Config Files

Overview

This page documents the on-host config layer for the EEM agent. 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.

Keys

Every key has a matching environment override under its primary name (for example EREBINE_AGENT_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 agent refuses to start if either is unset across CLI, environment, and file. join_key is needed only when the agent has no saved enrollment to restore.

Reload Semantics

Two things are read while the agent 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 agent 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.

Keys

Workspace credentials

A workspace that sets credentials_ref runs its credentialed tools on that one file and on nothing else on the host. The file lives at credentials_dir/<name>/<credentials_ref>, owned by the agent's account, mode 0600 or 0400, and not a symlink.

The 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 agent account's home or the agent's working directory is read.

• 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.
• Any other credentialed tool in a workspace that sets credentials_ref -- a cloud CLI, git, a database -- is refused with credential_binding_unsupported rather than run on the agent's own identity. So is every credentialed tool in a workspace of another type that sets one.
• A workspace without credentials_ref runs its tools on the agent's own identity: whatever its account and working directory reach. Two such workspaces on one agent share it. Run one agent 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:

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.

Reload and the default workspace

An edit takes effect without a restart, on two paths with different guarantees. Enforcement is immediate: the agent 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 agent enforces, so a stale catalogue can name a workspace the agent refuses, and can never grant one.

Without this file the agent 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 that exists but cannot be understood stops the agent rather than falling back. Silently ignoring a scope declaration is how a workspace ends up running unscoped.

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 key not listed here is carried through unchanged. The scope block is free-form on purpose, so a workspace type this page does not describe still works.

Code

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

Kubernetes

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

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 credentials_ref set, that is the workspace's own kubeconfig and no other; see Workspace credentials.

Docker / Podman / Container

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

Linux host

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

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 agent drives through the openstack command line. Runs on: Linux and macOS.

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 through credentials_ref, 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 agent host. Runs on: Linux and macOS.

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 agent 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 agent constructs it in-process from its registered tool descriptors and republishes on enrollment and every lease renewal. The router persists it server-side in agents.capability_manifest_json.

On-Disk Layout

Default layout on a production EEM host:

• /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 stderr by default. 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.