A sandbox service you host, as a resident runtime
OpenSandbox is a self-hosted sandbox-as-a-service stack. Each workspace is one sandbox created from the Grove runtime image, and Grove drives it through the server's own lifecycle API. The worker inside dials the daemon exactly as it does on every other resident platform.
sequenceDiagram
participant D as Grove daemon
participant R as OpenSandbox driver
participant O as OpenSandbox API
participant S as Sandbox
participant W as grove-native-worker
D->>R: up(workspace spec)
R->>O: POST /sandboxes from the runtime image
O->>S: start it, entry process the worker
R-->>D: sandbox id saved on the workspace record
S->>W: run the worker, which clones the branch
W->>D: dial out, GET /mailboxes/connection
D-->>W: mailbox messages and steer frames
How a workspace maps onto a sandbox
One workspace is one sandbox, and the sandbox id is the only thing Grove needs to find it again.
- Up creates a sandbox whose entry process is the worker. The worker clones your repository and checks out the workspace branch itself, so nothing dials into the sandbox.
- Outbound traffic is denied by default. The sandbox may reach the daemon, your git host and the hosts you list in
allow_hosts, such as your model API. Grove never relies on the server's own default. Each name is allowed together with the addresses it resolves to when the sandbox is created, because a server that enforces egress at both the DNS and the firewall layer drops a connection to an address it was not told about. An address can front several services, so that layer is wider than the name. - Status reads the sandbox's own state, and a server that does not answer reads as unknown rather than a guess.
- A quota or capacity refusal is final. The server's quota and pool answers are reported as a refused create and never retried.
- Removing a workspace deletes its sandbox. One that is already gone counts as removed.
Freeze, thaw and eviction
OpenSandbox can pause a sandbox but cannot stop one and keep it, so both freeze and stop are a pause.
- Freeze pauses the sandbox in place after the worker pushes its branch. Memory stays resident, so a thaw picks the agent up mid-thought.
- Stop is also a pause, marked in the sandbox's metadata so a stopped workspace never reads as frozen.
- Thaw resumes the same sandbox. Its id is stable across pause and resume, so the handle never changes.
- A host reboot loses a paused sandbox on the Docker backend. A thaw that finds it gone starts a fresh sandbox on the pushed branch with a new session, since the conversation lived inside the old one.
- A workspace frozen for a while longer hibernates. Grove snapshots the sandbox, pushes a
snap-tag to the runtime image repository and only then deletes the sandbox, so it holds no memory and no local disk. Setsnapshot_registryonly to override that repository. The next message restores the same session and keeps the snapshot until the worker reconnects, so a failed restore can be retried.
Configuration
{
"runtimes": {
"sandbox": {
"kind": "opensandbox",
"image": "registry.example.com/grove/runtime:latest",
"url_env": "OPEN_SANDBOX_URL",
"api_key_env": "OPEN_SANDBOX_API_KEY",
"image_auth_user_env": "REGISTRY_USER",
"image_auth_password_env": "REGISTRY_PASSWORD",
"resources": {"cpu": "2", "memory": "4Gi"},
"allow_hosts": ["api.example.com"],
"registry_user_env": "REGISTRY_USER",
"registry_password_env": "REGISTRY_TOKEN"
}
}
}
The server URL and API key are read from the variables url_env and api_key_env name, and the driver adds the /v1 API path itself. A runtime image in a private registry takes its credential from the two image_auth_*_env variables. resources is required, because the server refuses a sandbox with no limits. Leave timeout_seconds unset for a sandbox that never expires. Hibernation needs a docker client reaching the same engine as the OpenSandbox server, and idle.hibernate_after_seconds sets how long a frozen workspace waits, 0 to never hibernate. Every field is in the Configuration Reference.
Grove verifies the server's TLS certificate with the Python 3.13+ strict X.509 rules and never relaxes them, so a self-hosted stack behind a private CA needs a CA certificate whose Basic Constraints extension is marked critical. A failure reads Basic Constraints of CA cert not marked critical on the first create, while the snapshot push is unaffected because the docker client verifies on its own, and re-issuing the CA repairs every client on the network. Add the root to Grove's trust through the GROVE_TLS_CA_PATH variable when the operating system store does not already carry it.