Cloud environment setup

Create a long-lived cloud environment, pick its VM template and git repos, and bind sessions to it.

An environment is a long-lived Firecracker VM that sessions execute inside. Binding a session to an environment gives the agent VM-backed tools — shell, file read/write, and patch — operating on the repos cloned into that VM.

Reach for an environment when you want a VM that persists across many sessions. For a one-off VM that's provisioned and torn down around a single job, use an on-demand run instead.

Create an environment

Create an environment with a name, a VM template, and the git repos to clone into it. The Console also lets an agent carry a default environment spec (template

repos) that its runs provision automatically — set it under the agent's Environment / VM field.

POST /v1/environments with a name and a config. Only config.type (always cloud in v1) is required within the config.

curl https://agents.clusterbase.dev/v1/environments \
  -H "Authorization: Bearer $CLUSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-dev",
    "config": {
      "type": "cloud",
      "template_id": "development",
      "git_repos": [{ "url": "https://github.com/acme/web", "branch": "main" }]
    }
  }'

Templates

config.template_id selects the VM image: development (the default when omitted), workspace, browser, or desktop. The cloud sandbox reference describes what each one is for, what it has installed, its compute and disk, and its network limits.

Git repos

config.git_repos are cloned into the VM when it's first provisioned. Each repo clones as the VM's owner, so private repos pull with that identity's GitHub credentials. A repo lands at /home/user/<name> unless you set an explicit path. Per-repo clone outcomes surface on a bound session's cloned_repos, including a warning if a particular repo failed to clone.

{ "url": "https://github.com/acme/web", "branch": "main", "path": "web" }

Networking and packages

In v1, config.networking supports only unrestricted — limited is rejected until network filtering ships. config.packages is accepted and stored but not yet installed — only the template's pre-installed tools are available.

Bind a session

Pass environment_id when creating a session. The VM is provisioned on the first binding and reused afterwards. The caller must own the environment — an unknown or non-owned id returns 404.

curl https://agents.clusterbase.dev/v1/sessions \
  -H "Authorization: Bearer $CLUSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agent": "agt_3f9c2a", "environment_id": "env_9a8b7c" }'

Lifecycle

List with GET /v1/environments, fetch one with GET /v1/environments/{id}. Archiving (POST /v1/environments/{id}/archive) or deleting (DELETE /v1/environments/{id}) tears the VM down.

A session created without an explicit environment_id gets its own environment, owned by that session. Deleting the session tears that environment down too — no separate DELETE /v1/environments/{id} call is needed. Passing an existing environment_id to a session instead detaches it from any session that created it, so it survives deletion of either session.