docs
// Execution Management (EEM)

Config Files

Two YAML files. eem.yaml configures the Erebine Execution Manager (EEM): CLI flags win, then environment variables (the primary name, EREBINE_EEM_*, then its legacy EEM_* spelling), then the file, then built-in defaults, flat scalars only. workspaces.yaml declares the workspaces the EEM serves, and takes effect without a restart.

Overview

This page documents the on-host config layer for the EEM. The Environment Variables reference covers the matching environment overrides; chat templates are project-scoped JSON managed through the router API and live under Author a Chat Template.

Keyboard: press Alt+E to jump to the next example block, Alt+Shift+E for the previous one. The chord ignores text inputs.

eem.yaml

Loaded from the path supplied by --config, default /etc/erebine/eem.yaml. A missing file is a legitimate "no config" signal, so flag-only and environment-only deployments work without an empty stub.

The file is a flat top-level mapping of scalars (string, integer, boolean). Nested maps and sequences are rejected at boot with invalidConfigFile. Keys are lowercased before lookup.

yaml
# required router_url: https://router.example.com registration_name: eem-prod-us-east-01 # first enrollment only join_key: jk_xxxxxxxxxxxxxxxxxxxxxxxx # optional (defaults shown) credentials_dir: /var/lib/erebine/credentials log_level: info lease_renewal_interval_ms: 10000 shutdown_grace_seconds: 30 max_concurrent_executions: 20 signing_key_path: /var/lib/erebine/agent-signing-key.hex curve_key_path: /var/lib/erebine/agent-curve-key.hex queue_db_path: /var/lib/erebine/state/queue.sqlite project_external_id: proj_optional_external_id allow_remote_declarations: false

Keys

Every key has a matching environment override under its primary name (for example EREBINE_EEM_JOIN_KEY, EREBINE_EEM_QUEUE_DB_PATH); the legacy EEM_* spelling is read only when the primary name is unset. The required keys, router_url and registration_name, have no default; the EEM refuses to start if either is unset across CLI, environment, and file. join_key is needed only when the EEM has no saved enrollment to restore.

KeyDefaultRequiredPurpose
router_url unset Yes HTTPS endpoint of the router used for enrollment and the data plane.
join_key unset First enrollment One-shot enrollment token issued by the router. The EEM redeems it only when there is no saved enrollment to restore: on the first start, when agent-enrollment.json (written beside the signing key) or one of the key files is missing or unreadable, or when the router no longer accepts the saved identity. In those cases it refuses to start without one. A key for another project than the saved enrollment's is redeemed too: the EEM enrolls into the key's project and logs that it did. Once the first enrollment succeeds, the key can be revoked and dropped from the file.
registration_name unset Yes Stable display name the router uses to track this EEM across restarts.
credentials_dir /var/lib/erebine/credentials No Directory holding one subdirectory per workspace. Each file a workspace's credentials map in workspaces.yaml names sits inside its own subdirectory. See Workspace credentials.
log_level info No Log verbosity. One of trace, debug, info, notice, warning, error.
lease_renewal_interval_ms 10000 No Cadence (milliseconds) for lease renewal messages to the router.
shutdown_grace_seconds 30 No Time the EEM waits for in-flight executions to finish on SIGTERM before forcing exit.
max_concurrent_executions 20 No Ceiling on simultaneous tool executions handled by the EEM.
signing_key_path /var/lib/erebine/agent-signing-key.hex No Persisted Ed25519 signing-key file used to sign messages to the router.
curve_key_path /var/lib/erebine/agent-curve-key.hex No Persisted Curve25519 key-agreement private-key file. The public half is derived on load.
queue_db_path /var/lib/erebine/state/queue.sqlite No SQLite file backing the outbound dispatch queue.
project_external_id unset No External project id (proj_<id>) attached to callbacks for project-scoped routing.
allow_remote_declarations false No true lets project owners and operators add and remove this EEM's workspaces from its settings or erectl eems add-workspace, which rewrites workspaces.yaml. A new workspace takes its scope and credentials from the project and its domains from its types, and one of a type the EEM does not know is refused; an existing one keeps the scope and domains in the file.

Reload Semantics

eem.yaml and the environment are read once, at start. A change to either takes effect on the next restart. There is no reload signal: the EEM traps SIGTERM and SIGINT, and both stop it.

Two things are read while the EEM runs, so a change to them needs no restart:

  • workspaces.yaml, on every tool call and every lease renewal. See workspaces.yaml for when the router's catalogue catches up.
  • A credential file under credentials_dir, by the call that uses it, so a replaced file is used from the next call. A call already running keeps the credential it read.

The paths to both are settings. Moving workspaces.yaml or the credentials directory is a restart.

workspaces.yaml

The EEM cannot learn which workspaces it serves. Enrollment hands it an identity, addresses and a token, and no workspace list, so the operator declares them. The name of each declaration must equal the workspace's name in your project: that string is the only thing the router matches a declaration against. A name that matches nothing binds nothing, and it does it quietly.

Declarations live in their own file because eem.yaml accepts flat scalars only, and a scope block is nested. Default location /etc/erebine/workspaces.yaml, overridden by EREBINE_EEM_WORKSPACES_FILE.

yaml
workspaces: - name: homelab # must equal the workspace name in your project types: [kubernetes, openstack] description: Lab cluster and its cloud domains: [kubernetes, openstack] scope: namespaces: [default, kube-system] rate_per_minute: 10 enabled_services: [nova, neutron] limits: max_concurrent_executions: 4 credentials: kubernetes: homelab-kubeconfig openstack: homelab-appcred

Keys

KeyRequiredPurpose
name Yes The workspace's name in your project. The only axis a declaration binds on.
types Yes A list of one or more of the six types below, in display order. The scope block takes the keys of every type listed, and a new declaration takes the domains of every type listed. A type outside the six fails the file when it is read.
description No Free text carried to the catalogue so a caller can tell two workspaces apart.
domains No The tool domains this workspace admits. A tool whose domain is outside the list is neither advertised for the workspace nor run in it. Absent or empty, it narrows nothing, and the EEM-wide EREBINE_EEM_DOMAINS gate still applies on top. erectl, the desktop app and a workspace added remotely (allow_remote_declarations) write a new declaration with the domains its types serve (linux and shell for a linux workspace, both lists for a workspace of two types) and never change the list of one already in the file; erectl workspaces declare --domains sets it explicitly. A type Erebine does not describe has no domains to write, so erectl refuses one without --domains.
scope No The type-specific block. See the scope reference below.
decider_approvals No allow (the default) or refuse. With refuse the EEM refuses a call in this workspace that the project's decider approved under an auto approval policy; a call a person approved runs as before, and the project waits for a person instead of asking the decider. Any other value fails validation. erectl workspaces declare --decider-approvals and the desktop app's workspaces sheet set it, and a refresh keeps it.
allow_autonomous No false (the default) or true. true is this host's consent to autonomous trust for the workspace: when the project's owner also turns autonomous trust on for it, a call in the workspace that needs approval runs with no person, unless it is irreversible or in the database domain. Without this key the EEM refuses such a call, so a person decides it. Any value but a boolean fails validation. Only this file sets it: a workspace the router declares on the EEM is written without it, and a refresh keeps the value here. erectl workspaces declare --allow-autonomous and the desktop app's workspaces sheet write it; turning it off removes the key. It takes effect on the next call. See Autonomous trust.
limits.max_concurrent_executions No Per-workspace ceiling on simultaneous tool calls, under the EEM-wide max_concurrent_executions. A call that arrives while the workspace is at its ceiling is refused, not queued. Absent, only the EEM-wide ceiling applies.
credentials No A map from credential family to one file name, with no /, in credentials_dir/<name>/. The families whose tools read the file are kubernetes, openstack and git_token; a tool of one of them runs on its file. Once the map names any family, every other credentialed tool is refused rather than run on the EEM's own account, including a tool of a family the map names whose tools do not read a file yet. See Workspace credentials. The credential material never leaves the host.

Workspace credentials

A workspace binds at most one file per credential family, under credentials, and runs each credentialed tool on the file of that tool's family and on nothing else on the host. One workspace can drive a cluster on a kubeconfig and a cloud on a clouds.yaml. Each file lives at credentials_dir/<name>/<file>, owned by the EEM's account, mode 0600 or 0400, and not a symlink.

FamilyThe file isThe tools get
kubernetes A kubeconfig. Its current context picks the cluster, namespace default and user. KUBECONFIG naming the file. kubectl and helm read it and no other kubeconfig; there is no in-cluster fallback.
openstack A clouds.yaml holding exactly one cloud under clouds. That cloud's auth block picks the project. OS_CLIENT_CONFIG_FILE naming the file and OS_CLOUD naming its one cloud. No other clouds.yaml or secure.yaml is read.
git_token A git token on one line, such as a GitHub or GitLab personal access token. git_push to an https remote sends it as HTTP Basic authentication, user x-access-token, to that remote's push URL only, for that one push. It is never on the command line or on disk, and it is masked in what the push returns. An ssh or local remote pushes on the EEM account's own ssh agent or credentials. gh_pr_list and gh_pr_create get it for that one call, never on the command line or on disk, masked in what they return: as GH_ENTERPRISE_TOKEN, with GH_HOST pinning gh to that host, when the workspace's repository pushes origin to a GitHub Enterprise Server host and origin is in allowed_remotes; otherwise as GH_TOKEN, which gh uses for github.com, and an Enterprise Server host uses the EEM account's own gh login. The workspace's repository is a declared root; without a repo argument gh runs in the first one. The gh tools are in the git domain, so list git in the workspace's domains to run them there. Commits take their author and signing from the EEM account's git config.

A kubeconfig or clouds.yaml client runs with only those variables, a fixed PATH, and an empty private home directory that is also its working directory, so nothing in the EEM account's home or the EEM's working directory is read. A kubeconfig exec credential plugin runs the same way, so anything it reads from its environment or home directory, such as a profile name or a config file path, goes in that user's exec env block in the kubeconfig.

  • A file that is missing, empty, a symlink, or readable by group or other refuses the call with credential_unavailable before anything runs. So does a clouds.yaml that does not hold exactly one cloud.
  • Once a workspace binds any family, a credentialed tool of a family it does not bind -- a cloud CLI, a database, a cluster tool in a workspace that binds only a git token -- is refused with credential_binding_unsupported, which names the families bound, rather than run on the EEM's own identity.
  • A workspace without credentials runs its tools on the EEM's own identity: whatever its account and working directory reach. Two such workspaces on one EEM share it. Run one EEM per credential boundary, or bind each workspace.

Generating the file

Write it with erectl rather than by hand, so the names come from your project and cannot be mistyped:

bash
erectl workspaces declare --workspace prod-k8s --workspace erebine-repo erectl workspaces declare --workspace prod-k8s --stdout # preview erectl workspaces declare --workspace bastion --domains linux,shell erectl workspaces declare --remove old-cluster

On the EEM's own host, run it as root. With no personal key there that can see operational workspaces, erectl reads your project as this EEM, with the EEM's own identity on the host, and is shown only the workspaces this EEM serves: the ones bound to it, and the ones it alone declares. Bind the EEM to a new workspace first, from its EEM screen in the web UI, then declare it. The file keeps the owner, group and mode it had, so the EEM can still change it when you add or remove a workspace from the web UI, and a credential file the declaration names that is missing on the host is named in the notes.

The desktop app's New code workspace writes it too: see Desktop Execution Manager.

A refresh keeps the scope already in the file. Narrowing is local work and the project's copy is the wider one, so taking it is opt-in through --reseed-scope. Host-specific values -- a code workspace's repo_roots -- are set on the host that runs the work, and a refresh never removes them.

Writing the file rewrites the document through a YAML parser. Comments, blank lines and key order do not survive. Keep notes somewhere the command does not write.

Converting an older file

A file written before workspaces took several types names one type and at most one credentials_ref per workspace. The EEM no longer reads it: it refuses the file and logs the command that writes it again, naming every workspace the file declares. Run that command on the host; declare writes the file fresh from your project for the workspaces you name, and lists any declaration of the older file you did not name, which it drops:

bash
sudo erectl workspaces declare --workspace prod-k8s --workspace bastion --stdout # preview sudo erectl workspaces declare --workspace prod-k8s --workspace bastion # write it

Settings that lived only in the older file, such as a narrowed scope, domains or a code workspace's repo_roots, are not carried over: set them again with the declare flags or in the file.

A declaration whose name is not kebab-case is refused before anything is written: rename the workspace in your project first with erectl workspaces update <id> --name <name>. To give a workspace a second type or credential, set it on the workspace (erectl workspaces update <id> --type kubernetes,openstack --credential openstack=homelab-appcred), put the file in the workspace's credentials directory, and declare it again.

Reload and the default workspace

An edit takes effect without a restart, on two paths with different guarantees. Enforcement is immediate: the EEM rebuilds its manifest from this file on every tool call, so narrowing a scope or removing a workspace binds the very next call. The catalogue converges within about a lease interval (10 seconds by default): the router is told the manifest changed and asks for the new one. The catalogue is what the router offers callers and never what the EEM enforces, so a stale catalogue can name a workspace the EEM refuses, and can never grant one.

Without this file the EEM declares a single workspace named local with an empty scope. That workspace can only match a workspace literally named local, and it delivers no scope to any tool, so a code workspace will not work until you declare one here. A file that exists but declares nothing is not the same thing: it declares zero workspaces and drops the local fallback with them.

A file the parser cannot read -- not YAML, no workspaces list, a declaration without a name or types, a type outside the six, a credential family Erebine does not know -- stops the EEM rather than falling back. Inside a declaration the EEM is lenient: a scope that is not a mapping is read as empty, and the EEM does not check scope keys or values. erectl workspaces declare and the desktop app check them when they write the file. An empty or whitespace-only file is read as no file.

Workspace Scope

Six types, each with its own scope block. Every key listed below is enforced: a tool reads it and refuses work outside it, before it runs anything.

The If absent column is the one to read first, because it says what a key you have not written does. Nothing changes means the key narrows something the tools already do, so leaving it out leaves them as they are. Tools refuse means the key grants something the tools cannot do without it -- a path, a pod, a command, a directory -- so leaving it out turns those tools off until you declare it. Silence never grants anything.

Any scope key not listed here is carried through unchanged. A workspace of several types takes the keys of each, and a key two types share is read once.

Code

Type code. A checkout on the EEM host that the code tools may read, edit and build. Runs on: Linux and macOS.

KeyValueDefaultIf absentPurpose
repo_roots (required)list of absolute paths-Tools refuseAbsolute paths the code tools may touch; every other path is refused. The EEM's own files are refused under any root, as under allowed_paths; a repository's own agents.env or eem.env is an ordinary file unless the EEM cannot tell its own env files from it.
denied_pathslist of patterns-Nothing changesPatterns carved back out of the roots, matched case insensitively against the basename when the pattern has no slash.
max_file_byteswhole number of bytes8388608Nothing changesLargest file the code tools will read, or leave behind after a write, edit or patch, in bytes.
max_write_byteswhole number of bytes262144Nothing changesMost bytes one write may add: a code_write's content, a code_edit's replacement text, a patch's added lines. A large file still takes a small edit.
allowed_build_commandsname to command line-Tools refuseNamed command lines the build tool may run; a caller names one and cannot supply its own.
allowed_test_commandsname to command line-Tools refuseNamed command lines the test tool may run.
allowed_format_commandsname to command line-Tools refuseNamed command lines the format tool may run.
allowed_lint_commandsname to command line-Tools refuseNamed command lines the lint tool may run.
git_push_allowedtrue or falsefalseTools refuseWhether the git tool may push at all; anything but true refuses.
protected_brancheslist of patterns-Nothing changesBranch patterns a push may never target, matched case sensitively.
allowed_remoteslist of textoriginTools refuseRemote names a push may target. Absent, only origin; an empty list, none.
rate_per_minutewhole number of requests a minute-Nothing changesRequests a minute this workspace admits, counted by the router before a call reaches the EEM. Absent, the deployment-wide setting applies, and then the per-domain default.
user_rate_per_minutewhole number of requests a minute, or null-Nothing changesPer-caller share of the workspace ceiling, counted by the router; null means no separate per-caller limit. Absent, the deployment-wide setting applies.

git and the build, test, format and lint commands run with a fixed PATH (/opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin, /usr/sbin, /sbin, those that exist) and with HOME, USER, LANG, TMPDIR and SSH_AUTH_SOCK from the EEM's own environment. Nothing else of that environment reaches them. git therefore reads the EEM account's ~/.gitconfig: commits carry that user's name, email and signing settings, and a push uses that user's credential helper or ssh agent. A build tool installed anywhere else is named by absolute path in the command line. The GitHub tools run gh in the same environment, so gh finds git and, unless the workspace binds a git token, uses the EEM account's own gh auth login.

Repository metadata configures what git does later, so writing it needs approval. code_write, code_edit, code_multi_edit and code_patch_apply refuse any path in it: a .git directory or file at any depth, and a git directory wherever it sits, such as the one a worktree's or submodule's .git file names, or a bare repository. They also refuse git's own configuration in the EEM account's home directory (~/.gitconfig and ~/.config/git) when repo_roots covers it. A case variant such as .GIT counts. code_write_repo_metadata writes, edits or patches there instead, within the same repo_roots, denied_paths and max_write_bytes. Its risk is destructive, so every call waits for an owner's approval. The read tools still read metadata.

Unless the workspace is under autonomous trust, the git tools run no program that a repository's own configuration names: no hook, fsmonitor, filter, diff or merge driver, and no signing, ssh, credential or askpass program the repository sets. The signing program, ssh command and credential helpers the EEM account's own configuration names still run. Filter and merge drivers do not run at all, so git_add refuses a file that needs a filter, such as a Git LFS file, and the other git tools read and restore such a file without one. git_status and git_diff do not report uncommitted changes inside a submodule, and a push to a repository on the same machine is refused. The git tools need git 2.31 or later.

Kubernetes

Type kubernetes. Clusters the EEM drives through the kubectl, helm and kustomize command line. Runs on: Linux and macOS.

KeyValueDefaultIf absentPurpose
namespaceslist of text-Nothing changesNamespaces a call may target, matched case insensitively against the namespace the tool is about to pass. Most tools put default on the command line when the call omits the argument, so an omitted namespace is checked as default; declare it, or pass a namespace. k8s_apply_manifest, k8s_apply_from_file and helm_history pass no namespace at all when the call omits one, which would leave the target to the current context of the kubeconfig on the EEM host, and helm_list and k8s_top_cluster read every namespace: while this key is set those are refused, because neither answer is inside a list. Absent, it narrows nothing.
enabled_resource_kindslist of text-Nothing changesResource kinds a call may touch. Each tool's kind is known without asking the cluster: a fixed-kind tool carries it, k8s_delete_resource takes it as kind, and k8s_wait and the k8s_rollout_* tools take it as the part of resource before the slash. Spellings are compared after lowercasing and dropping the API group, so Pod, pod, pods, po and pods. are one kind, and deploy and Deployment.apps are deployments. A kind outside the built-in table is matched literally, so a custom resource works when both sides spell it the same way; relating two spellings of one would mean asking the cluster. Absent, it narrows nothing.
kube_manifest_pathslist of absolute paths-Tools refuseDirectories on the EEM host that hold appliable manifests. k8s_apply_from_file refuses any path outside them, and refuses every path while this key is absent. Each entry must be absolute, and a path that leaves a directory through a symbolic link is refused rather than followed.
kustomize_pathslist of absolute paths-Tools refuseDirectories that hold kustomize overlays. kustomize_build refuses any directory outside them, and refuses every directory while this key is absent. An omitted directory means the first entry, and a relative one is resolved against it.
exec_allowed_podslist of patterns-Tools refusePod name patterns k8s_exec may open a shell in, matched case insensitively against the name the call passes. While this key is absent no pod is permitted.
exec_allowed_commandslist of text-Tools refuseBinaries k8s_exec may run, matched against the first element of the command argv exactly as passed, so /bin/sh and sh are separate entries. While this key is absent no command is permitted. Nothing after the first element is checked, and it does not need to be: kubectl exec runs the argv directly with no shell between, so a separator is an argument rather than a second command. A shell listed here allows everything that shell can run.
scale_replica_capwhole number of replicas-Nothing changesLargest replica count k8s_scale_deployment may ask for. Absent, the count is unbounded.
rate_per_minutewhole number of requests a minute-Nothing changesRequests a minute this workspace admits, counted by the router before a call reaches the EEM. Absent, the deployment-wide setting applies, and then the per-domain default.
user_rate_per_minutewhole number of requests a minute, or null-Nothing changesPer-caller share of the workspace ceiling, counted by the router; null means no separate per-caller limit. Absent, the deployment-wide setting applies.

Four of these keys refuse when they are absent. A kubernetes workspace that declares no exec_allowed_pods and no exec_allowed_commands cannot run k8s_exec at all; one that declares no kube_manifest_paths cannot run k8s_apply_from_file; one that declares no kustomize_paths cannot run kustomize_build. Each of those tools takes a pod, a command or a filesystem path straight from the caller, so an undeclared key is a grant rather than a narrowing, and a grant nobody wrote grants nothing. Declare the four keys to restore the tools. namespaces, enabled_resource_kinds and scale_replica_cap stay open when absent, because each narrows something the tools are meant to do rather than granting it.

Declaring namespaces changes what an omitted namespace means. It has to: a list that still admitted "whatever the kubeconfig's current context says" or "every namespace" would not be a narrowing. Most calls are unaffected, because most tools put default on the command line themselves and that is simply checked. The ones that change are k8s_apply_manifest, k8s_apply_from_file and helm_history, which pass no namespace when the call omits one, and helm_list and k8s_top_cluster, which read across every namespace. Pass a namespace from the list; for k8s_top_cluster, which takes none, use k8s_top_pods.

k8s_apply_manifest is the one tool whose target is in the body rather than in an argument, since a document carries its own metadata.namespace. While either narrowing key is set the body is parsed and every document is checked: multi-document YAML, JSON and a List wrapper are all read, a document that names a namespaced kind with no namespace in it and none on the call is refused, and a body that is not valid YAML or JSON is refused rather than passed through. Kinds Kubernetes puts outside any namespace, such as Namespace and ClusterRole, are not bounded by namespaces, because nothing can bound them. With neither key set nothing is parsed and the tool behaves exactly as before.

No key bounds which cluster a call reaches. No tool in the bundle takes a context or a cluster argument and none passes --context, so the cluster is decided entirely by the current context of the kubeconfig the tool runs on. With a kubernetes credential bound, that is the workspace's own kubeconfig and no other; see Workspace credentials.

Docker / Podman / Container

Type container. Containers on the EEM host, through whichever of docker, podman or container is installed. Runs on: Linux and macOS.

KeyValueDefaultIf absentPurpose
runtimeone of auto, docker, podman, containerautoNothing changesWhich container runtime to drive; auto takes the first one found on the host, trying container, then docker, then podman on macOS, and podman then docker on Linux. Apple's container is the Mac's native runtime, so auto prefers it there; it is considered on macOS only, and a named runtime that is not installed is refused rather than substituted.
allowed_registrieslist of text-Nothing changesRegistries container_image_pull may pull from, matched against the registry the reference itself names. While this key is set a reference that names none is refused, because what a bare name resolves to is the runtime's own configuration and not part of the reference: write docker.io/library/nginx rather than nginx. Absent, it narrows nothing.
allowed_containerslist of patterns-Nothing changesContainers container_start, container_stop, container_restart and container_rm may touch. Matched against the ID or name exactly as the caller passes it; an ID is never resolved to a name, so list the form your callers use. Absent, it narrows nothing.
allowed_imageslist of patterns-Nothing changesImages container_image_pull and container_image_rm may touch, matched against the reference exactly as passed, tag and digest included. Absent, it narrows nothing.
rate_per_minutewhole number of requests a minute-Nothing changesRequests a minute this workspace admits, counted by the router before a call reaches the EEM. Absent, the deployment-wide setting applies, and then the per-domain default.
user_rate_per_minutewhole number of requests a minute, or null-Nothing changesPer-caller share of the workspace ceiling, counted by the router; null means no separate per-caller limit. Absent, the deployment-wide setting applies.

Linux host

Type linux. A Linux host the EEM inspects and manages through systemd, the journal and the standard utilities. Runs on: Linux only.

KeyValueDefaultIf absentPurpose
shell_runas_userlist of text-Tools refuseAccounts a shell command may be run as; without this key every run-as request is refused. Account names are compared exactly, because a Unix account name is case-sensitive.
allowed_pathslist of absolute paths-Tools refuseAbsolute directories the twelve path-taking host tools may work under; every path argument must resolve inside one, a relative argument is refused rather than guessed at, and a symlink below a root is refused rather than followed. Without this key none of those tools runs. A process's environment or command line under /proc, /etc/erebine, the EEM's own key, enrollment, workspaces and deploy env files, its credentials directory with everything in it, and the enrollment of an EIM on the same host are refused whatever this key declares, as is a file named eem.env, eem.local.env, agents.env, agents.local.env, agent-signing-key.hex, agent-curve-key.hex or agent-enrollment.json in the directories that hold them. An EEM started without EREBINE_EEM_DEPLOY_DIR, other than the desktop app's, cannot tell its own env files from a project's and refuses those names in every directory.
denied_pathslist of patterns-Nothing changesPatterns carved back out of the allowed paths; a denial beats an allowance. Matched against the whole absolute path, and a pattern with no slash is also matched against the file name alone, so *.pem means pem files anywhere under the roots and /etc/* means that directory. Absent, it narrows nothing.
allowed_commandslist of text-Nothing changesBinary names, such as systemctl or df, that the host tools may run; each tool is checked against the binary it is built to invoke, so the entries are names and not paths (dmesg reading the journal is checked as journalctl). It does not inspect what a shell command line contains, so it places no limit on shell_exec_irreversible. Absent, it narrows nothing.
rate_per_minutewhole number of requests a minute-Nothing changesRequests a minute this workspace admits, counted by the router before a call reaches the EEM. Absent, the deployment-wide setting applies, and then the per-domain default.
user_rate_per_minutewhole number of requests a minute, or null-Nothing changesPer-caller share of the workspace ceiling, counted by the router; null means no separate per-caller limit. Absent, the deployment-wide setting applies.

A linux workspace with no allowed_paths loses twelve tools. linux_file_read, linux_file_stat, linux_file_hash, linux_directory_list, linux_directory_size, linux_find_files, linux_chmod, linux_chown, linux_cp, linux_mv, linux_tar_create and linux_tar_extract take an absolute host path from the caller, and a key that bounds a caller-supplied path grants nothing when it is absent. Declare the directories the workspace is for, for example allowed_paths: ["/srv/app", "/var/log"]. Every other linux tool is unaffected: nothing else in the bundle takes a path.

OpenStack

Type openstack. An OpenStack cloud the EEM drives through the openstack command line. Runs on: Linux and macOS.

KeyValueDefaultIf absentPurpose
enabled_serviceslist of text-Nothing changesServices these tools may reach: nova, cinder, neutron, glance or heat. No tool takes a service argument, so each one is checked against the service its own command addresses and the refusal happens before a command line is built. The service is the one the call is routed to rather than the resource in the tool's name: openstack_volume_attach runs server add volume, so it needs nova. Absent, it narrows nothing.
heat_template_pathslist of absolute paths-Tools refuseAbsolute directories openstack_stack_create may read its template and environment files from; both must resolve inside one, a relative argument is refused rather than guessed at, and a symlink below a root is refused rather than followed. Without this key no stack is created.
server_create_flavor_allowlistlist of text-Nothing changesFlavors openstack_server_create and openstack_server_resize may name, compared exactly. Absent, it narrows nothing.
server_create_image_allowlistlist of text-Nothing changesImages openstack_server_create may boot, compared exactly. Absent, it narrows nothing.
server_create_network_allowlistlist of text-Nothing changesNetworks openstack_server_create may attach to, and pools openstack_floatingip_create may allocate an address from, compared exactly. Absent, it narrows nothing.
image_source_pathslist of absolute paths-Tools refuseAbsolute directories openstack_image_upload may read its file from, under the same containment and symlink rules. Without this key no image is uploaded.
rate_per_minutewhole number of requests a minute-Nothing changesRequests a minute this workspace admits, counted by the router before a call reaches the EEM. Absent, the deployment-wide setting applies, and then the per-domain default.
user_rate_per_minutewhole number of requests a minute, or null-Nothing changesPer-caller share of the workspace ceiling, counted by the router; null means no separate per-caller limit. Absent, the deployment-wide setting applies.

An openstack workspace with no heat_template_paths creates no stacks, and one with no image_source_paths uploads no images. template, environment and file are absolute host paths straight from the caller, and the client reads every byte behind them, so each key is a grant rather than a narrowing, and a grant nobody wrote grants nothing. Declare the directories the workspace owns, for example heat_template_paths: ["/opt/heat-templates"], to restore those two tools. The other 33 are unaffected: nothing else in the bundle takes a path.

No key names which project a call acts in. The project comes from the one cloud in the clouds.yaml the workspace binds as its openstack credential, not from any tool argument; see Workspace credentials. The project argument on openstack_server_list filters a listing and cannot widen one. Nothing bounds key_name either, so a caller may inject any keypair the project holds.

Infrastructure as code

Type iac. Terraform working directories on the EEM host. Runs on: Linux and macOS.

KeyValueDefaultIf absentPurpose
workspace_dirslist of absolute paths-Tools refuseDirectories the terraform tools may run in. Every call must name a directory at or below one of them, and while this key is absent no directory is permitted, so none of the four tools runs. Each entry must be absolute. Containment compares whole components, so /srv/terraform-scratch is outside /srv/terraform, and a directory that is or sits below a symbolic link is refused rather than followed.
rate_per_minutewhole number of requests a minute-Nothing changesRequests a minute this workspace admits, counted by the router before a call reaches the EEM. Absent, the deployment-wide setting applies, and then the per-domain default.
user_rate_per_minutewhole number of requests a minute, or null-Nothing changesPer-caller share of the workspace ceiling, counted by the router; null means no separate per-caller limit. Absent, the deployment-wide setting applies.

An iac workspace that declares no workspace_dirs runs no terraform at all. terraform_plan, terraform_apply, terraform_output and terraform_state_list all refuse until the key is declared. The directory argument is a filesystem path straight from the caller, and terraform in a directory is terraform against whatever real infrastructure that directory's state binds, so the key is a grant rather than a narrowing, and a grant nobody wrote grants nothing. Declare the absolute paths the workspace owns, for example workspace_dirs: ["/srv/terraform/prod"], to restore the tools.

All four tools now require a directory, and it must be absolute. It used to be optional, and an omitted one ran terraform in whichever directory the EEM process was started in. Nothing took that default's place: a workspace may declare several directories, and applying, or reading the state of, the wrong one is somebody else's infrastructure rather than a wrong answer. A relative path is refused on the same reasoning, since the only base it could have had is a guess.

What the key bounds is the directory terraform runs in, and that is the whole promise. It does not bound what terraform then reads: a var_file argument is passed through untouched, and which providers, modules and remote state a configuration pulls in is terraform's own resolution. Three keys that read as wider promises were removed rather than left in place. allowed_providers would need the configuration parsed and terraform's provider resolution reproduced. plan_before_apply asserts that an earlier plan saw the same files, which one call cannot know. targeted_destroy_only named a destroy tool that does not exist.

terraform_apply always runs apply -auto-approve -input=false -no-color. No argument and no scope key adds a plan gate in front of it; what gates it is the approval policy for its destructive risk class. The auto_approve argument it used to advertise was ignored and has been removed, for the same reason plan_before_apply was: a brake that is not connected is worse than no brake.

Capability Manifest

The capability manifest is not an operator-edited file. The EEM constructs it in-process from its registered tool descriptors and republishes on enrollment and every lease renewal. The router persists it server-side.

The manifest is the allowlist. The router rejects any tool call not present in the published manifest. Editing a file named manifest.json on the EEM host has no effect on the published manifest.

Wire shape (internal reference)

The fields below are the on-wire JSON shape. Operators do not author these; the EEM emits them.

FieldPurpose
schema_versionManifest schema revision.
agent_idStable EEM identifier assigned at enrollment.
display_nameOperator-visible name; mirrors registration_name.
descriptionShort free-text description supplied by the tool bundle.
shared_limitsObject with max_concurrent_executions_total, max_execution_timeout_ms, max_result_size_bytes.
workspaces[]Workspaces the EEM is bound to.
tools[]Flat array; each tool carries name, domain, description, parameters_schema, risk (level, requires_approval, reversible, optional reversal_tool), credential_type, timeout_ms, idempotent, and the workspaces it applies to.

On-Disk Layout

Default layout on a Linux host. On macOS the EEM uses ~/.config/erebine/ for configuration and ~/.local/state/erebine/ for state.

tree
/etc/erebine/ eem.yaml workspaces.yaml /var/lib/erebine/ agent-signing-key.hex agent-curve-key.hex agent-enrollment.json credentials/ <workspace>/ <file> # one per credential family it binds state/ queue.sqlite queue.sqlite-wal queue.sqlite-shm
  • /var/lib/erebine/ must live on a persistent volume. The dispatch queue is not useful if the filesystem is ephemeral.
  • The Curve25519 public half is derived from the private key on load; there is no separate .public file.
  • Logs go to standard output, at every level. Routing to journald, rsyslog, or a file is the operator's responsibility. See Deploy EEM on a Jumphost for a systemd unit and a compose override.

Further Reading