Config reference, lever.yaml

A lever application is described by a single config file. It declares the manager agent and the groves (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.md §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)
    groves/...
    vendor/bin/lever-manager

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: scionlocal/lever-claude:latest
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: scionlocal/lever-claude:latest
  credential_file: ~/.scion/oauth-token    # 0600; projected to the agents

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: 666333f9                  # pin a scion commit; fetched + cross-compiled into the jail
manager:
  image: scionlocal/lever-claude:latest
  prompt_file: prompt.md             # boot task; resolved at the ROOT (host-only, outside the mount)
  allow_ports: [3101, 3201]          # host tool ports the jail may reach
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
  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)
      operations:
        - { name: read }
      allowed_values:
        table: [users, orders]       # a db capability may only be pinned to these tables
groves:
  - name: scratch
    dir: groves/scratch              # relative to tree (i.e. workspace/groves/scratch)
    # image: <ref>                   # optional; defaults to manager.image
    obtain:
      - { tool: db, op: read }       # this grove may obtain db/read capabilities
security:                            # optional image policy (both default off)
  allowed_image_registries: [scionlocal]   # 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 or source (they are mutually exclusive). Omit both to rely on a scion already present in the jail.

manager

groves[]

security

Opt-in image policy applied to manager.image and every grove 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/groves declare. An explicit --image passed to lever-manager agent start is a runtime override and isn’t policy-checked, but it can only run an image already loaded into the jail (which came 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.md §6.

Conventions & derived values

• Canonical filename: lever.yaml at the instance root. Resolved from the current directory only, no walk-up (run lever from the root, or pass an explicit path).
• Root is not mounted: the instance root holds the config + boot prompt and stays host-only; only the tree: subdir is bind-mounted.
• Machine name: lever-<name>. up/apply/down/doctor all agree on this, derived from the config (override on down/doctor with --machine).
• Grove image inheritance: a grove with no image: runs on manager.image. The bring-up plan loads every distinct image once (deduped). At dispatch the capability broker reads the config directly and supplies each grove’s resolved image, so agent start NAME needs no --image (an explicit --image still overrides). The manager never handles host paths or credentials: it names a configured grove and the broker resolves everything host-side.
• In-place mounts: the tree subdir (and each groves[].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/scion.source/credential_file resolve against the config file’s directory, never the shell’s current directory.

See also

• getting-started.md, build a working instance from scratch.
• security-model.md, trust boundaries, threat model, and the credential flow these keys drive.