Cloud workspaces

A cloud workspace is a remote machine that runs a coding agent on one of your repositories. Read this page before you create your first workspace, or when you need to pick a provider.

The agent itself runs in the workspace: OpenCode, or T3 Code (which drives Codex and Claude Code). That is the difference from a sandbox, where the agent stays on your machine and only commands run remotely.

What a workspace has#

• A checkout of your repository, on the branch you pick.
• One agent, started with your model credentials. See Agents.
• A URL to open in a browser or connect a local client to. See Connect to a workspace.
• Optional connections: GitHub, Google Cloud, MCP servers. See Connections.
• Preview URLs for any port. See Previews.
• A lifecycle: it runs, pauses when idle, resumes, and is terminated. See Lifecycle.

Ways to create one#

The gitterm CLI lists, pauses, restarts and terminates workspaces. It does not create them.

Create a workspace from the dashboard#

Before you start:

• Add a model key or subscription under Models. See Agents.
• For a private repository, connect GitHub under Integrations. See Connections.

Steps:

1. Open Workspaces and click New workspace.
2. Enter the repository. Optionally set a Branch; leave it empty to use the repository default.
3. Pick an Agent and a Cloud provider. Where the provider offers them, pick a Region and a Machine size.
4. Under GitHub repository access, pick a connection. None (public repos only) works for public repositories only.
5. Optional: open Add integrations to attach a Google Cloud identity or MCP servers and Executor.
6. Optional: turn on Keep running when idle. See Lifecycle.
7. Click Create workspace.

You should see the new workspace as a row under Workspaces. Once it is running, the row shows a button to connect, and clicking the row shows the rest. See Connect to a workspace.

Create a workspace from the SDK#

import { createGittermClient } from "@gitterm/sdk";

const client = createGittermClient({ token: process.env.GITTERM_API_TOKEN });

const { workspace, runtime } = await client.workspaces.create({
  repo: "https://github.com/acme/product",
  branch: "main",
  agent: "opencode",
  provider: { type: "e2b" },
  connections: ["github"],
});

console.log(workspace.status, runtime.url);

Only repo is required. Without agent, the server uses opencode. Without provider, it uses your default provider and that provider's default machine size. For every option, see the SDK reference.

Providers#

The deployment's admin enables providers, and you can pick only from those. Set your default under Compute in the dashboard.

• Sandbox providers return a running workspace right away. Railway reports pending until its deployment succeeds, usually within a minute.
• Whether files survive a pause depends on the provider. See Lifecycle.
• The admin sets the machine sizes. client.catalog.workspaceOptions() lists the sizes you may use, with vcpus and memoryGb.
• On managed Gitterm, your plan limits which providers and sizes you can use. See Plans and billing.

Related#

• Agents
• Connect to a workspace
• Lifecycle
• Plans and billing