Managoat.Runtimes

How a coding agent CLI — claude, codex, gemini or opencode — gets into a sandbox and comes up speaking the Agent Client Protocol. The protocol session itself is managoat_acp; the sandbox it runs in is managoat_sandbox. This package is what has to have happened on the sandbox before a peer can open a session: which adapter to install and at what version, where the runtime keeps its files, the instructions file that carries the agent's system prompt, the credential env vars, the skills tree, and the per-runtime workarounds with the condition for deleting each one.

alias Managoat.Runtimes
alias Managoat.Runtimes.{ACP, Instructions, Skills}

{:ok, handle} = Managoat.Sandbox.create("my-agent", provider: :sprites)
{:ok, runtime} = Runtimes.for_runtime("claude")

agent = %{
  name: "reviewer",
  model: "anthropic/claude-sonnet-4-6",
  system: "You review pull requests. Be brief.",
  mcp_servers: %{"gh" => %{"command" => "gh-mcp", "env" => %{"GITHUB_TOKEN" => token}}}
}

# 1. The credential env for this runtime, from the credentials the host holds.
#    Three of the callbacks are optional, so they are called through the
#    dispatchers rather than on the module — see "Calling the optional
#    callbacks" below, and never guard them with function_exported?/3.
env = Runtimes.default_env(runtime, agent, %{anthropic_api_key: key})

# 2. Files: the runtime's own config (claude's .mcp.json), the system prompt,
#    the skills.
:ok = Runtimes.write_config(runtime, handle, agent)
:ok = Instructions.write(handle, "claude", agent)
:ok = Skills.install(handle, [%{"name" => "house-style", "content" => skill_md}], runtime: "claude")

# 3. The ACP adapter, pinned, then whatever bootstrap the runtime needs.
:ok = ACP.install(handle, "claude", env)
:ok = Runtimes.prepare_sandbox(runtime, handle, agent, env)

# 4. Spawn it and hand the process to Managoat.ACP.Peer.
{bin, args} = ACP.command("claude")
{:ok, command} = Managoat.Sandbox.spawn(handle, bin, args, env: env, dir: ACP.cwd("claude"), stdin: true)

{:ok, peer} =
  Managoat.ACP.Peer.start(
    owner: self(),
    writer: &Managoat.Sandbox.write_stdin(command, &1),
    ref: command.ref,
    prompt: "review PR 42",
    mode: :run,
    session_id: nil,
    cwd: ACP.cwd("claude"),
    mcp_servers: ACP.mcp_servers(agent),
    model: Managoat.Runtimes.Model.acp_model("claude", agent.model)
  )

The pieces

What the host still does

This package writes files into a sandbox and tells you what to spawn. It does not spawn, does not hold the protocol session, and does not know the tenant. The host:

• decrypts the tenant's inference credentials and passes them to default_env/2 as %{anthropic_api_key: ..., openai_api_key: ..., gemini_api_key: ..., claude_code_oauth_token: ...};
• decides the skills list (Fountain prepends its own API skill to the agent's);
• reads its own configuration for how long a held permission waits for a human, and passes it to Managoat.ACP.Permissions.ask_timeout_ms/1;
• applies any network policy to the sandbox, and calls ACP.install/3 and prepare_sandbox/3after it, with the npm registry allowed if the policy restricts egress;
• calls Gemini.SessionStore.consolidate/2 at the end of every gemini turn.

Calling the optional callbacks

Four of the callbacks are optional and the matrix is genuinely sparse — every runtime is missing at least one — so a host has to guard the call. The obvious guard is wrong:

# WRONG: silently no-ops in an escript or a release
if function_exported?(mod, :default_env, 2), do: mod.default_env(agent, creds), else: []

function_exported?/3 answers false for a module that is merely not loaded yet, which is the normal state of any module nobody has called under an escript or a release. That drops the callback without an error: one host lost its whole inference credential env this way, and saw a provisioning run report every stage green and then fail minutes later on authentication. The callback that vanished was default_env/2, which all four runtimes implement — so no amount of checking the matrix saves you.

Dispatch through Managoat.Runtimes instead. Each function loads the module first and falls back to the documented no-op:

env  = Managoat.Runtimes.default_env(mod, agent, credentials)      # or []
:ok  = Managoat.Runtimes.write_config(mod, handle, agent)          # or :ok
:ok  = Managoat.Runtimes.prepare_sandbox(mod, handle, agent, env)  # or :ok

build_command/5 has no default to fall back to — there is no argv to invent — so ask Managoat.Runtimes.implements?/3 and decide what an unimplemented runtime means on your legacy spawn path. skills_root/0 and skills_sh_agent/0 are required callbacks; call them on the module.

The adapter is pinned, and that is load-bearing

An unpinned adapter can stop advertising sessionCapabilities.resume in a point release and silently downgrade every conversation to a full history replay per turn. So the versions in Managoat.Runtimes.ACP are exact, the install is idempotent on that exact version (an image carrying a different one is corrected, not accepted), and a pin moves in a commit that says why.

Licence

Apache-2.0. Extracted from Fountain under its decision record 0037; the issue numbers in the source are that repository's.