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.
# 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.
| Key | Default | Required | Purpose |
|---|---|---|---|
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.
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
| Key | Required | Purpose |
|---|---|---|
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.
| Family | The file is | The 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_unavailablebefore 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
credentialsruns 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:
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:
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.
| Key | Value | Default | If absent | Purpose |
|---|---|---|---|---|
repo_roots (required) | list of absolute paths | - | Tools refuse | Absolute 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_paths | list of patterns | - | Nothing changes | Patterns carved back out of the roots, matched case insensitively against the basename when the pattern has no slash. |
max_file_bytes | whole number of bytes | 8388608 | Nothing changes | Largest file the code tools will read, or leave behind after a write, edit or patch, in bytes. |
max_write_bytes | whole number of bytes | 262144 | Nothing changes | Most 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_commands | name to command line | - | Tools refuse | Named command lines the build tool may run; a caller names one and cannot supply its own. |
allowed_test_commands | name to command line | - | Tools refuse | Named command lines the test tool may run. |
allowed_format_commands | name to command line | - | Tools refuse | Named command lines the format tool may run. |
allowed_lint_commands | name to command line | - | Tools refuse | Named command lines the lint tool may run. |
git_push_allowed | true or false | false | Tools refuse | Whether the git tool may push at all; anything but true refuses. |
protected_branches | list of patterns | - | Nothing changes | Branch patterns a push may never target, matched case sensitively. |
allowed_remotes | list of text | origin | Tools refuse | Remote names a push may target. Absent, only origin; an empty list, none. |
rate_per_minute | whole number of requests a minute | - | Nothing changes | Requests 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_minute | whole number of requests a minute, or null | - | Nothing changes | Per-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.
| Key | Value | Default | If absent | Purpose |
|---|---|---|---|---|
namespaces | list of text | - | Nothing changes | Namespaces 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_kinds | list of text | - | Nothing changes | Resource 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_paths | list of absolute paths | - | Tools refuse | Directories 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_paths | list of absolute paths | - | Tools refuse | Directories 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_pods | list of patterns | - | Tools refuse | Pod 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_commands | list of text | - | Tools refuse | Binaries 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_cap | whole number of replicas | - | Nothing changes | Largest replica count k8s_scale_deployment may ask for. Absent, the count is unbounded. |
rate_per_minute | whole number of requests a minute | - | Nothing changes | Requests 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_minute | whole number of requests a minute, or null | - | Nothing changes | Per-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.
| Key | Value | Default | If absent | Purpose |
|---|---|---|---|---|
runtime | one of auto, docker, podman, container | auto | Nothing changes | Which 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_registries | list of text | - | Nothing changes | Registries 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_containers | list of patterns | - | Nothing changes | Containers 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_images | list of patterns | - | Nothing changes | Images 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_minute | whole number of requests a minute | - | Nothing changes | Requests 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_minute | whole number of requests a minute, or null | - | Nothing changes | Per-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.
| Key | Value | Default | If absent | Purpose |
|---|---|---|---|---|
shell_runas_user | list of text | - | Tools refuse | Accounts 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_paths | list of absolute paths | - | Tools refuse | Absolute 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_paths | list of patterns | - | Nothing changes | Patterns 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_commands | list of text | - | Nothing changes | Binary 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_minute | whole number of requests a minute | - | Nothing changes | Requests 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_minute | whole number of requests a minute, or null | - | Nothing changes | Per-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.
| Key | Value | Default | If absent | Purpose |
|---|---|---|---|---|
enabled_services | list of text | - | Nothing changes | Services 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_paths | list of absolute paths | - | Tools refuse | Absolute 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_allowlist | list of text | - | Nothing changes | Flavors openstack_server_create and openstack_server_resize may name, compared exactly. Absent, it narrows nothing. |
server_create_image_allowlist | list of text | - | Nothing changes | Images openstack_server_create may boot, compared exactly. Absent, it narrows nothing. |
server_create_network_allowlist | list of text | - | Nothing changes | Networks openstack_server_create may attach to, and pools openstack_floatingip_create may allocate an address from, compared exactly. Absent, it narrows nothing. |
image_source_paths | list of absolute paths | - | Tools refuse | Absolute 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_minute | whole number of requests a minute | - | Nothing changes | Requests 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_minute | whole number of requests a minute, or null | - | Nothing changes | Per-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.
| Key | Value | Default | If absent | Purpose |
|---|---|---|---|---|
workspace_dirs | list of absolute paths | - | Tools refuse | Directories 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_minute | whole number of requests a minute | - | Nothing changes | Requests 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_minute | whole number of requests a minute, or null | - | Nothing changes | Per-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.
| Field | Purpose |
|---|---|
schema_version | Manifest schema revision. |
agent_id | Stable EEM identifier assigned at enrollment. |
display_name | Operator-visible name; mirrors registration_name. |
description | Short free-text description supplied by the tool bundle. |
shared_limits | Object 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.
/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
.publicfile. - 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
- EEM Environment Variables - the environment override layer for every key above.
- Deploy EEM on a Jumphost - a systemd unit and a compose override.
- Author a Chat Template - project- and workspace-scoped JSON managed via the router API.