Execution credentials and trust boundaries¶
Commands and agents execute arbitrary code. Native agent adapters require an
explicit operator authorization policy, described below. Other executors without
security declarations retain trusted native execution: host network, host
filesystem and the configured agent HOME. Worker logs identify native versus isolated execution.
Native execution is not a filesystem sandbox. Adapters that require host execution
also require the operator's existing executor allow permission.
Declare restrictions in execute params, for example:
{
"executionPolicy": {
"required": true,
"allowedCapabilities": ["command"],
"allowedSecrets": ["service"],
"trust": "restricted",
"network": "none",
"filesystem": "scratch"
},
"secretRefs": {"service": "service-production"},
"isolation": {"mode": "required", "runtime": "bwrap"}
}
Restricted execution requires an enforced isolation driver. Missing drivers,
unsupported platforms and native fallbacks fail closed. The current Linux bwrap
and OCI drivers disable network access and expose writable attempt scratch.
Host workspace access must be declared separately using workspace-read-only
with workspaceMode: "read-only", or workspace-write with
workspaceMode: "shared-write". Shared writes acquire an implicit exclusive
workspace reservation through durable coordinator admission; explicit concurrency
keys can additionally protect external resources. An omitted
filesystem declaration on a restricted attempt grants scratch access only.
OCI also requires an operator-approved Linux image. macOS can opt into Docker
Desktop with {"mode":"required","runtime":"docker-vm","enabled":true,
"image":"your-approved-image"}. The legacy macos-vm runtime selects the same
backend. It explicitly uses the desktop-linux Docker context; missing Docker
Desktop, images or permissions fail execution without native fallback. There is
no bespoke hypervisor to install or maintain. These are process boundaries, not interception of agent tool calls.
They do not constrain execution performed by a remote provider's service.
The backend interface lives in muxlio-core/internal/sandbox; workers dispatch
it independently of agent adapters. Successful execution logs include structured
boundary capabilities:
| Backend | Network | Filesystem | Processes | Host credentials |
|---|---|---|---|---|
native-trusted |
Host | Host | Host | Accessible through host files |
bwrap (Linux) |
None | Scratch, system binaries/libraries and declared mounts | Linux namespaces | Only explicitly supplied credentials |
oci (Linux Podman/Docker) |
None | Image, scratch and declared mounts | Linux namespaces | Only explicitly supplied credentials |
docker-vm (macOS Docker Desktop) |
None | Image, scratch and declared mounts | Namespaces inside a shared Linux VM | Only explicitly supplied credentials |
Docker Desktop containers share the VM kernel; they are not a dedicated microVM
per agent. Docker Sandboxes (sbx) is a separate product with its own workspace,
network and credential policies; it is not automatically selected or treated as
equivalent to an offline backend. New integrations must implement the backend
contract and pass conformance before operators advertise them.
Workspace capabilities distinguish private-clone (an independent regular-file
snapshot in scratch), read-only-host, and writable-host. A private clone
prevents accidental concurrent workspace edits from colliding but provides no
OS containment under native execution. Shared writes deliberately change the
host source and still require exclusive resource admission. Isolation does not
remove secrets already present in a supplied workspace, image or adapter bundle.
Containers run without Linux capabilities, with no-new-privileges, a process
limit and a read-only image filesystem; their guest HOME and TMPDIR are scratch.
Container cleanup removes the named container after execution or cancellation.
The container CLI retains the operator's host runtime configuration; it does not
inherit the guest's scratch HOME. The pinned environment allowlist filters values
passed to the guest, and ambient host environment variables are never implicitly
forwarded there. Images run the selected adapter as their explicit entrypoint. Pinned task
readiness probes run through the same backend and environment filter before
work starts; they do not execute natively when required isolation is unavailable.
Worker registration probes still inspect the operator-managed host environment.
Before advertising a backend, run its real boundary conformance on the worker:
cd muxlio-core
MUXLIO_SANDBOX_CONFORMANCE=bwrap go test ./internal/sandbox -run TestBackendConformance -v
MUXLIO_SANDBOX_CONFORMANCE=oci MUXLIO_SANDBOX_IMAGE=your-approved-image go test ./internal/sandbox -run TestBackendConformance -v
# macOS, with Docker Desktop running:
MUXLIO_SANDBOX_CONFORMANCE=docker-vm MUXLIO_SANDBOX_IMAGE=your-approved-image go test ./internal/sandbox -run TestBackendConformance -v
The image must already be available and match the host CPU architecture. Tests compile a static Linux probe and exercise actual filesystem reads/writes, network interfaces and host socket access, process visibility, credential inheritance, read-only versus writable mounts, and simultaneous independent scratch trees. An explicitly selected unavailable backend fails the test. Without explicit selection, the suite tests installed Linux bubblewrap or skips with a reason; a skipped test does not qualify a backend. Re-run after runtime/config changes.
The operator configures each worker executor with handle-to-environment-name mappings, for example:
Only declared, allowlisted names resolve, immediately before execution on that
worker. A handle cannot read arbitrary environment variables. Missing or denied
handles fail without disclosing their values. Retries resolve handles again.
The adapter receives resolved values through its existing stdin secret contract;
the durable assignment contains handles only. Transient local Secrets values
are excluded from JSON and refused by durable coordinator dispatch.
Execution parameters containing conventional credential fields (such as
secrets, password, API_KEY or authorization) are rejected before a plan is
pinned. Do not embed credentials in task prose, source code, bindings, handles,
run inputs or arbitrary parameters: arbitrary strings cannot reliably be
identified as credentials. Worker result fields and progress logs redact known
execution credentials, including secret-bearing configured environment values.
Artifact publication rejects files containing those values, and snapshots skip
them. Redaction does not protect against malicious code that encodes or sends
credentials elsewhere; give only necessary credentials to trusted code.
Scoped API credentials¶
The administrator token authorizes the complete control plane. The existing
cluster worker token trusts its holder with all worker identities and artifact
transfer. Use separate scoped credentials for remote workers or clients that
must not have those powers. Set accessGrants in the coordinator configuration:
{
"accessGrants": [
{"tokenFile":"client-a.token","runId":"run-a","permissions":["read","signals"]},
{"tokenFile":"submitter.token","permissions":["submit"]},
{"tokenFile":"catalog.token","permissions":["workspaces:read"]},
{"tokenFile":"controller.token","runId":"run-a","permissions":["control"]},
{"tokenFile":"worker-a.token","workerId":"worker-a","permissions":["worker","artifacts:read","artifacts:write"],"artifactDigests":["sha256:..."]}
]
}
Credential files are relative to the configuration directory or absolute. Keep
them protected and deliver their values as bearer tokens over TLS outside trusted
local networks. Worker credentials and scoped grants reload on every API request; replacing token
files or removing/revoking grants affects subsequent requests. Restart workers with
new credentials after rotation. The administrator token is fixed at server startup.
No scoped credential may list all runs or access another run. submit separately
authorizes creating runs and submission preflight; it does not grant read or
control access to the resulting run. Provision a run-scoped grant separately
when those operations are needed.
workspaces:read authorizes only the workspace catalog endpoint, including
configured digests. Issue it on a grant without a run or worker ID. Submit,
run read, and worker credentials do not imply catalog access. The catalog
requires a bearer credential on loopback and private-network connections too.
read, control (pause/resume/cancel/retry), signals, and steer are independent
permissions. steer authorizes session input delivery at
/v1/runs/{runId}/sessions/{sessionId}/inputs, subject to queue permissions and
advertised adapter input capabilities. Worker registration and protocol URLs must match the
grant's worker ID. Artifact permissions require an explicit digest allowlist;
read permission cannot request a PUT transfer plan. Empty scopes grant nothing.
Unauthenticated requests from remote addresses fail closed even when no tokens
are configured. Health checks remain public. GET /v1/auth checks a credential's
current validity without granting resource access; it returns 204 for an active
identity and denies revoked, expired, invalid or missing credentials.
Remote web and MCP access¶
Keep the default loopback bind and use SSH forwarding for the easiest remote
setup (ssh -N -L 17600:127.0.0.1:7600 host, then open
http://127.0.0.1:17600/). Loopback UI requests receive automatic operator
credentials. Same-origin UI requests from private-network peers also receive
them when the Host is a private IP literal, such as 192.168.1.1; this supports
trusted LAN access while preventing public DNS names from rebinding to the
coordinator. Cross-origin and cross-site browser requests are rejected, including
requests with explicit bearer credentials. Forwarded headers do not establish
trust.
Explicit credentials retain their scopes even on loopback. Empty, malformed, or
duplicate Authorization headers are rejected instead of falling back to local
operator access.
For an explicit remote deployment, use HTTPS with a valid certificate, separate client grants, and an authenticated gateway for browser access. The UI has no browser login form: the gateway must authenticate each user and attach that user's scoped bearer credential to API requests. Validate the external browser Origin at the gateway; preserve the original Host and scheme through an HTTPS upstream, or remove Origin only after validating it when proxying to a different upstream origin. Do not forward unauthenticated requests to a loopback upstream with a rewritten loopback Host. Do not use a shared administrator token for all remote users. Binding HTTP publicly does not authenticate anyone. Public HTTP exposes bearer credentials in transit; use TLS or an SSH tunnel.
MCP HTTP accepts coordinator client grants directly as bearer credentials and
forwards each client's identity independently. Coordinator authorization remains
authoritative for each operation; tool annotations are advisory metadata only.
The separately configured listener credential is a trusted gateway credential
using the configured upstream identity, so protect it like that identity. File-based
build and test are restricted to local stdio MCP because they access the MCP
host outside coordinator authorization. HTTP clients can validate inline JSON
using check_plan without reading files or executing source on the MCP host.
Advertising available isolation backends¶
Enable backends on each execution host in its operator-owned config.json:
Use oci on Linux for Podman/Docker, or docker-vm on macOS for Docker Desktop.
Both embedded and standalone workers verify the platform and launcher before
advertising muxlio.dev/isolation/<backend>=true. Missing launchers fail startup;
execution still validates the daemon, image and boundaries for each attempt.
VM tasks also require the existing task-level enabled: true opt-in. Installing
a launcher alone does not enable a backend.
Unattended native agent authorization¶
executors.<capability>.authorization in the worker's local operator config is
independent of the submitting client's API credential and task executionPolicy.
The worker copies this typed policy into the adapter request immediately before
launch. Coordinator state, workflow task text, inputs, params, model output and
client setup never grant or replace it. Client permission to submit work and the
worker's permission to perform it are separate grants. Direct adapter callers
are trusted execution hosts and must protect their stdin envelope accordingly.
The existing executor allow host-execution gate remains an independent check.
muxlio init supplies all-allowed operator policies for bundled executors by
default: allow: true, trusted mode, all tools and commands, workspace writes,
network access, and native isolation. Operators can restrict individual executors
in config.json. Repeated init fills missing settings while preserving explicit
policies, disabled executors, and null policies. --allow-command remains an
explicit way to re-enable command execution after it has been disabled.
Outside those initialized defaults, missing authorization denies generation in
all five bundled native agents. A
restricted policy defaults to no tools or commands and no writes. Both network
and isolation must be explicit. Tool names are generic: read-file,
write-file, shell, network, or *. allowedCommands describes allowed
commands; an empty list denies commands. A mapping must reject any command or
tool scope it cannot enforce; this implementation does not translate command
strings into permissive shell prefix patterns. Network none refers to tool
traffic; connecting to the model API is still required. isolation: required
requires an enforced worker backend even if a task requests trusted native
execution. It never silently falls back. Native CLI permissions alone are not
OS isolation, and cannot contain malicious runner software.
For explicitly trusted high-autonomy jobs, configure each capability separately:
{
"executors": {
"agent/claude": {
"allow": true,
"authorization": {
"mode": "trusted",
"allowedTools": ["*"],
"allowedCommands": ["*"],
"workspaceWrite": true,
"network": "allowed",
"isolation": "native"
}
}
}
}
Trusted mode requires all unrestricted grants explicitly. compatibility is an
operator-approved migration mode with the same explicit grants. For Codex it
retains --approve-for-me auto-review; trusted mode selects the explicit bypass
flag. Compatibility never restores automatic policy defaults
or broad shell environment inheritance. Codex uses
shell_environment_policy.inherit=none in both modes. Supply necessary tool
credentials through the existing explicit secret contract, rather than ambient
shell inheritance. For the other native agents compatibility uses the same
explicit bypass mapping as trusted mode. These modes trust workspace hooks,
plugins and tools with the execution host's accessible credentials and files.
Runner versions are unconstrained unless the client explicitly pins them in the environment manifest. Adapters collect version evidence when available; an unlisted or unavailable version does not block an unpinned run. Explicit pins still require matching version evidence. CLI invocation errors are reported by the owning adapter.
| Native agent | Restricted policy | Trusted / compatibility |
|---|---|---|
| Claude | Restricted and safe modes, empty MCP configuration, explicit file tools, dontAsk, no permission prompts; no shell/network tools |
Explicit bypass permission mode |
| Codex | Rejected: full tool/MCP/hook enforcement is unqualified | Bypass / automatic approval review |
| Cursor | Rejected: full restrictive enforcement is unqualified | Explicit run-all and workspace trust |
| Kiro | Rejected: selective tool trust does not prove workspace hook or network containment | Explicit all-tools and workspace trust |
| Antigravity | Rejected: sandbox/plan flags do not prove the full contract | Explicit skip-permissions |
For Claude file-only execution, use mode: restricted, allowedTools:
["read-file", "write-file"], empty allowedCommands, workspaceWrite: true,
network: none, and an explicit isolation choice. File tools are confined by
restricted mode to the working roots, including the declared output scratch.
No tool is exposed by default. An unknown mode, field or unsupported restriction
fails before generation. CLI upgrades do not require an allowlist update.
Shared worker and coordinator code must never select CLI flags.
The policy log records accepted and denied attempts with a valid policy (including
missing-policy denials). It records the SHA-256 digest, mode, tool/command counts, writes,
network and isolation requirements, without command strings or environment
values. Registration readiness probes remain read-only and do not qualify
permission enforcement.
Run the deterministic adapter, worker and cross-adapter conformance tests first. Live qualification is opt-in because it starts billable generations with the operator's existing login:
cd muxlio-adapters
MUXLIO_LIVE_AUTHORIZATION=all go test ./tests/conformance -run '^TestNativeAuthorizationLive$' -v -count=1
# Or select one or more agents, e.g. MUXLIO_LIVE_AUTHORIZATION=claude,codex
The probe verifies an edit and shell content test under the trusted policy and a denied shell operation under restricted policy, including prompt-based elevation attempts. Claude also must copy an unpredictable fixture through its restricted file tools; trusted-mode success alone does not qualify those grants. Unsupported restrictive mappings must reject before generation. All runs are noninteractive with deadlines and Unix process-group cleanup of the adapter, runner and child tools. Explicit live selection on other platforms fails until equivalent process containment is implemented. An explicitly selected missing CLI, authentication failure, backend failure or timeout fails the probe; it is never counted as successful denial. Run live qualification on the actual execution host before enabling a mapping; argument fixtures alone do not prove successful live enforcement. ACP/A2A transport adapters retain their separate protocol trust contracts and are not native CLI mappings.
Workflow compilation¶
The recommended validation path for untrusted or agent-generated submissions is
JSON Plan IR: use MCP check_plan (an in-memory JSON document), or build/test
with a .json file. These paths never execute TypeScript, JavaScript, imports,
package scripts, or compiler hooks. Catalog templates also produce JSON without
Node. Do not compile source merely to validate generated definitions.
Loading .ts, .js, or .mjs executes arbitrary code before Plan IR validation.
This includes CLI build, check, test, and run, and MCP build/test.
CLI source commands compile directly. MCP requires trustedSource: true on
each source call. The tool descriptions and
rejection messages expose the risk before execution. This acknowledgement is
not a sandbox or a substitute for reviewing the source and dependencies.
Compilation invokes only project-local tsx 4.23.15 using Node, checks its
package version, and never invokes npx or installs packages. Install the root
lockfile explicitly with npm ci in a trusted environment. The version check is
not an integrity check against malicious local dependencies: the workflow,
Node binary, and installed dependency tree must all be trusted.
The compiler receives an allowlisted environment (PATH, a disposable HOME and TMPDIR, MUXLIO_COMPILE, a fixed NODE_OPTIONS heap limit, and disabled tsx caching). Operator environment tokens and Node injection hooks are not forwarded. Compilation stops after 30 seconds, 8 MiB of stdout, or 64 KiB of stderr. Node's V8 heap is capped at 256 MiB; this is not a total process-tree memory cap. On Unix, cancellation and cleanup after compiler exit kill the compiler process group, including remaining descendants; on other platforms cancellation kills the direct child and bounds pipe draining. These are resource safeguards for trusted code, not protection from deliberately hostile code.
Source compilation still has host filesystem and network access. A disposable
HOME does not prevent reading credentials by absolute path. Worker isolation
policies in internal/sandbox apply to worker execution, not authoring, and
must not be presented as compiler isolation. If source compilation is necessary,
run the compiler on a separate disposable host/container under a dedicated
identity, with only the reviewed workspace and dependencies mounted, no
operator credentials, network denied, and OS memory/process limits. Transfer
only the resulting JSON Plan IR to the operator's MCP host for check_plan and
submission. Never compile source on a host that handles unreviewed definitions.