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 Owner-only 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.

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.