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.
The compile chain
Section titled “The compile chain”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 vresolved Manifest | toolreg.Snapshot internal/toolreg/snapshot.go | registry + pins, one version; "google:readonly" -> | server + listed tools pinned (not source_changed) vprofile.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 rendererCompile 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.
What each output feeds
Section titled “What each output feeds”- (a) Policy.
buildPolicyturns the manifest, the grant and the gateway address into the OpenShell policy.PolicyDigestis a sha256 over the YAML. It keys the sandbox’s policy, so a new pin changes it. The manifestDigestis 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 thattoolgateway.Tokens.Issuecreates (internal/toolgateway/tokens.go); the same grant is what the policy allows, what the MCP config lists and what--allowedToolsnames, 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 fromCompiled.Grant); Launch is how this run starts (from the engine, per turn). Launch modes are harness-neutral: the claude adapter mapsheadlesstoclaude -pandinteractiveto ACP. For headless,claudePrintturns them into flags:--tools,--strict-mcp-config,--mcp-config,--allowedTools,--setting-sources ""unless the profile inherits user settings,--model, and--resumeor--session-id.
At run time
Section titled “At run time”profilerun.SandboxEngine (internal/profilerun/sandbox.go) does this for each turn:
- Calls its
Compilefunction:profile.CompileAtover the turn’s snapshot of the registry and pins, recorded inCompiled.Snapshot. Inremote servethe snapshot comes from atoolreg.Storethe turns reload when the registry or pins file changed (time, size, inode) and once a minute as a backstop (toolSnapshotsininternal/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 poolmcpproxy.Serveowns, retiring only moved or dropped backends. - Ensures the sandbox
aimux-<profile>exists with that policy (ensure, throughinternal/sandboxlaunch). - Asks the harness adapter for a Spec from the compiled Capabilities (with the turn’s model, if chosen) and a Launch: headless mode,
--session-idon the first turn,--resumeafter. - 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. - Runs
claudethroughLauncher.Execwith 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.
The tool runner sandbox
Section titled “The tool runner sandbox”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):
-
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 (forgh,aimux-github) is left out of the policy and shows as down with an error naming the Keychain item andaimux sandbox setup; the other sources keep running.aimux tools status,aimux tools diff,aimux doctorand setup’s tool review are read-only: they list aclisource only whenaimux-toolsalready exists and is Ready (running<binary> --versionin it), and otherwise show it as down withtool 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. -
<binary> --versionat 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’sx-aimux-binaryannotation, so aghupgrade changes everyghtool’s pin: the tools stop being served until you approve them again. A binary replaced under a running backend (a rebuiltaimux-tools) is seen at the next listing, and calls are refused as changed from then until the tools are approved again. -
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’spolicy_deniedbody 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 runaimux 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. - Missing: Ensure creates it again; if that fails (no image, no gateway),
HTTP sources
Section titled “HTTP sources”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:
- 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%2Fand 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. - 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, thenaimux tools approve. Later listings do not move that baseline; approving makes a new tool snapshot, which restarts the backend with a new one. - 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-wstatus line goes to stderr with the HTTP status and theX-OpenShell-Policyheader. - Results as for
clicalls: 30 seconds, output cut at 256 KiB, a runner that went away ensured once and the call retried once. A 403 withX-OpenShell-Policyand apolicy_deniedbody is reported as the network policy refusingGET <path>; the API’s own errors come back asHTTP <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>, percliorhttp-openapisource with at least one active pin (a pin the gateway serves, so notsource_changed). Unapproved sources open nothing. - A
clisource gets its pack’s endpoints and binary. Forghthat isapi.github.comREST withaccess: read-onlyand/graphqlwith a rule allowingoperation_type: query, for/usr/bin/ghonly. - An
http-openapisource gets one REST endpoint on its base URL’s host (a plain public hostname: no IP literals,localhost,.internalor.localnames, and not the model host), with aGETrule 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.comforgh), 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 eitheraccessorrules, never both (OpenShell rejects that). - No model host and no tool gateway: the runner has neither
api.anthropic.comnorhost.containers.internal. - Files:
/tmpand/dev/nullare 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).
The GitHub provider
Section titled “The GitHub provider”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.