gitterm
Get started

Concepts

Short definitions of sandboxes, cloud workspaces, /cloud handoff, account modes, providers, and cleanup.

View as markdown

This page defines the terms the rest of the docs use. Read it once before setting things up, or come back when a word is unclear.

Sandbox, cloud workspace, and /cloud

SandboxCloud workspace/cloud handoff
Where the agent runsOn your machineIn the cloudIn the cloud, after the move
What runs remotelyOnly the commands your agent sendsOpenCode or T3 Code, with your repositoryOpenCode, with your conversation and checkout
Model credentials remotelyNoneYours, configured in GittermYours, configured in Gitterm
How you start itsandbox_* tools from @gitterm/opencode-sandboxThe dashboard or the SDK/cloud from @gitterm/opencode-cloud
  • Sandbox. A plain remote machine your local agent uses for builds, tests, and preview servers. It runs no coding agent. See Sandboxes overview.
  • Cloud workspace. A remote machine that runs the agent itself: OpenCode, or T3 Code (which drives Codex and Claude Code). You open it in the browser or connect a local client. See Cloud workspaces.
  • /cloud handoff. Moves one OpenCode session into a cloud workspace, and /cloud-return brings it back with the cloud's commits, changes and conversation. Nothing syncs in between: later local edits do not go up, and cloud changes come back only when you return the session, which replaces the local state rather than merging. T3 Code sessions do not move; start a new cloud agent instead. See Move a session and Bring a session back.

Managed and direct accounts

A sandbox account says whose provider account runs the sandbox and who pays. An account with an apiKey is direct; one without is managed. You can configure several accounts and pick one by name.

AccountSet up withWho holds the provider accountWho paysNeeds a Gitterm account
Directprovider and apiKeyYou (bring your own key)Your provider accountNo
ManagedNo apiKey; optionally size, serverUrl, providerThe Gitterm deploymentYour Gitterm planYes

Every sandbox belongs to the account that created it. Gitterm never falls back to another account: using a sandbox from another account, or a missing or rejected key, is an error. See Setup.

Cloud workspaces always run through a Gitterm account.

Providers

A provider is the company whose machines run the sandbox or workspace. Sandboxes support E2B, Daytona, Vercel, Boat, exe.dev, and Railway with either kind of account, and AWS with managed accounts only. Cloudflare sandboxes are planned. See Providers.

Sandbox terms

  • Lifetime. How long a sandbox may exist, set when it is created (30 minutes by default).
  • Sync. Uploading your current working tree to ~/project in the sandbox. Each sync is recorded as a snapshot: a list of file paths and hashes.
  • Job. One command running in the sandbox. Jobs keep running if OpenCode restarts. See Jobs and previews.
  • Preview. A URL for a port in the sandbox, such as a dev server. Private by default; whether it can be public depends on the provider and the kind of account. See Previews.
  • Artifact. A file a job produced, downloaded to your machine and then applied to your checkout. See Artifacts.

What stays local

With sandboxes, these never leave your machine: the conversation, Git history, your model credentials, and files that look like secrets (such as .env files and private keys). See Security.

With /cloud, the selected conversation and Git history do move, by design. Your local files and sessions stay unchanged until you run /cloud-return.

Lifetimes and cleanup

  • Sandboxes end at their lifetime: Gitterm terminates managed ones, and the provider ends direct ones where it can. exe.dev and Railway never do, so destroy those yourself. See Cleanup.
  • Cloud workspaces run until you pause or terminate them, or until an idle timeout stops them. See Lifecycle.