Sandbox

Local development

host has the least setup and does not inject vault env. It runs every office in one filesystem, so it cannot enforce a private office’s visibility and is a trusted deployment.

Mainline isolation

oci:<image> lets mikan manage lifecycle, workspace mounts, vault env, and resource limits.

What the sandbox is for

oci:* targets a team sharing one VM. Each office gets resource limits, an isolated filesystem, and its own environment. It is not a hostile multi-tenant boundary like E2B or a SaaS sandbox: containers share the host kernel and everyone on the VM is trusted. Credentials enter the sandbox only because development work (gh, gcloud, gws) needs them.

Mode names

docker:* is not a supported mode; use container:* or oci:* instead.

Supported modes

Mode	Execution location	Vault env injection	Vault key	Notes
host	host machine	not injected	derived from the platform user	Local development only; requires a trusted read-write projection
container:<name>	existing Docker container	injected	derived from the container name	one container one vault; multiple people sharing one container also share its vault
oci:<image>	OCI container managed by mikan	injected	the office key	Current recommended isolation mode; 1 conversation = 1 vault = 1 container

The office key is the versioned v1-<platform>-<readable-id>-<hash> segment that also names the conversation’s directory under the workspace. See Conversation offices.

Conversation offices

Each conversation owns one directory under the workspace root — its office — named by office key rather than by the platform’s raw conversation id. Sandbox mounts follow that directory, so inside a runtime the office is at /workspace/<office-key>.

Which parts of the workspace a runtime sees follows the office’s visibility (ADR 0008), derived from the Slack conversation type: public channels are public; private channels, DMs, group DMs, externally shared channels, and unknown kinds are private. Every office gets the same mount shape; only the read-only flags differ:

Mounted under /workspace	Public office	Private office
<office-key>/ — the office itself	read-write	read-write
MEMORY.md, skills/ — shared knowledge	read-write	read-only
public/<office-key>/ — every public office	read-only	read-only

Nothing mounts the workspace root. The admin portal or /pi-sandbox visibility private can narrow a public channel; nothing can widen beyond Slack. Only oci:* enforces visibility; the other modes report managedProjection: false and serve a private office with a one-time logged warning. Field semantics and the retired door-policy settings are documented in Configuration.

Visibility is not an extra sandbox

Visibility decides which host directories are projected into the runtime. It is not an execution boundary: host mode runs tools directly on the host with no filesystem or process isolation whatever the office’s visibility.

Upgrading from the raw-id layout

0.5.3 workspaces hold directories named by raw conversation id. mikan migrate moves them to the office layout, together with their vaults, settings, sessions, and events; see Upgrading from 0.5.3.

Per-mode docs

Host sandboxRun tools directly on the host; best for local development.

Container sandboxConnect to an existing Docker container and reuse your own lifecycle management.

OCI sandboxLet mikan manage per-conversation containers and resource limits.

Capability differences

oci:<image> recommended is the primary developed and recommended sandbox mode today; the other modes are kept for local development, compatibility, or experiments, and some capabilities will not be filled in.

Capability	host	container:<name>	oci:<image>
command execution	✅	✅	✅
mikan-managed runtime lifecycle	not applicable	❌	✅
per-conversation container / runtime	❌	❌	✅
per-conversation vault env	❌	❌	✅
automatic vault file projection / bind mount	❌	❌	✅
automatic workspace mount	host	self-managed	✅
enforced office visibility	❌	❌	✅
idle auto-stop / recreate	not applicable	❌	✅
default CPU / memory limits	❌	❌	✅
/pi-sandbox boost	❌	❌	✅
agent sandbox tool sets limits	❌	❌	✅
recommendation level	local dev	legacy / compatibility	mainline

Most ❌ rows are refusals rather than silent downgrades. The exception is office visibility: a mode that cannot enforce it logs Sandbox '<type>' cannot enforce private office visibility once per office and continues, because those modes are trusted deployments by definition. A mode that cannot mount vault files raises Sandbox type "<type>" does not support vault file mounts instead of running without the credential. On modes that cannot project files, keep vault credentials in env only.