Environments

Create a workspace

An Environment owns a persistent writable RootFS and a /workspace directory. Sessions share its files, tools, instructions and configuration. Use one Environment for work that should share state; use forks for independent workspaces.

curl -X POST \
    "https://api.sandpi.ai/v1/environments" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "name": "PR review workspace",
  "labels": {
    "repo": "sandpi",
    "purpose": "review"
  }
}'

{
  "name": "PR review workspace",
  "labels": {
    "repo": "sandpi",
    "purpose": "review"
  }
}

{
  "data": {
    "id": "",
    "name": "",
    "status": "ready",
    "platform": {
      "initialCheckpointStatus": "pending",
      "workspaceRevision": -9007199254740991
    },
    "labels": {},
    "labelsRevision": 0,
    "networkPolicy": {
      "mode": "allow-all",
      "domainExceptions": [
        "example"
      ]
    }
  }
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

An optional public HTTPS Git repository is cloned into /workspace/project before the initial checkpoint. Repository credentials and private hosts are not accepted during initialization. Set networkPolicy at creation to restrict access before initialization. Allow required repository hosts, then manage outbound network access and egress credentials separately.

Wait for initialization

Save the returned Environment ID and poll its state. Wait for both the Environment status and platform.initialCheckpointStatus to be ready before submitting work.

curl \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

{
  "data": {
    "id": "",
    "name": "",
    "status": "ready",
    "platform": {
      "initialCheckpointStatus": "pending",
      "workspaceRevision": -9007199254740991
    },
    "labels": {},
    "labelsRevision": 0,
    "networkPolicy": {
      "mode": "allow-all",
      "domainExceptions": [
        "example"
      ]
    }
  }
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Do not treat an accepted creation response as proof that the repository and checkpoint are ready. If initialization fails, inspect its diagnostic state before creating a replacement.

Pause and resume

After execution and checkpoint work settle, a Platform Sandbox pauses immediately with a memory checkpoint. Queued Runs continue without pausing between them. A Run, rollback or file operation resumes it when needed. Runtime access has a one-minute inactivity fallback; the interactive TUI has its own fifteen-minute idle policy.

If memory restoration definitively fails, Sandpi automatically requests a durable cold restart from committed RootFS files when the stopped source qualifies for recovery. Processes and PTYs restart; retained memory and uncommitted writes can be lost. A queued Run waits for this recovery instead of being rejected solely because cold recovery is pending. An already executing Run is never silently replayed when its original process is lost. Timeouts, capacity waits, and uncertain replies continue reconciling the original memory operation. Recovery still requires quota, writable storage and credential qualification.

Pause preserves workspace files and native Session state. Closing your browser or SSE stream does not stop a Run. The Environment lifecycle lock prevents pause from racing execution or file operations. Failed checkpoints and pauses remain durable for retry.

Configure shared capabilities

Use the console’s Environment Configuration tab or the corresponding APIs for agents.md, Skills, MCP servers, credentials, schedules and webhooks.

Organize with labels

Labels are user-defined key/value pairs for grouping workspaces by repository, stage, purpose or an external task ID. Set them when creating an Environment, then edit them in the console’s Configuration tab or replace the entire map through the API below. Read the Environment first and supply its labels revision; a concurrent edit returns a conflict instead of overwriting another user’s labels. Remove all entries to clear the map.

curl -X PUT \
    "https://api.sandpi.ai/v1/environments/$ENVIRONMENT_ID/labels" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
  "labels": {
    "repo": "sandpi",
    "stage": "dev"
  },
  "labelsRevision": 0
}'

{
  "labels": {
    "repo": "sandpi",
    "stage": "dev"
  },
  "labelsRevision": 0
}

{
  "data": {
    "labels": {},
    "labelsRevision": 0
  }
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

Label edits do not wake a paused Sandbox and can happen during a Run. Labels live outside RootFS checkpoints, so rollback retains their current values. A fork copies its source’s labels once when the child’s metadata is created; subsequent edits are independent. Labels do not grant access or change Project scope.

Remove an Environment

Deletion cleans online workspace content asynchronously and fences new operations. Save the deletion receipt and follow it to completion. Completed forks remain independent. See retention and deletion.

List your Environments

Use the token’s account or Project scope to list workspaces before selecting one.

curl \
    "https://api.sandpi.ai/v1/environments" \
    -H "Authorization: Bearer $SANDPI_API_TOKEN"

{
  "data": [
    {
      "id": "",
      "name": "",
      "status": "ready",
      "platform": {
        "initialCheckpointStatus": "pending",
        "workspaceRevision": -9007199254740991
      },
      "labels": {},
      "labelsRevision": 0,
      "networkPolicy": {
        "mode": "allow-all",
        "domainExceptions": [
          "example"
        ]
      }
    }
  ]
}

{
  "error": {
    "code": "platform_balance_insufficient",
    "message": "Top up Platform credits before submitting a Run.",
    "requestId": "req_example"
  }
}

The list operation supports keyword search over the name, ID and repository URL, provisioning status, and repeated exact-match label conditions. All label conditions must match; values are case-sensitive. Console filters run on the server and stay in the page URL so the filtered view can be bookmarked or shared.

Pagination is optional for existing clients: pass a page size to receive bounded pages, then reuse the returned cursor with the same search/filter conditions. Omitting a page size preserves the complete-list behavior.