Sandbox execution
Follow runtime preparation, environment boundaries and agent code execution.
In this topic
The sandbox gives agent tools an isolated execution environment with a managed lifecycle, working resources, and a controlled connection back to Mellow. It is one execution boundary inside the app; it does not replace the permissions required by native Mac tools, a browser, or an external service.
Establish which runtime is available
The Linux sandbox implementation uses Apple's containerization and virtualization facilities. Availability depends on the Mac, operating-system version, app build, and installed runtime assets. Builds can also expose a more limited host-side fallback where supported. A fallback should be identified as such; it does not provide the same isolation boundary as a Linux guest.
Check the app's sandbox status before troubleshooting an individual command. Separate unavailable, not provisioned, starting, running, and deliberately stopped conditions. Starting the app is not proof that the guest has finished provisioning.
Provisioning and artifact integrity
The manager resolves a pinned sandbox image and a guest kernel. Release bundles can include runtime resources; development builds may need a download or a locally imported image. Artifact checks validate expected hashes and bound download size before use.
The inspected source explicitly distinguishes a verified local image build from a published registry image. Do not assume a fresh installation can pull a particular image merely because a developer's existing cache boots successfully. Validate provisioning from the release's intended distribution path.
A hash mismatch should stop provisioning and remove the failed artifact. Replacing the expected digest with a downloaded file's digest to silence the error would defeat the check.
Shared guest, agent-specific resources
SandboxManager serializes guest lifecycle operations. Per-agent provisioning establishes the resources and identity used by an agent inside that environment. Tools must resolve the current agent rather than treating the shared guest as one unrestricted global workspace.
The guest image provides common development runtimes and utilities according to its build recipe. Additional packages or plugin dependencies can require installation and network access. Check actual readiness instead of assuming an executable exists because another image version included it.
Warm starts can reuse an on-disk root filesystem. That changes startup work but does not eliminate the need to verify plugin state and per-agent resources. A cold-provisioning test and a warm-restart test exercise different paths.
Tools and approval
An agent may discover file, process, and package-related capabilities according to its current scope and configuration. Discover the current schema through Mellow rather than hardcoding every tool name in a client. Read-only inspection and executable commands can have different authorization requirements.
A successful shell launch should return enough information to monitor its outcome. Background execution needs a process or task identifier, completion state, exit status, and output retrieval path. Do not convert “started” into “finished” in the final response.
Path validation must happen before filesystem access. Relative paths, symlinks, mounted resources, and per-agent homes require consistent boundaries. Test escape attempts and missing paths alongside the normal case.
Host bridge and secrets
The host bridge connects selected guest operations to Mellow over a managed socket transport. The guest-side socket is /tmp/mellow-bridge.sock. Agent tokens are stored under /run/mellow with file permissions and ownership intended to keep one agent from reading another agent's credential.
A bridge token is not a general-purpose cloud credential. The bridge still enforces operation and agent scope. Keep bridge request limits and authentication intact when adding a new operation.
Secret tools should obtain or check credentials through the supported secure flow. Never write real keys into a plugin recipe, container image, agent instruction, or shared log. Confirm that a secret's intended destination is the operation requiring it, not the model's visible conversation.
Network policy is separate from reachability
The sandbox can have open, restricted, or unavailable network access according to its configuration. In an allowlist mode, egress is mediated; system package installation can use a package-registry-scoped credential rather than widening an agent's policy.
The fact that a host can reach a URL does not prove the guest may reach it. Similarly, changing the app's Global Proxy does not itself grant every sandbox process unrestricted network access.
Operate and recover deliberately
An explicit Stop is different from a guest failure. The manager tracks that distinction so automatic recovery does not undo a user's deliberate stop. Before removing runtime resources, understand whether you are deleting a cache, guest filesystem, plugin installation, or agent data.
For a failed start, collect availability, artifact verification, provisioning, networking, and bridge errors in sequence. For a failed tool, first establish a running guest and the correct agent identity, then check path scope, dependencies, approval, and process output.
Release verification checklist
Exercise a clean provision, warm restart, agent separation, allowed and denied network requests, secret prompt, process cancellation, explicit stop, and app relaunch. Confirm that the release artifact contains or can obtain every required resource. Source landmarks are SandboxManager.swift, SandboxRuntimeAssets, the agent provisioner, bridge services, and sandbox tool registrar.