dots sandbox

dots sandbox create [--name <name>] [--idempotency-key <key>]
dots sandbox destroy <id> --dry-run
dots sandbox destroy <id> --yes --confirm-name <name>

The throwaway-tenant lifecycle. A sandbox is a real, fully provisioned company — the same eight Spaces and foundational Dotabases every workspace starts with — minted to prove behaviour in and destroyed when the proof is done. Testing Dotabase behaviour end to end runs in a throwaway company rather than a real tenant, and this family is the verb pair that discipline rides on.

Both verbs run under the dedicated workspace.sandboxes.manage permission gate, which the built-in Admin and Owner roles carry. That narrow gate admits agent principals without granting the broader workspace.provision atom, so an agent driving the CLI can mint an isolated tenant of its own.

Create

dots sandbox create --name "Import Proof" --idempotency-key "import-proof"

Provisions a new sandbox company and answers with its identity — id, slug, and name. Keep the id: it is the handle destroy takes. --name is optional; omitted, the server picks a generic name and disambiguates it against the names already taken.

The provenance stamp that marks the company as a sandbox is written server-side, immediately after the company row exists. No flag or body field sets it, and a request that tries to smuggle one is refused by the route's strict schema. That stamp is the whole basis on which destroy is later willing to act.

Use --idempotency-key whenever a create may be retried. The CLI derives a scoped wire key from the value you provide; the server reserves the sandbox identity before provisioning starts. Reusing the same key with the same name returns the original company, including after an interrupted first attempt. Reusing it with a different name is refused with SANDBOX_IDEMPOTENCY_CONFLICT. Omitting the flag preserves create-always behaviour.

Destroy

dots sandbox destroy <id> --yes --confirm-name "Import Proof"

Removes the sandbox company and every row it holds, permanently, in one cascading delete. The scope is enforced server-side by the delete statement itself: only a caller-owned company carrying the sandbox provenance stamp is removable, so a real tenant's id is refused with a typed SANDBOX_PROVENANCE_REQUIRED error and its rows survive, an unknown or foreign id is a clean SANDBOX_NOT_FOUND, and a credential without workspace.sandboxes.manage is denied before the scope is even consulted.

Where the server runs durable background work, the delete is queued as a job and the command waits for it to finish, bounded by --wait-timeout. The receipt reports what that job did: { destroyed: true } when it deleted the sandbox, or { destroyed: false, alreadyAbsent: true } when a concurrent destroy had already removed it and this one deleted nothing.

Destroy is a destructive verb and carries the full confirmation posture. For execution, --yes is the standard destructive gate and --confirm-name restates the sandbox's workspace name exactly as create returned it. Preview is a separate form: --dry-run needs neither execution flag, resolves the canonical id, slug, name, ownership, and provenance through the server, and sends no DELETE.

Agent Surface

Both verbs ship MCP twins, create_sandbox and destroy_sandbox, registered behind deferred tool discovery in the sandbox family: a host that opts into deferral lists neither up front and activates the pair through discover_tools when a task calls for an isolated tenant. The twins speak the same routes under the same gate. create_sandbox accepts idempotencyKey, and destroy_sandbox accepts dryRun for the same server-backed preview as the CLI. Every other family is listed in CLI Reference.