---
title: "Sandbox"
description: "Compare mikan's supported host, container, image, microVM, and Firecracker sandbox modes."
url: "https://geminixiang.github.io/sandbox/"
---

# Sandbox

`host` has the least setup and does not inject vault env, making it suitable for development on trusted machines.
    `image:<image>` lets mikan manage lifecycle, workspace mounts, vault env, and resource limits.
    `gondolin:default` runs a local Gondolin/QEMU VM and is the planned successor to managed `image:*` sandboxes.

  `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

<LinkCard
  title="Host sandbox"
  description="Run tools directly on the host; best for local development."
  href="host/"
/>
<LinkCard
  title="Container sandbox"
  description="Connect to an existing Docker container and reuse your own lifecycle management."
  href="container/"
/>
<LinkCard
  title="Image sandbox"
  description="Let mikan manage per-conversation containers and resource limits."
  href="image/"
/>
<LinkCard
  title="Gondolin sandbox"
  description="Try the local Gondolin/QEMU preview intended to replace image sandboxes."
  href="gondolin/"
/>
<LinkCard
  title="Firecracker sandbox"
  description="Connect to a Firecracker VM that you start yourself."
  href="firecracker/"
/>
<LinkCard
  title="Remote task executor"
  description="Not a sandbox mode: a tool for throwaway, parallel commands in a remote sandbox."
  href="../remote-task/"
/>

## Capability differences

`image:<image>` <Badge text="recommended" variant="success" /> 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           |