Skip to the content.

Application Runtime Guide

core/runtime assembles one agent runtime from a configuration document and owns everything it built.

The unit is deliberately not a session. A Runtime holds the substrate a turn runs on — the model provider and its router, the tool registry with its instances, the sandbox runner, the file boundary, the skill index, the journal — and nothing that belongs to a conversation: no history, no turn counter, no per-user state. Two runtimes can live in one process without sharing anything, which is what makes "atomic" true rather than aspirational. History is an argument to a turn, and the turn loop belongs to whatever layer adds prompting (core/agent, core/agent-host).

The document

version: 1
name: forge

files:
  roots:
    - /workspace/forge # absolute; the first root is the default workdir

sandbox:
  backend: seatbelt # local | seatbelt | bwrap | windows | remote
  writes:
    - /workspace/forge/out
  net:
    mode: allow_list
    allow_hosts: [api.openai.com, "*.github.com"]
  timeout: 60s
  cpu_millicores: 2000 # needs timeout
  memory_mib: 2048
  output_mib: 8
  journal: # presence opts in; absent means no journal
    exclude: [.git, node_modules]
    retention: 4096

inference:
  providers:
    - name: openai
      driver: openai
      settings: { api_key: "${OPENAI_API_KEY}" }
  models:
    - provider: openai
      model: gpt-5
      weight: 100
      capabilities: { inputs: [text, image] }
      limits: { max_input_tokens: 200000, max_output_tokens: 32000 }
  route:
    selector: weighted
    attempts_per_target: 2
    max_targets: 3

tools:
  enable: [exec, read, write, edit, glob, grep, skill_search, skill_read]
  tty: false
  dynamic:
    default: direct
    hidden: [write]
  images: false
  mcp:
    servers: []
  middleware:
    - { name: redact, settings: { pattern: "sk-[A-Za-z0-9]+" } }

skills:
  roots: [.agents/skills]

sandbox

The process boundary. Nothing here is guessed:

Field Meaning
backend Required. local, seatbelt, bwrap, windows, or remote. There is no default: a boundary picked by guessing is a boundary nobody chose.
workdir Where commands run. Empty means the first files root.
writes Absolute paths a command may write. Empty means read-only.
net.mode default, none (aliases deny, deny_all), allow_list (alias allowlist), proxy (alias proxies).
net.allow_hosts Only legal with allow_list; a host pattern or *-glob.
net.proxy Only legal with proxy.
timeout Default per-call deadline. A tool may ask for less; this is the ceiling.
cpu_millicores Millicore budget. Rejected without timeout, because the budget is derived from it.
memory_mib Address-space cap; zero is unbounded.
output_mib Captured output per call; zero uses the backend default.
journal A settings block. Presence opts in; see sandbox.md.
bwrap, seatbelt, windows The backend's own construction options. Setting one on a different backend is a validation error, not a comment.
remote Client configuration for backend: remote; must be absent otherwise.

The value you write in backend is resolved from a table the host registers (runtime.WithSandboxBackends), not from a built-in list: the runtime imports none of the backends, so a process that ships only the local runner links nothing else. core/runtime/backends is the opt-in set of every backend core provides — backends.All() for all five, or one of backends.Local(), Bwrap(), Seatbelt(), Windows(), Remote(). A backend that is not registered is a validation error that names what is registered.

files, skills, tools

Section Rule
files.roots At least one, all absolute; this is also the write policy the file tools enforce.
skills.roots Directories scanned for SKILL.md. One index is built and shared by the tools and the host's own prompts.
tools.enable Empty means every registered tool. Names not registered are a build error.
tools.dynamic The projection: default (always / direct / deferred / hidden), plus always, hidden, budget, max_bytes, idle_rounds, search_with_load.
tools.middleware Named middleware with kind-owned settings, applied in order.
tools.descriptions Per-tool and per-parameter replacement of the text the model reads, keyed by tool name. A configured name that matches no wired tool is a build error. Text is prompt surface only: the input schema's types and bounds are never overridden. See tool.md.
tools.exec.shell Pins the shell the exec tool runs (name, path, args) instead of letting the platform probe the host. See tool.md.

inference

Providers are {name, driver, settings}; the driver name must be registered on the Runtime (see WithDrivers). Models are {provider, model, weight, capabilities, limits}. route decides how a request picks among them: selector plus selector_settings, attempts_per_target, max_targets, base_delay, max_delay. See inference.md.

Layers

A deployment usually stacks three files: a base, a profile, a local override. The merge itself lives in core/config; runtime.LoadLayers is the entry point that also validates the result.

cfg, err := runtime.LoadLayers(ctx, []config.Layer{
    {Priority: 0,  Name: "base.yaml",    Source: config.File("base.yaml")},
    {Priority: 10, Name: "profile.yaml", Source: config.File("profile.yaml")},
    {Priority: 20, Name: "local.yaml",   Source: config.Bytes(embedded)},
}, config.WithResolver("secret", vault.Resolve))

A layer's bytes come from a config.Source, so a stack is not limited to files on disk: config.File, config.Bytes, config.FS for any io/fs filesystem (an //go:embed tree included), and config.Func for a document that has to be fetched, decrypted or generated.

Building

// Resolvers are a load option: they belong to reading the document.
cfg, err := runtime.LoadLayers(ctx, layers,
    config.WithResolver("secret", vault.Resolve),
)

rt, err := runtime.New(ctx, cfg,
    // Backends are keyed by the name written in sandbox.backend; there is no
    // built-in table, so a host that ships one backend links only that one.
    runtime.WithSandboxBackends(backends.All()),
    // Drivers are keyed by the name written in inference.providers[].driver.
    runtime.WithDrivers(runtime.Driver{Name: "openai", Build: openai.New}),
    // Selectors are keyed by the name written in inference.route.selector.
    runtime.WithSelectors(runtime.Selector{
        Name:     "weighted",
        Generate: func(json.RawMessage) (route.Selector[inference.GenerateRequest], error) {
            return weighted{}, nil
        },
    }),
    runtime.WithToolSource(myExtraTools),
    // Middleware that needs a Go value cannot come from YAML, so the host
    // registers it under the name the document lists.
    runtime.WithMiddleware(runtime.MiddlewareOption{Name: "approve", Build: approve}),
    // The composed sandbox runner, after the document's policy: wrap it before
    // the tools are built (instrumentation, an escalation retry).
    runtime.WithSandboxDecorator(wrapSandbox),
)
defer rt.Close()

There are no built-in drivers or selectors: a name the document writes must have been registered, and an unregistered one fails with the offered names — inference.route.selector: "cheapest" is not available; offered: weighted. An empty selector keeps declaration order. Middleware is the exception: the built-in names telemetry, recover, result_limit, concurrency and redact are always available, in the order the document lists them, first written outermost.

New validates before it builds, so a document that cannot be honoured fails without side effects:

The sandbox policy reaches the commands

This is the part that used to be missing: a document could declare a budget that nothing enforced. The runtime now projects every per-call knob of the section onto each call it issues through engine.WithDefaults:

Document Becomes
timeout ExecOptions.Timeout — a ceiling; a tool asking for less keeps its own.
cpu_millicores Resources.CPU (derived from the timeout).
memory_mib Resources.MemoryBytes.
writes Permission.Writes — the files a command may touch.
net Net — projected where the backend declares the mode it can enforce.

Three rules make that honest:

  1. Stricter wins, per field. When a tool also sets resources, the two are merged field by field: zero defers, and of two non-zero values the smaller one wins. A tool cannot widen the deployment's budget and the deployment cannot silently widen a tool's.
  2. An unenforceable cap is a build error. writes is only projected onto a backend that has write confinement; asking for a cap a backend cannot apply names the field instead of pretending.
  3. A backend that cannot enforce writes or net warns. local enforces no OS boundary, so either value would be decoration; the runtime logs a warning rather than implying enforcement. net is projected only when the mode appears in Capabilities.NetModes, and a remote runner reports the server's declaration, so the same test answers for it. Not projecting would discard the policy silently, because engine.WithDefaults replaces a tool's own Net with the chain default. On bwrap, allow_list and proxy also need bwrap.MaybeBridge in the host main; without that hook those modes fail per call.

Decorating the runner

WithSandboxDecorator wraps the runner the runtime composed — backend plus the policy above — before the tool set is built:

type audited struct {
    *sandboxengine.Forwarder
    sink Sink
}

func (a *audited) Start(ctx context.Context, spec sandbox.SessionSpec) (sandbox.Session, error) {
    a.sink.Record(spec.Argv)
    return a.Forwarder.Start(ctx, spec)
}

rt, err := runtime.New(ctx, cfg, runtime.WithSandboxDecorator(
    func(sb runtime.Sandbox, composed sandbox.Runner) (sandbox.Runner, error) {
        forwarder, err := sandboxengine.NewForwarder(composed)
        if err != nil {
            return nil, err
        }
        return &audited{Forwarder: forwarder, sink: sink}, nil
    }))

runtime.Sandbox is the resolved view of the document: WorkDir is the effective directory (sandbox.workdir, otherwise the first files root), Net the posture the document declares, and Defaults exactly what engine.WithDefaults applies. A host that builds a second chain from it does not re-derive the document; anything that reproduces the workDir() fallback or the default merge by hand drifts from it. Treat Config and Defaults as read-only: their slices and policy pointers are shared with the composed chain, so editing one rewrites the boundary that chain enforces.

Ordering is the reason the seam is on the runner rather than a tool option: the decorator runs after the policy and before the journal, so exec_command, exec_session, Runtime.Runner() and the journal all see the decorated value.

Two rules keep it honest:

A runner that needs the completed result of a command — escalation recognizes an OS refusal in it — implements sandbox.Executor, which engine.Exec dispatches to; Start keeps the derived view. See sandbox.md for the escalation wiring.

The remote backend

sandbox.backend: remote hands execution to a server that speaks the wire protocol in core/sandbox-remote/wire:

sandbox:
  backend: remote
  remote:
    transport: http # http (default) | unix
    endpoint: https://sandbox.internal:8443
    token: "${SANDBOX_TOKEN}"
    timeout: 30s
    poll_hold: 15s
    insecure_skip_verify: false
Transport Fields
http endpoint required and http(s); socket rejected.
unix socket required; endpoint and insecure_skip_verify rejected. A token is optional — the boundary is the directory's permissions.

Every other backend's fields behave the same way: the field the transport does not use is a validation error, because a socket path beside an endpoint is configuration that silently does nothing.

Accessors

Call Returns
Config() The resolved configuration, layers already merged.
Provider(), Router(), DefaultModel() The inference side.
Tools(), Assembly(), NewCatalogView() The tool registry and the per-run projection.
Runner(), Journal() The sandbox boundary and its file journal (nil when absent).
Files() The fsx.Tree the file tools write through.
Skills() The one skill.Index the tools and the host share.
Context(ctx) A context carrying the runtime's identity for tracing.
Close() Tears down, in reverse construction order.

The run identity

Context(ctx) attaches one value: a correlation.Run. It is the identity a span, a log record, a RunRecord and a checkpoint are correlated by — not conversation content, and not a dependency. Each layer adds the fields it is the first to know, and a later layer only overrides the fields it sets:

Field Written by Attribute key
RuntimeID runtime agent.runtime.id
SessionID agent-host session.id
AgentName agent-host agent.name
TenantID agent-host tenant.id
Manifest agent-host agent.manifest.id
TaskID agent task.id
Turn agent turn

DelegationDepth and ChainID are stamped by delegation and are deliberately not rendered as attributes: they say where the run sits in a delegation chain, not who it is, and the delegation layer already carries them on its own records (Outcome, Job).

The package is core/correlation and it is a contracts-tier package on purpose: tool, sandbox, inference, agent and delegation all read the identity to start a span, and none of them may import the assembly that built the runtime. The attribute names above live in the same package (core/correlation/attrs.go), so "who the work belongs to" has exactly one home; core/telemetry keeps the keys that describe the work itself (tool.*, llm.*, sandbox.*, error.*, …).

Callers read it in two ways, and both are allocation-free:

run, ok := correlation.From(ctx)                  // the identity itself
span.SetAttributes(correlation.Attrs(ctx)...)     // precomputed, cap-crippled

Ownership

One rule: a Runtime closes what it created. A value handed in through an option is somebody else's to close, and Close leaves it alone.

Close runs in reverse construction order — tools, then journal, then runner, then tree — because a session that outlives its runner writes into a corpse, and a journal that outlives its runner drops the last events. Errors are joined: a failing journal must not stop the runner from being closed.

What is not here

Not in runtime Where it lives
Sessions, history, turn loop core/agent and core/agent-host
Lifecycle hooks agent.Hooks, attached by a deploy.HookKind — see hooks.md
Events a UI subscribes to agent.Event, streamed by a session
Reload / hot swap A host builds a new Runtime and drains the old one
Deployment documents core/deploy — see deploy.md