Config reference, lever.yaml

A lever application is described by a single config file. It declares the manager agent and the workers (project agents) it orchestrates, plus how the jail is built around them.

The canonical filename is lever.yaml, placed at the instance root. The root holds the config and the boot prompt and is NOT mounted; only a tree: subdirectory is bind-mounted into the jail. This keeps the config out of the agent-writable mount, a compromised agent can’t rewrite the config the host trusts on the next bring-up.

Config is resolved from the current directory only, there is deliberately no walk-up discovery. Run lever from the instance root (where lever.yaml lives), or pass an explicit config path. A lever.yaml planted in a parent directory can therefore never be picked up. See security-model §5.

Layout

my-instance/             <- instance root: run `lever` here; NOT mounted
  lever.yaml             <- the config
  prompt.md              <- boot prompt (host-only)
  workspace/             <- tree: the bind-mounted subdir (agents edit this)
    workers/...

lever-manager, the in-jail orchestration binary, isn’t staged in the tree, it’s baked into the agent image (make lever-image-bins + your Dockerfile’s COPY … /usr/local/bin/lever-manager), so it’s already on PATH when the manager container boots.

Minimal config

tree: is required and must be a confined subdirectory. api-key is the default LLM-auth mode, so a real Console key (broker.api_key_file, 0600) is required unless you opt into subscription:

name: myapp
backend: orbstack
tree: workspace
manager:
  image: lever.local/lever-claude
broker:
  api_key_file: ~/.secrets/anthropic-key   # required by the default api-key mode

To use your Claude OAuth token instead (the real token is projected into the agents), opt into subscription and drop api_key_file:

name: myapp
backend: orbstack
tree: workspace
broker:
  llm_auth: subscription
manager:
  image: lever.local/lever-claude
  credential_file: ~/.scion/oauth-token    # 0600; projected to the agents

Providing the Console key

api_key_file must hold a real Anthropic Console key (sk-ant-...), created at console.anthropic.com → API Keys. That’s a different credential from the Claude subscription OAuth token used in subscription mode (manager.credential_file, above) — a Console key is billed per-token via the API, not tied to your Claude.ai session.

Local host. Write it straight to the api_key_file path at 0600, without it ever touching your shell history or argv:

umask 077 && mkdir -p ~/.secrets
read -rs key && printf '%s' "$key" > ~/.secrets/anthropic-key && unset key

read -rs reads the key from stdin without echoing it or putting it in a command line; umask 077 means the file > creates lands 0600 immediately, satisfying the permission check below. (Any editor works too, as long as you set the mode afterwards: chmod 600 ~/.secrets/anthropic-key.)

Remote host. Pipe the key over ssh so it never touches the remote shell history or a world-readable temp file:

pbpaste | ssh user@remote-host 'umask 077; mkdir -p ~/.secrets; cat > ~/.secrets/anthropic-key'

The key travels over the ssh channel only, never as an argument or a remote shell variable; umask 077 on the remote side is what makes the file cat writes land 0600 before lever apply’s permission check sees it. Swap pbpaste for however you get the key into your local pipe (cat ~/.secrets/anthropic-key, a password manager’s CLI, etc).

Rotation. Overwrite the file (keep it 0600) and re-run lever apply/lever up — the key is read once when the broker process starts, not per request, so a broker already running keeps using the key it started with until it’s restarted.

Full example

name: assistant                      # instance identity -> jail machine "lever-assistant"
backend: orbstack                    # containment backend
tree: workspace                      # bind-mounted SUBDIR (the root is not mounted)
egress: closed                       # seal the jail to the broker only (api-key instances only)
scion:
  version: 65531d7f                  # pin a scion commit; a lever release ships this one prebuilt
manager:
  image: lever.local/lever-claude
  # image_tar: images/lever-claude.tar   # optional; ship the image as a docker archive, no host docker needed
  model: claude-opus-5               # optional; alias or model ID for `scion start --model`
  prompt_file: prompt.md             # boot TASK (first user turn, keep it short); resolved at the ROOT (host-only, outside the mount)
  instructions_file: manual.md       # standing instructions -> the agent's CLAUDE.md, via a file, never argv; same resolution
  read_only: [tools]                 # tree dirs the MANAGER sees read-only (e.g. code the host also runs); create-time only
  claude_settings:
    auto_compact_window: 400000      # optional; tokens at which Claude Code compacts; applied at every start
  after_compact_note: Re-read NOTES.md and the open cards before you go on.   # optional; one line, given to the agent after each compaction
  daily_reset: "06:30"               # optional; a new conversation once a day at this host-local time
  # resources: { memory: 3GiB, cpu: "2" }   # optional; container limits, create-time only
  # Host ports the jail may reach DIRECTLY (an MCP server you run yourself).
  # Never a first-party tool's backend port (3201 below): the jail would dial
  # the tool past the broker, and config load rejects it.
  allow_ports: [3901]
broker:
  llm_auth: api-key                  # the default; no real key in any container
  api_key_file: ~/.secrets/anthropic-key   # 0600; injected host-side by the /llm proxy
  # max_running_workers: 2           # optional; refuse a worker start past 2 running workers
  tools:
    - name: db
      command: [lever-tool-db]       # supervised subprocess the broker proxies to
      backend: 127.0.0.1:3201        # loopback address it listens on (injected as -backend); reachable from the jail only via the broker
      operations:
        - { name: read, params: [query, table] }  # optional: declared arg names — mint rejects constraints on any other key
      allowed_values:
        table: [users, orders]       # a db capability may only be pinned to these tables
workers:
  - name: scratch
    dir: workers/scratch              # relative to tree (i.e. workspace/workers/scratch)
    # image: <ref>                   # optional; defaults to manager.image
    # image_tar: <path>             # optional; the archive shipping THIS worker's image (needs image:)
    # model: <alias|id>             # optional; defaults to manager.model
    # resources: { memory: 1536MiB, cpu: "1" }   # optional; this worker's container limits
    # task_file: tasks/scratch.md   # optional; the task of an operator's fresh start; at the ROOT, outside the tree
    # autostart: true               # optional; `lever up` resumes or starts this worker after the manager
    obtain:
      - { tool: db, op: read }       # this worker may obtain db/read capabilities
shared_folders:                      # optional; off unless listed
  - path: shared/reference           # a tree folder, outside every worker dir
    writers: [scratch]               # mounts it read-write at /shared/reference
    readers: ["*"]                   # every other worker mounts it read-only; the manager always does
security:                            # optional image policy (both default off)
  allowed_image_registries: [lever.local]  # only run images from these registries/namespaces
  require_image_digest: false              # true -> every image must be @sha256:-pinned

For subscription mode instead: drop egress, set broker.llm_auth: subscription, remove api_key_file, and add manager.credential_file (your OAuth token, projected to the agents).

Keys

Top level

scion

Provide at most one of version, source or binary (they are mutually exclusive). Omit all three to rely on a scion already present in the jail.

lever requires a recent scion; the examples pin a supported commit. An unsupported scion fails at lever apply with an error that names the minimum. Do not work around a value must be base64-encoded error by encoding the credential yourself; upgrade the pin.

Whichever mode you use, lever records the installed binary’s sha256 in the jail and skips the copy when it already matches, so an unchanged scion is not re-streamed on every lever up.

Prebuilt scion

Each lever release ships scion prebuilt for linux/amd64 and linux/arm64, built from the commit the examples pin (65531d7f). When scion.version names that commit (as written in the examples, as its full hash or a prefix of at least 7 hex digits, or as its module version), a release build of lever downloads the binary for the guest’s architecture from its own GitHub release instead of building it. The host then needs no Go toolchain and skips the scion compile (about 4 CPU-minutes). The release also ships scion’s web UI built from that commit (a scion-web_<pin>.tar.gz asset of a few MB), so with remote.enabled lever downloads it instead of building it, and the host needs neither Go nor node for remote access either.

• The download is https only, from github.com and GitHub’s release asset hosts. The sha256 and size of every asset are embedded in the lever binary when the release is built. lever checks the download against them, and checks the ELF architecture, before it installs anything. It does not use checksums.txt or any other file from the server.
• A download whose bytes do not match is refused, and lever apply stops with an error that names both digests. lever does not fall back to a build then; set LEVER_SCION_DOWNLOAD=off to build from source once you have looked.
• When the download cannot happen (no network, the asset or release missing, a redirect to a host lever does not allow), lever builds scion from source as it does for any other pin, and the step notes prebuilt scion not downloaded; using a source build. That build needs Go; the web UI build needs Go and node.
• The web UI archive is checked the same way (https, the same hosts, the embedded sha256 and size) before lever unpacks it, and it is unpacked only when it holds nothing but directories and regular files under plain relative names (no links, devices, absolute paths or ..), within limits on the file count and sizes. An archive that breaks those rules stops the apply like a digest mismatch. The unpacked UI is cached in ~/.cache/lever/scion-web/release-<sha256>/ (~/Library/Caches/lever/scion-web/ on macOS) and reused on the next apply.
• The verified binary stays in lever’s cache directory (~/.cache/lever/scion-bin/ on Linux, ~/Library/Caches/lever/scion-bin/ on macOS). lever hashes it on each apply and downloads it again if it changed.
• Set LEVER_SCION_DOWNLOAD=off in lever’s environment to always build from source (scion and its web UI).
• A lever built from a checkout (make install, go build, go install) embeds no digests and always builds scion.

Agent telemetry (scion.telemetry)

Since scion#1792, sciontool telemetry is on by default, and cloud export is on by default too. lever configures no cloud destination, so the OTLP receiver that sciontool init starts in each agent container refuses to start. Every sciontool hook call still tries to export to 127.0.0.1:4317 in the container. The call then waits out a 10 s export timeout and a 5 s shutdown timeout. Claude Code fires 8 hook events, and Pre/PostToolUse fire on every tool call. A trivial turn took more than two minutes.

• off (the default). lever apply writes this top-level block into the jail’s ~/.scion/settings.yaml, and keeps all other keys and comments:

  telemetry:
    enabled: false
  

  If the block has other keys, lever keeps them and sets only enabled: false. An explicit enabled: true is overridden, because this key is the switch. (scion config set refuses this key, so lever edits the file.) scion turns the block into SCION_TELEMETRY_ENABLED=false for every agent that it starts.

• scion-default. lever does not manage the key. It removes only the exact block that off wrote, and leaves a block with more keys unchanged. Use this mode only when you configure scion telemetry yourself. A cloud destination adds egress and a credential in the jail, so lever does not manage it.

The setting applies when an agent starts. The runtime broker reads the file at each agent start. A running container keeps the env that it started with, and the hub reads the block only at its own startup. When apply changes the file, it logs the change and restarts nothing. Run lever stop && lever up to apply the change to the hub and the manager. The manager conversation is kept. The scion telemetry row of lever doctor shows the setting in the jail. It also shows the SCION_TELEMETRY_ENABLED value that the manager container started with, and it fails when the two do not agree.

lever has no local mode. With cloud export off (SCION_TELEMETRY_CLOUD_ENABLED=false), the in-container receiver starts on 127.0.0.1:4317/4318 with no new egress. But the receiver drops every span and log that it accepts, because sciontool has no local file or console sink. The telemetry.local settings produce env vars that no sciontool code reads. Also, scion’s Claude provisioner refuses an enabled telemetry block that names no cloud provider or endpoint. A local mode would thus add work to every hook and give no data.

With remote.enabled, version: and source: additionally need node >= 20 + npm on the host. Neither carries built web assets, so lever builds the hub’s web UI host-side from the same source tree and stages it into the guest; binary: is exempt, and so is the scion pin of your lever release, whose web UI lever downloads (prebuilt scion). Cache location, sizes, and failure modes are in the remote access guide.

manager

workers[]

shared_folders[]

A shared folder is a tree directory that the agents you name mount at the same path, /shared/<name>: read-write for each writer, read-only for each reader. It is the one way to give workers a common directory; without it a worker mounts only its own dir. Typical uses: reference material every worker reads, a hand-off folder one worker fills for the others, build outputs, or reviewed tools that one agent publishes and the rest run. Off unless listed, and every mount is opt-in per agent.

At least one of writers and readers must name an agent, and nobody may be in both.

• The manager always sees the folder. It mounts the whole tree. Unless it is a writer, it gets the folder read-only at both its tree path and /shared/<name>, like a manager.read_only entry. A manager that writes the folder mounts it read-write at /shared/<name>, and the folder is pinned in its tree (bind-mounted over itself). Either way every directory between the tree root and the folder, and every worker dir, is pinned too, so the manager can neither move the folder away nor swap it, or a worker dir, for a link that a worker would then mount.
• A worker that is not listed sees nothing of it.
• The host checks every mount source. Every lever apply/lever up that starts or resumes the manager, and the broker before every worker start and resume, refuse a folder that is missing or reached through a symbolic link. Create the folder before you start the agents. Right before it creates the manager, lever apply also refuses a file in a folder that has a hard link outside it (another name for it elsewhere could edit it), and a directory in it that it cannot read: copy such a file in instead of linking it, and keep the folder readable. Hard links with every name inside the folder are fine. Nothing re-checks hard links later: no new link across the folder’s boundary can be made from a container.
• Workers wait for the manager’s pins. While any folder is configured, the broker refuses to start or resume any worker unless the manager container holds its whole tree plan (checked as the manager.read_only tool guard checks it: the configured mounts, then, for a running manager, its live mounts from the guest side). A manager with no container, or a stopped one whose configured mounts hold the plan and whose planned directories all exist on the host, passes. A manager created before the current plan (a folder or a worker added since) lacks pins: run lever up --fresh --keep-conversation. When lever cannot read the mounts or the worker’s hub record, the start or resume is refused with “retry”.
• New contents show at once. It is a bind mount: files a writer adds appear in every reader without a restart. Change the folder’s contents in place; never replace the folder itself (rm -rf and recreate, a rename-based deploy): a mount stays on the directory that existed when the container started, so agents would go on seeing the old one. lever doctor finds a replaced folder in a running reader (writers’ mounts are checked by configuration only); recreate the agents it names.
• Symbolic links inside the folder are the writers’ business. A link resolves in the container that follows it, so it reaches only what that agent can already see.
• No host program may live in a shared folder, and neither may remote.labels_file when a worker writes the folder. Config load refuses a tool command whose program or script resolves inside one: a writer could change it, and no shared folder excuses one the way manager.read_only does.
• Changes restart the broker and need fresh agents. The broker reads lever.yaml only when it starts, and a change to shared_folders or manager.read_only changes its config hash, so the next lever apply (or lever reload) restarts it with the new plan. scion keeps an agent’s mounts for life, so adding a folder, or changing who may read or write it, reaches only an agent created afterwards: a worker after lever worker purge (or the manager’s agent recycle for a recyclable worker) and a new dispatch; the manager after lever up --fresh --keep-conversation, which keeps its conversation (plain --fresh starts a new one). The broker refuses to resume a worker whose record holds a shared mount the config no longer grants (removed, or read-write where it is now read-only), and names the purge. While any folder is configured it also refuses a resume when it cannot read the record (“retry”). With none configured it still reads the record and refuses one that holds a /shared mount (left from before the folders were removed), but a failed read does not hold the resume back, so an instance without folders never waits on that read. A mount the config adds that an older worker lacks is not refused: that worker goes without it until it is created again. The manager’s own resume is not refused: a manager that lost access keeps its old mounts until lever up --fresh, and lever doctor fails meanwhile. lever doctor’s shared folders row compares every agent’s mounts with the plan (a leftover or wider mount fails, a missing one warns) and checks running readers’ mounts from the guest side; the manager read-only paths row covers the manager’s tree-path protection and pins.

Security: a shared folder is a deliberate channel from its writers to its readers. Whatever a writer puts there, every reader (and the manager) can read and may run, so a compromised writer can influence what the other agents do. Grant writers only to agents you would trust with that, and see security model §4.5.

security

Opt-in image policy applied to manager.image and every worker image. Both default off, so existing configs are unaffected until you turn them on.

Note: these are enforced at config-load (host side), so they bound what lever apply loads and what the manager/workers declare. lever-manager agent start takes no image argument; the broker resolves each worker’s image from the validated config.

broker

The host-side capability broker (outside the jail) that holds the real credential and mints CN-bound, short-lived capability tokens. See security-model §6.

External MCP servers (external: true)

An external tool is a host MCP server the broker fronts but does not spawn — it keeps running as your own user-session process (launchd, a terminal, however you run it), which is what keeps macOS Automation/TCC grants intact for AppleScript-driven servers. The broker registers it from config at boot, exposes it at /mcp/<name>/ on its mTLS listener, and proxies to backend. Jailed agents therefore reach it only through a capability — no manager.allow_ports hole, no hand-authored .mcp.json. Every request goes to backend’s own path (/ when backend has none) with the agent’s query string dropped; any other path under /mcp/<name>/ gets 404 and never reaches the server, so its other routes stay out of reach.

Per-tool capability grain, gate:

• fine (default): only the MCP tools listed under operations are callable; a token must name the specific operation, and allowed_values can pin arguments.
• coarse: one wildcard grant — {tool: <name>, op: "*"} — admits every MCP call the server exposes (declare no operations). The wildcard is honored only for a gate: coarse tool: the broker chooses which capability to require, so a "*" token can never widen a fine tool. The audit log records the real MCP tool called either way.

broker:
  tools:
    - name: docs-search            # fine: only search is callable, database pinnable
      external: true
      backend: 127.0.0.1:3302
      operations:
        - {name: search}
      allowed_values:
        database: [work, personal]
    - name: tasks               # coarse: whole surface behind one wildcard grant
      external: true
      backend: 127.0.0.1:3300
      gate: coarse
    - name: notes                   # the server mounts its MCP endpoint under a path
      external: true
      backend: 127.0.0.1:3901/mcp
      gate: coarse
workers:
  - name: agent-y
    dir: workers/agent-y
    obtain:
      - {tool: docs-search, op: search}   # Y: docs-search search ONLY
manager:
  obtain:
    - {tool: tasks, op: "*"}           # manager: full tasks

backend must be a literal loopback IP (127.0.0.1 / [::1]; hostnames are rejected): the broker proxies host-side, so a non-loopback backend would let a jailed agent reach another host through the broker, bypassing the jail’s LAN-drop egress. If you truly need that, set allow_non_loopback: true on the tool — an explicit, per-tool opt-in.

Liveness is yours: the broker does not restart an external server. While it is down, every call to the tool gets 503 with the plain body tool <name>: backend unavailable; try again later. The body names only the tool, never the backend address. Claude Code keeps the server connected on an HTTP error, so only that call fails, and the next call works once your server is back. If the restarted server no longer knows the client’s session, its own 404 reaches the client unchanged, and the client opens a new session. The broker writes one audit line per tool per minute while the backend is down (decision=error detail=gateway.backend_unavailable, with backend=<host:port>, the error, and suppressed=<n> for the failures it left out since the last line). The tool backends row of lever doctor dials the server. The gateway answers every method but POST (an MCP client’s GET and DELETE) with 405 and Allow: POST: it offers no SSE stream and no session teardown, which the MCP client accepts.

operator

Optional host-side config for operator directives — authenticated delivery of an operator-signed action to a named agent, verified by the broker against a trust anchor you control (see the lever directive command group in the CLI reference). The whole block is optional: with allowed_signers unset, directives are disabled (the channel is simply not configured, not half-configured).

operator:
  allowed_signers: operator_allowed_signers   # ssh-keygen allowed_signers file, confined to the instance dir
  signing_key: /abs/path/to/operator_key      # default signing key for `lever directive send`; NOT confined
  directive_expiry: 10m                       # optional; default 10m
  directive_expiry_max: 24h                   # optional; default 24h

The operator principal is fixed as operator@<instance-name>, one principal per instance. Key posture (where to keep the key, multi-key break-glass, no agent forwarding) is in security model §11.5; setup and usage are in the operator directives guide.

remote

Optional config for lever remote: a host-side reverse proxy that exposes the Scion hub web UI (chat, transcript, xterm.js attach) through an authenticating front (tailscale serve by default, or another front that sets a verified identity header, such as exe.dev), injecting the operator’s hub web session host-side so the client never holds a credential. The whole block is optional and disabled by default — see the remote access guide for the accepted security posture, setup steps, and repair.

remote:
  enabled: true
  base_url: "https://myhost.tailxxxx.ts.net"   # required whenever enabled — see above
  # port: 8445                                 # optional; default shown
  # allowed_users: ["you@github"]              # optional identity pinning
  # identity_header: Tailscale-User-Login      # optional; another front's verified-login header
  # bind: 127.0.0.1                            # optional; a private address only for a front that dials it
  # trust_forwarded_host: false                # optional; see above before turning on
  # landing: console                          # optional; chat = open on lever's chat page (the login's agents)
  # labels_file: workers/labels.json          # optional; manager-written labels for the chat page
  # push:                                     # optional; chat page notifications (needs landing: chat)
  #   enabled: true
  #   subject: mailto:you@example.com
  # files:                                    # optional; files in the chat (needs landing: chat)
  #   enabled: true
  # voice:                                    # optional; dictation on the chat page (needs landing: chat)
  #   enabled: true
  #   socket: /home/you/my-instance/.lever-state/whisper/dictate.sock   # lever-tool-whisper's -dictate-socket
  #   read_aloud: server                    # optional; device (default), server or off
  #   speak_socket: /home/you/my-instance/.lever-state/tts/speak.sock    # with server: lever-tool-tts's -speak-socket

tree_backup

Snapshots of the tree on the host, in .lever-state/tree-backups/: see tree backups. Every key of the block is checked: an unknown key is a load error. Sizes take a number of bytes or a unit (KiB, MiB, GiB, TiB, KB, MB, GB, TB); durations take Go’s form (90s, 5m, 2h) or whole days (7d), and 0 for none.

ssh

lever ssh and lever ssh-config: an SSH session into the manager or a worker over scion’s hub relay (conduit), for the host operator only. See the SSH and VS Code guide. It needs a scion with the hub’s conduit controls and agent images built from one; without them apply keeps conduit off and warns, and lever ssh refuses.

Conventions & derived values

• Machine name: lever-<name>. up/apply/stop/destroy/doctor all agree on this, derived from the config (override on stop/destroy/doctor/worker purge with --machine). lever down is a deprecated alias of destroy.
• Worker model inheritance: a worker with no model: runs on manager.model; with neither set, lever passes no --model and the pinned scion resolves the model. The model is fixed when an agent is created (scion resume takes no --model), so editing it only affects agents created afterwards. The broker resolves the inheritance once, when it starts, and the hash that decides whether lever apply restarts the broker covers broker:/workers:/scion: but deliberately not manager: — so an edit to manager.model alone reaches a newly created worker only after the broker restarts for another reason. Setting workers[].model explicitly is the direct route. This is the same trade-off image: inheritance already makes.
• Worker image inheritance: a worker with no image: runs on manager.image (and ships in manager.image_tar, when set). The bring-up plan loads every distinct image once (deduped), from its archive when the config names one, else from the host docker store. At dispatch the capability broker reads the config directly and supplies each worker’s resolved image, so agent start NAME takes no image argument. The manager names a configured worker; the broker resolves paths, image and credentials host-side.
• In-place mounts: the tree subdir (and each workers[].dir within it) is bind-mounted into the jail so agents edit the real host files. There is no copy/sync step.
• Path resolution base: relative tree/prompt_file/instructions_file/scion.source/credential_file resolve against the config file’s directory, never the shell’s current directory.

See also

• Getting started, build a working instance from scratch.
• Security model, trust boundaries, threat model, and the credential flow these keys drive.