Sandboxes

A Nimbus sandbox is a persistent cloud machine tied to a repository and user session. It contains the checkout, toolchain, runtime bridge, terminals, desktop server, and preview tunnels.

Lifecycle

Sandboxes move through a small set of lifecycle states:

• creating: Nimbus has requested a new cloud machine.
• setting_up: bootstrap scripts are installing runtime tools and cloning the repository.
• running: the workspace is available for agent turns and interactive tools.
• sleeping: the machine has been stopped and snapshotted after inactivity.
• failed: setup or runtime health checks require intervention.

Persistence

The filesystem persists across sleep and wake. Running processes do not persist. Dev servers, terminals, desktop sessions, and agent processes are relaunched when the sandbox wakes.

Sleep and wake

Nimbus keeps active sessions awake while agents, terminals, desktops, or forwarded ports are in use. Idle sessions sleep automatically. Sending a message, opening an interactive terminal, or using desktop access wakes the sandbox.

Runtime bootstrap

The bootstrap process installs the tools Nimbus needs inside the sandbox:

• Codex and agent bridge runtime
• GitHub and account configuration
• Terminal and tmux support
• Desktop and browser support
• Preview port routing

Cleanup

Delete disposable sandboxes when a test run is complete. This avoids clutter and keeps runtime usage predictable.