Skip to content

How a profile becomes a sandbox

For contributors. This page follows one profile with runs: sandbox from its manifest to the claude -p process in the sandbox. For what the profile fields mean, see Profiles.

profile manifest (builtin or ~/.config/aimux/profiles)
| profile.Resolve internal/profile/manifest.go
| extends parent; a child may only narrow
| profile.CheckRoles, only where a profile is admitted
| (aimux profile check, the remote API catalog, and before
| every new turn, queued ones included: Router.Admit):
| every role target and its own roles resolve and
| validate, with a valid sandbox name; a planner role
| runs: sandbox without web, a writer role runs: acp
| with no tools and no web; routing and
| cancelling a running turn use Resolve alone
v
resolved Manifest
| toolreg.Snapshot internal/toolreg/snapshot.go
| registry + pins, one version; "google:readonly" ->
| server + listed tools pinned (not source_changed)
v
profile.CompileAt(m, snap, gw) internal/profile/compile.go
| refuses a sandbox name over 19 characters or not in
| lowercase letters and digits in dash-separated runs
| (no leading, trailing or doubled dash; CheckSandboxName)
|
+--> (a) PolicyYAML + PolicyDigest buildPolicy / marshalPolicy
| OpenShell network, MCP tool, file and binary rules
|
+--> (b) Grant: profile.ToolGrant internal/profile/grant.go
| server -> exact tools, immutable; (a), the token
| and (c) all render from this one value
|
+--> (c) Compiled.Capabilities() internal/harnessconfig/harnessconfig.go
grant, web, file grants (read and write paths),
inherit user, model (harness-neutral)
|
| + harnessconfig.Launch from the engine:
| mode (headless or interactive),
| resume id, session id
v harnessconfig.For("claude-code")
harness adapter internal/harnessconfig/claude.go
claudePrint (claudeACP for acp mode)
|
v
Spec: argv for `claude -p ...` + MCP config renderer

Compile fails before any of this runs when the profile does not run in a sandbox, is not available, lacks model in network.allow, has an invalid sandbox name (aimux-<name> over 19 characters, or not lowercase letters and digits in dash-separated runs: no leading, trailing or doubled dash), or requests tools whose sets all lack pins.

  • (a) Policy. buildPolicy turns the manifest, the grant and the gateway address into the OpenShell policy. PolicyDigest is a sha256 over the YAML. It keys the sandbox’s policy, so a new pin changes it. The manifest Digest is separate and is what sessions and audit record.
  • (b) Grant. The server to exact tool names map, held as an immutable ToolGrant: its fields are unexported and every accessor returns a copy. Grant.Scope() is the scope of the session token that toolgateway.Tokens.Issue creates (internal/toolgateway/tokens.go); the same grant is what the policy allows, what the MCP config lists and what --allowedTools names, and a test checks the four match.
  • (c) Capabilities and Launch. An adapter reads only these two, never the manifest; a future Codex or Gemini adapter reads the same two. Capabilities is what the run may do (Compiled.Capabilities(), which derives its tool grant from Compiled.Grant); Launch is how this run starts (from the engine, per turn). Launch modes are harness-neutral: the claude adapter maps headless to claude -p and interactive to ACP. For headless, claudePrint turns them into flags: --tools, --strict-mcp-config, --mcp-config, --allowedTools, --setting-sources "" unless the profile inherits user settings, --model, and --resume or --session-id.

profilerun.SandboxEngine (internal/profilerun/sandbox.go) does this for each turn:

  1. Calls its Compile function: profile.CompileAt over the turn’s snapshot of the registry and pins, recorded in Compiled.Snapshot. In remote serve the snapshot comes from a toolreg.Store the turns reload when the registry or pins file changed (time, size, inode) and once a minute as a backstop (toolSnapshots in internal/remoteapp/profileserve.go). The read-only gateway runs in its own process, the gateway worker (internal/gatewayworker, aimux mcp proxy gateway serve), with its own store: it reloads when a lease names a snapshot version it does not serve, and once a minute. It publishes a new snapshot to the token table before rebuilding any server, and keeps the one backend pool mcpproxy.Serve owns, retiring only moved or dropped backends.
  2. Ensures the sandbox aimux-<profile> exists with that policy (ensure, through internal/sandboxlaunch).
  3. Asks the harness adapter for a Spec from the compiled Capabilities (with the turn’s model, if chosen) and a Launch: headless mode, --session-id on the first turn, --resume after.
  4. If the grant is not empty, makes a token and puts it on the gateway worker as a lease (toolgateway.Lease: the grant’s scope, Compiled.Snapshot’s version and the pin of each granted tool, 15 minutes) over ~/.aimux/gateway.sock; the worker first loads that snapshot if it serves another, then lists the turn’s servers afresh (at most 5 seconds). The engine renews the lease every 2 minutes, asks the worker’s status every 10 seconds (every second after a failed renewal or status check, until it answers) and puts the lease again when the worker restarted (a new start time) or holds no lease, and deletes it when the process ends. For 15 seconds after the worker can take leases again, it holds a call whose token it does not know yet until the lease is back (at most 64 calls; more get 503); after that an unknown token gets 401 at once. When the gateway serves another snapshot than the lease’s, older or newer (a refresh still pending), the token loses the tools whose pin hash or source differs between the two, or that only one of them pins; the rest stay usable.
  5. Runs claude through Launcher.Exec with the MCP config (it holds the token) on the first stdin line and the prompt after it. Neither goes on a command line.

Three walls then apply: the adapter’s flags (cooperative), the OpenShell policy (enforced), and the read-only tool gateway checking token and pin on every call (enforced). Reviewed tool sets and pins explains the pins.

cli and http-openapi tool sources do not run in a profile’s sandbox. They run in one shared sandbox, aimux-tools, from the image localhost/aimux-tools:2.103.3: the profile sandbox image plus gh 2.103.3, installed from the release tarball and checked against its SHA-256 for arm64 or amd64 (sandbox/aimux-tools/Containerfile). aimux sandbox setup builds it.

Both run there. The tool gateway worker (aimux mcp proxy gateway serve) and aimux tools approve start each cli source on first use (an http-openapi source works differently; see HTTP sources):

  1. Ensure: openshell provider list --names, then the policy below compiled for the providers the gateway has, then the sandbox is created or updated as for profiles. A source whose provider is missing (for gh, aimux-github) is left out of the policy and shows as down with an error naming the Keychain item and aimux sandbox setup; the other sources keep running. aimux tools status, aimux tools diff, aimux doctor and setup’s tool review are read-only: they list a cli source only when aimux-tools already exists and is Ready (running <binary> --version in it), and otherwise show it as down with tool runner not started: run aimux tools approve <set> ..., or start the tool gateway worker: aimux mcp proxy gateway install. They never create or update the sandbox.

  2. <binary> --version at start and again on every listing (the gateway relists at most once a minute, and to verify a call). The version goes into each tool’s x-aimux-binary annotation, so a gh upgrade changes every gh tool’s pin: the tools stop being served until you approve them again. A binary replaced under a running backend (a rebuilt aimux-tools) is seen at the next listing, and calls are refused as changed from then until the tools are approved again.

  3. Each call: the pack checks the arguments first (a refused argument runs nothing), then openshell sandbox exec --no-login-shell --no-tty --timeout <s> --env GH_CONFIG_DIR=/tmp/gh --env XDG_CACHE_HOME=/tmp/cache aimux-tools -- <argv>, argv only, never a shell, with a 30 second limit. Stdout is the result, cut at 256 KiB with a final line [output cut at 256 KiB]. A non-zero exit is an error result with the first 2 KiB of the stderr aimux kept (the last 4 KiB the command wrote, so a long stderr is a truncated tail). A request the network policy refused (OpenShell’s policy_denied body with an HTTP 403) is an error result naming the method and path it refused. Output past 1 MiB is read and dropped so the command’s own exit status is kept. openshell also exits 1 when the sandbox is gone or not Ready, so after any failure the runner’s phase is checked: if it is not Ready, the call ensures the sandbox once (for at most 60 seconds) and retries once. If it comes back with another binary, the call is refused as changed. If the Ensure fails, the result names the step for that situation:

    • Missing: Ensure creates it again; if that fails (no image, no gateway), aimux sandbox setup.
    • Stopped: Ensure never starts a stopped sandbox. Run openshell -g local sandbox start aimux-tools, or delete it as for Failed.
    • Failed (or Error, Completed): openshell -g local sandbox delete aimux-tools, then run aimux tools approve <set> or restart the gateway worker (launchctl kickstart -k gui/$(id -u)/com.aimux.tool-gateway) to create it again.

    Any other runner failure reaches the agent as the tool runner failed; see the aimux log, with the detail in the gateway’s log.

An http-openapi source lists its tools from its local OpenAPI file (3.0 or 3.1, YAML or JSON, at most 5 MiB and 500 GET operations), parsed again whenever its modification time or size changes, so reviewing it needs no runner. Every get with an operationId becomes the tool <source>_<operationId>, the operationId in snake case ([a-z0-9_]). Skipped, with the reason in the gateway’s log: other methods, a get without operationId, a path with a segment that is neither one whole {param} nor plain RFC 3986 characters (letters, digits, -._~!$&'()+,;=:@; no *, %, brackets, backslash or space), a ., .. or empty inner segment, and an operation with a required header, cookie, array or object parameter (optional ones are dropped). Parameters are path and query ones of type string, integer or boolean, each optionally an enum (kept in the input schema and checked on each call); a parameter whose schema is a $ref, or that declares a serialization other than the default (a style or explode other than path simple and query form with explode, allowReserved, allowEmptyValue, or content instead of schema), skips its operation; path-level parameters and $refs to components/parameters are merged in. Each tool’s pin covers GET <path template> (annotation x-aimux-http), the base URL (x-aimux-base) and the parameters. Descriptions are not pinned, so a spec edit can change a tool’s description text without approving it again. A spec that is missing or cannot be read is that source’s error, naming the source and the file; the other sources keep running.

Each call:

  1. The arguments become one URL before anything runs. Each path value is escaped as one segment, so ? and # cannot leave it; a value that is empty, . or .., or holds /, \ or %, is refused (an API that decodes %2F and resolves dot segments could otherwise route it outside the approved operation). An unknown key, a missing required one, a value of the wrong type or outside its enum, and a string with a control character or a leading - are refused too. The URL’s host must be the base URL’s.
  2. If the operation’s path or parameters differ from the backend’s first listing (the one the gateway built its servers from and checked against the pins; a call before any listing lists first), the call is refused as changed since it was pinned: review with aimux tools diff, then aimux tools approve. Later listings do not move that baseline; approving makes a new tool snapshot, which restarts the backend with a new one.
  3. The runner is ensured on the first call, and the request runs as /usr/bin/curl -q -sS --fail-with-body --max-time 25 --proto =https --globoff -H 'Accept: application/json' -w '<status line>' <url>: a GET with no body, https only, no URL globbing, no .curlrc (-q); only the URL comes from the agent. The -w status line goes to stderr with the HTTP status and the X-OpenShell-Policy header.
  4. Results as for cli calls: 30 seconds, output cut at 256 KiB, a runner that went away ensured once and the call retried once. A 403 with X-OpenShell-Policy and a policy_denied body is reported as the network policy refusing GET <path>; the API’s own errors come back as HTTP <status> with the first 2 KiB of the body.

This call path is tested against a fake runner; no live http-openapi call has been run on OpenShell 0.1.7 yet, so treat it as expected rather than verified behavior.

A source that names a credential serves no tools yet and is left out of the runner’s policy, with an error saying so: OpenShell 0.1.7 offers no checked way for curl in the runner to send a provider’s credential without its value on the command line.

The sandbox never holds the token, and nothing on this path reads the Keychain or redacts output. Checked live on OpenShell 0.1.7 with the gh pack and a real token: the sandbox’s environment has no GitHub token, and the proxy adds the Authorization header to /usr/bin/gh’s requests only; REST reads, gh issue list and a GraphQL query work; a POST (/markdown) and a GraphQL mutation are refused with policy_denied; a binary the policy does not list (python3) cannot connect; and curl cannot reach api.github.com (refused at connect), because the endpoints are scoped to their binary.

profile.CompileRunner (internal/profile/runner.go) compiles its policy from the same snapshot as the profiles:

  • One network policy, tools_<source>, per cli or http-openapi source with at least one active pin (a pin the gateway serves, so not source_changed). Unapproved sources open nothing.
  • A cli source gets its pack’s endpoints and binary. For gh that is api.github.com REST with access: read-only and /graphql with a rule allowing operation_type: query, for /usr/bin/gh only.
  • An http-openapi source gets one REST endpoint on its base URL’s host (a plain public hostname: no IP literals, localhost, .internal or .local names, and not the model host), with a GET rule per approved operation’s path under the base path, each {param} segment as * (one segment, never **), for /usr/bin/curl. Its host may not be one a credentialed built-in pack uses (api.github.com for gh), since that pack’s provider is bound to the host. A base URL the compiler refuses (such a host, a refused host, a bad port or base path) or a path it refuses leaves that source out, with the reason under its name, like a spec error; it never fails the other sources. An operation is approved when its tool has an active pin that matches its current definition: one nobody approved, or whose path or parameters changed since, gets no rule.
  • Every endpoint is enforcement: enforce. A REST endpoint has either access or rules, never both (OpenShell rejects that).
  • No model host and no tool gateway: the runner has neither api.anthropic.com nor host.containers.internal.
  • Files: /tmp and /dev/null are the only writable paths; the workdir is read-only.

Compiled.Providers lists the providers the sandbox is created with: the packs’ credential providers (aimux-github for gh), once each. A profile sandbox’s list is just wingman-claude. sandboxlaunch passes one --provider per entry at create and records the list in <sandbox>.providers; when the list changes on a running sandbox, Ensure attaches and detaches the difference (openshell sandbox provider attach|detach --wait). The runner’s PolicyDigest covers its policy and its sorted providers, so a provider change alone updates the sandbox; its .digest file works as for profiles, and aimux sandbox status shows it as (tool runner) with its recorded and compiled digests (runner in --json).

aimux sandbox setup creates the provider aimux-github only when the platform’s secret store (keyring.System: the Keychain on macOS, the Secret Service on Linux) has the item aimux-github; it asks with keyring.Probe, which tells a missing item from a store that could not be asked (on macOS it reads only the item’s attributes; on Linux, where secret-tool has no metadata lookup, it reads and discards the item). When the item is absent, or the platform has no supported store, setup prints how to add it (a fine-grained token, public repositories, read-only) and carries on. A probe or read that fails for any other reason (a timeout, an access error, a locked store) fails setup with the store and item named. Before creating it, setup lints and imports aimux’s own provider profile aimux-github (sandbox/aimux-tools/github-profile.yaml) into the workspace when the gateway lacks it, and creates the provider with --type aimux-github. Its id is not github, so OpenShell’s built-in github profile is never the one attached. aimux’s profile is the stock OpenShell one trimmed to the api.github.com endpoints and /usr/bin/gh: the stock profile also opens github.com git transport to the git binaries, and an attached provider adds its profile’s endpoints to the sandbox’s effective policy. The token goes to openshell provider create in GITHUB_TOKEN in its environment, never on a command line.