Cloud environment setup

An environment is a saved configuration for an agent VM. It selects the image, additional packages, and setup scripts. Starting a normal session creates an isolated workspace from that configuration; repositories and a Storage folder are chosen per session, not saved on the environment. The saved environment is the reusable definition; it does not own one VM forever.

Portal managed agents always use a VM. A normal session gets an isolated workspace, whether it starts from the default VM template or a saved environment. Deployments additionally choose whether to reuse one deployment workspace or create a fresh VM for each run.

Create an environment

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"
    }
  }'

Templates

config.template_id selects the VM image: development (the default when omitted and shown as Agent), 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.

Packages and scripts

config.packages accepts apt, pip, npm, cargo, gem, and go arrays. config.build_script runs after package installation; its filesystem changes are saved in a separate custom template. The standard image is unchanged.

After saving a customized environment, call POST /v1/environments/{id}/build. Use GET /v1/environments/{id}/build for status and bounded logs. Wait for ready before starting a session; binding a customized environment that was never built returns 409. Portal submits the build automatically. Each environment pins the exact immutable build used for launch.

config.setup_script runs in each newly provisioned VM after repository checkout, before the agent starts. config.setup_directory optionally selects the working directory; it must be /workspace or an absolute path beneath it, requires setup_script, and defaults to /workspace. Environments saved with a directory outside /workspace fail at startup with 400 until it is updated. Reusing or resuming a VM does not repeat startup. Both scripts are limited to 16 KiB; startup has a ten-minute limit. A failed startup prevents agent execution and tears down the attempted VM.

Keep credentials in connections rather than embedding them in image build scripts. Networking currently supports only unrestricted; limited is rejected.

Bind a session

Pass environment_id when creating a session. The session workspace is provisioned from the saved environment when it is first bound. The caller must own the environment — an unknown or non-owned id returns 404. Select repositories and a Storage folder for that workspace in resources:

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",
    "resources": {
      "git_repos": [{ "url": "https://github.com/acme/web", "branch": "main", "path": "web" }]
    }
  }'

Each repo clones as the workspace's owner, so private repos pull with that identity's GitHub credentials. A repo lands at /workspace/<name> unless you set an explicit path, which must resolve beneath /workspace and outside the reserved library-files, scratch, inputs and uploads directories (else 400). A repo named like a reserved directory, or sharing its name with another repo in the list, lands at /workspace/<owner>-<name> instead. Per-repo clone outcomes surface on the session's cloned_repos, including a warning if a particular repo failed to clone. resources.folder_id mounts a Storage folder at /workspace/library-files; set it there or as the session's top-level folder_id, never both.

Lifecycle

List with GET /v1/environments, fetch one with GET /v1/environments/{id}. Archiving (POST /v1/environments/{id}/archive) stops new workspaces from being created from the definition; existing workspaces are preserved. Deleting (DELETE /v1/environments/{id}) archives the environment first and returns 409 while any workspace still references it.

A session created without an explicit environment_id gets its own workspace, owned by that session. Deleting the session tears that workspace down too — no separate DELETE /v1/environments/{id} call is needed. Passing an existing environment_id creates a session workspace from that definition; the definition survives when the session is deleted.

Build artifacts are kept while any workspace still pins them. Deleting an unused customized environment also archives its Infra template and requests cancellation of active builds; Infra retires unused artifacts. If cleanup fails, the archived environment retains its references for retry.