# Sandbox plugin reference Install, options, account fields, limits, environment variables, and tools of @gitterm/opencode-sandbox. This is the reference for `@gitterm/opencode-sandbox`, the OpenCode plugin that gives your local agent remote sandboxes: every option, account field, limit, environment variable, and tool. Use it to look up a field. For step-by-step setup, see [Sandbox setup](https://gitterm.dev/docs/sandboxes/setup.md). Formerly part of `@gitterm/opencode-plugin`. The `/cloud` command is now a separate plugin; see [Cloud plugin reference](https://gitterm.dev/docs/reference/cloud-plugin.md). ## Install ```sh opencode plugin add @gitterm/opencode-sandbox ``` This installs the plugin and adds it to your global OpenCode config. You can instead list it under `plugins` in a project's `opencode.json`, or in `~/.config/opencode/opencode.json` for all projects. The tools need an account, so replace the plugin's string entry with an object that has `options`. Keep your other settings and plugin entries. ```jsonc { "$schema": "https://opencode.ai/config.json", "plugins": [ { "package": "@gitterm/opencode-sandbox", "options": { "provider": "e2b", "apiKey": "{env:E2B_API_KEY}" }, }, ], } ``` Restart OpenCode after changing the options. When you load the plugin from a local path, point `package` at the package directory, not a file. ## Sign in Managed accounts need a Gitterm login. Direct accounts do not. ```sh npm install -g @gitterm/cli gitterm login ``` The plugin uses the CLI's saved login. For a self-hosted deployment, run `gitterm login --server `, where `` is your Gitterm API URL. You can instead set `GITTERM_API_TOKEN` (and `GITTERM_SERVER_URL`) before starting OpenCode. ## Options These go directly in the plugin's `options`, next to one account's [fields](#account-fields). For several accounts, put them under `accounts` instead. Without options, the tools report that sandboxes are not configured. | Option | Type | Required | Default | What it does | | ---------------- | -------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account` | string | No | None | With `accounts`: name of the account the tools use. | | `accounts` | object | No | None | Map of account name to [account fields](#account-fields), for several accounts. A single account inline is named after its `provider`, or `gitterm` without one. | | `limits` | object | No | See [limits](#limits) | Caps on what the agent can start. | | `exclude` | string[] | No | None | Extra glob patterns `sandbox_sync` never uploads. Secret-like files are always left out. | | `publicPreviews` | boolean | No | `false` | Creates every sandbox with public previews, without asking. Setting it is your approval. Whether a preview can be public depends on the provider and the kind of account; see [Previews by provider](https://gitterm.dev/docs/sandboxes/jobs-and-previews.md#previews-by-provider). | | `snapshots` | boolean | No | `false` | Lets the agent save a set-up sandbox as a snapshot, so the project's next sandboxes start from it. See [Setup snapshots](https://gitterm.dev/docs/sandboxes/setup.md#setup-snapshots). | Account names use letters, digits, `_`, `.`, and `-`, start with a letter or digit, and are at most 63 characters. ### Account fields | Field | Applies to | Required | Default | What it does | | ---------------------------- | -------------------------- | ------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `apiKey` | Direct | Yes | None | Provider key, as `"{env:VAR}"` or `"{file:path}"`. Having it makes the account direct; without it the account is managed. See [Concepts](https://gitterm.dev/docs/concepts.md#managed-and-direct-accounts). | | `provider` | Direct | Yes | None | `e2b`, `daytona`, `vercel`, `boat`, `exedev`, or `railway`. | | `provider` | Managed | No | The server's default | One the deployment offers, for example `e2b` or (managed only) `aws`. Gitterm's own sandboxes on gitterm.dev. | | `size` | Managed | No | Your plan's default | Machine size: `small` or `medium` on gitterm.dev, or one of a self-hosted deployment's machine profiles. | | `allowUnboundedLifetime` | Direct `exedev`, `railway` | Yes (`true`) | `false` | Accepts that a crashed sandbox runs until you destroy it. | | `template` | Direct `e2b` | No | `base` | E2B template. | | `target` | Direct `daytona` | No | Daytona's default | Region: `us` or `eu`. | | `snapshot` | Direct `daytona` | No | None | Daytona snapshot to use instead of the default image. | | `teamId`, `projectId` | Direct `vercel` | Yes | None | Vercel team and project. | | `runtime` | Direct `vercel` | No | `node24` | `node24`, `node22`, or `python3.13`. | | `size` | Direct `boat` | No | Boat's default | `small`, `default`, or `large`. | | `image` | Direct `exedev` | No | `node:22-bookworm` | Container image. | | `projectId`, `environmentId` | Direct `railway` | Yes | None | Railway project and environment. | | `image` | Direct `railway` | No | `node:22-bookworm-slim` | Container image. Gitterm's command server runs in it. | | `apiUrl` | Direct `railway` | No | Railway's API | Railway API URL. Default: `backboard.railway.app/graphql/v2`. | | `serverUrl` | Managed | No | CLI login | Gitterm API URL, for self-hosted deployments. | | `token` | Managed | No | CLI login | Gitterm API token. Prefer `gitterm login` or `GITTERM_API_TOKEN`. | For what each provider does with a sandbox, see [Providers](https://gitterm.dev/docs/sandboxes/providers.md). ### Limits Set these under `limits`. Any field you leave out uses its default. | Limit | Default | What it does | | ------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `maxSandboxes` | `2` | Live sandboxes per account. `sandbox_create` fails at the limit. | | `maxLifetimeMinutes` | `60` | Longest lifetime `sandbox_create` accepts. | | `defaultLifetimeMinutes` | `30` | Lifetime when the agent does not set one. | | `maxJobMinutes` | `30` | Longest job timeout. Jobs default to 10 minutes or this, whichever is less. Preview servers run until the sandbox's lifetime ends, or this long where the sandbox has none. | Providers also cap the lifetime: 24 hours, or 5 hours on Vercel. ## Environment variables | Variable | What it does | | -------------------- | ------------------------------------------------------------------- | | `GITTERM_API_TOKEN` | Gitterm API token for managed accounts. Overrides the saved login. | | `GITTERM_SERVER_URL` | Gitterm API URL for managed accounts. Overrides the saved login. | | `XDG_STATE_HOME` | Base directory for local sandbox records. Default `~/.local/state`. | | `XDG_CACHE_HOME` | Base directory for downloaded artifacts. Default `~/.cache`. | Set variables before OpenCode starts. This includes variables you reference with `{env:VAR}` and variables you pass to jobs with `secretEnv`. ## Tools The plugin adds nine tools, and a tenth when `snapshots` is on. You ask in plain words and the agent picks them; their arguments are in [Tools](https://gitterm.dev/docs/sandboxes/tools.md). | Tool | What it does | | ------------------ | ----------------------------------------------------------------- | | `sandbox_create` | Creates a sandbox | | `sandbox_list` | Shows the selected account, who is charged, limits, and sandboxes | | `sandbox_sync` | Uploads the checkout | | `sandbox_exec` | Runs a command as a job | | `sandbox_job` | Reads a job's status and output, or cancels it | | `sandbox_preview` | Exposes a port, optionally starting a server first | | `sandbox_artifact` | Downloads a file a job produced | | `sandbox_apply` | Copies a downloaded file into the checkout | | `sandbox_destroy` | Deletes a sandbox | | `sandbox_snapshot` | Saves or deletes the project's setup snapshot (with `snapshots`) | Which tools ask for approval, and how to pre-approve them: [Approvals](https://gitterm.dev/docs/sandboxes/setup.md#approvals). ## Sidebar OpenCode's right sidebar has a **Sandboxes** list with this checkout's live sandboxes, newest first. Each line shows the sandbox name and a dot for its state (green running, yellow pending or paused, red deleting), then any running jobs, preview ports, and its purpose or provider. The list refreshes every few seconds from the local sandbox records. It never calls the provider, and it is hidden when the checkout has no sandboxes. ## Related - [Sandbox setup](https://gitterm.dev/docs/sandboxes/setup.md) - [Tools](https://gitterm.dev/docs/sandboxes/tools.md) - [Jobs and previews](https://gitterm.dev/docs/sandboxes/jobs-and-previews.md) - [CLI reference](https://gitterm.dev/docs/reference/cli.md#sandboxes)