Sandbox

Local development

host has the least setup and does not inject vault env, making it suitable for development on trusted machines.

Mainline isolation

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

Gondolin preview

gondolin:default runs a local Gondolin/QEMU VM and is the planned successor to managed image:* sandboxes.

Mode names

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

Supported modes

Mode	Execution location	Vault env injection	Vault key semantics	Notes
host	host machine	not injected	can store, but unused at run time	Best for local development; does not put vault env into the host process
container:<name>	existing Docker container	injected	container-<name>	one container one vault; multiple people sharing one container also share its vault
image:<image>	Docker managed by mikan	injected	generated conversation vault	Current recommended isolation mode; 1 conversation = 1 vault = 1 container
gondolin:default	local Gondolin/QEMU VM	injected	generated conversation vault	Preview; supports private/full workspace mounts; requires Node.js >=23.6 and QEMU
firecracker:<vm-id>:<host-path>[:<ssh-user>[:<ssh-port>]]	Firecracker VM	injected	generated conversation vault	Very early alpha; you must start the VM and mount workspace at /workspace; not recommended yet

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.

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

Gondolin sandboxTry the local Gondolin/QEMU preview intended to replace image sandboxes.

Firecracker sandboxConnect to a Firecracker VM that you start yourself.

Remote task executorNot a sandbox mode: a tool for throwaway, parallel commands in a remote sandbox.

Capability differences

image:<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>	image:<image>	gondolin:default	firecracker:*
command execution	✅	✅	✅	✅	✅
mikan-managed runtime lifecycle	not applicable	❌	✅	✅ in-process	❌
per-conversation container / runtime	❌	❌	✅	✅	self-managed
per-conversation vault env	❌	❌	✅	✅	✅
automatic vault file projection / bind mount	❌	❌	✅	✅	❌
automatic workspace mount	host	self-managed	✅	✅	self-managed
private workspace mount mode	not applicable	❌	✅	✅	❌
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	preview	alpha