Xeonr Developer Docs
API SpecificationSandboxes

Suspend Sandbox

POST
/containers.api.v1.SandboxService/SuspendSandbox

Suspends a sandbox: records a SUSPENDED marker in the run log, deletes the pod gracefully (30s grace when a writable workspace needs flushing, 10s otherwise), marks the record SUSPENDED, revokes the agent key and marks console sessions lost. Workspaces and the egress binding are kept for resume.

Access: namespace OPERATOR or above (write)

Authorization

BearerAuth
AuthorizationBearer <token>

A namespace-scoped API key (cpk_…) for machines, or a Xeonr Auth OIDC token for humans. The key's namespace and role are pinned server-side.

In: header

Header Parameters

Connect-Protocol-Version?number

Define the version of the Connect protocol

Connect-Timeout-Ms?number

Define the timeout, in ms

Request Body

application/json

sandboxId?string
Length1 <= length <= 64
[key: string]?never

Response Body

application/json

application/json

curl -X POST "https://containers.xeonr.io/containers.api.v1.SandboxService/SuspendSandbox" \  -H "Connect-Protocol-Version: 1" \  -H "Connect-Timeout-Ms: 1000" \  -H "Content-Type: application/json" \  -d '{}'
{
  "sandbox": {
    "sandboxId": "string",
    "namespace": "string",
    "environmentId": "string",
    "workspaceId": "string",
    "state": "SANDBOX_STATE_UNSPECIFIED",
    "ports": [
      {
        "port": 0,
        "url": "string",
        "accessToken": "string",
        "auth": "AUTH_UNSPECIFIED"
      }
    ],
    "createdAtUnix": "string",
    "resources": {
      "cpuMillis": 0,
      "memoryMb": 0,
      "ephemeralMb": 0,
      "pids": 0
    },
    "idleSuspendSec": 0,
    "maxLifetimeSec": 0,
    "workspaceCache": {
      "policy": "POLICY_UNSPECIFIED",
      "writebackSec": 0
    },
    "egressGrant": {
      "mode": "MODE_UNSPECIFIED",
      "expiresAtUnix": "string",
      "reason": "string",
      "policy": {
        "mode": "MODE_UNSPECIFIED",
        "allow": [
          {
            "hostPattern": "string",
            "ports": [
              0
            ],
            "mode": "RULE_MODE_UNSPECIFIED",
            "pathPrefixes": [
              "string"
            ],
            "methods": [
              "string"
            ],
            "maxResponseBytes": "string",
            "allowPlainHttp": true
          }
        ],
        "presets": [
          "string"
        ],
        "allowPlainHttp": true
      },
      "id": "string"
    },
    "runtimeEgress": {
      "mode": "MODE_UNSPECIFIED",
      "allow": [
        {
          "hostPattern": "string",
          "ports": [
            0
          ],
          "mode": "RULE_MODE_UNSPECIFIED",
          "pathPrefixes": [
            "string"
          ],
          "methods": [
            "string"
          ],
          "maxResponseBytes": "string",
          "allowPlainHttp": true
        }
      ],
      "presets": [
        "string"
      ],
      "allowPlainHttp": true
    },
    "label": "string",
    "egressGrants": [
      {
        "mode": "MODE_UNSPECIFIED",
        "expiresAtUnix": "string",
        "reason": "string",
        "policy": {
          "mode": "MODE_UNSPECIFIED",
          "allow": [
            {
              "hostPattern": "string",
              "ports": [
                0
              ],
              "mode": "RULE_MODE_UNSPECIFIED",
              "pathPrefixes": [
                "string"
              ],
              "methods": [
                "string"
              ],
              "maxResponseBytes": "string",
              "allowPlainHttp": true
            }
          ],
          "presets": [
            "string"
          ],
          "allowPlainHttp": true
        },
        "id": "string"
      }
    ],
    "env": {
      "property1": "string",
      "property2": "string"
    },
    "workspaces": [
      {
        "snapshotId": "string",
        "mountPath": "string",
        "readOnly": true,
        "workspaceId": "string",
        "ephemeral": true,
        "ephemeralFromSnapshotId": "string",
        "volume": {
          "sizeMb": "string",
          "seedSnapshotId": "string",
          "cacheKey": "string"
        }
      }
    ],
    "workingDir": "string",
    "argv": [
      "string"
    ],
    "restart": "SANDBOX_RESTART_UNSPECIFIED",
    "onExit": "SANDBOX_ON_EXIT_UNSPECIFIED",
    "runState": "RUN_STATE_UNSPECIFIED",
    "run": 0,
    "lastExitCode": 0
  }
}
{
  "code": "not_found",
  "message": "string",
  "details": [
    {
      "type": "string",
      "value": "string",
      "debug": {}
    }
  ]
}

Revoke Egress POST

Removes exactly one grant by id, leaving the base policy and other grants intact; takes effect on the proxy via the live feed. grant_id is required (InvalidArgument); an unknown grant is NotFound. **Access:** namespace OPERATOR or above (write)

Sync Sandbox Workspace POST

Forces the sandbox's agent to flush local changes back to the workspace store now rather than on the periodic sync, and reports files/bytes flushed plus conflict paths accumulated since the last call. Empty workspace_id flushes every read-write mount. FailedPrecondition when the sandbox has no writable workspace or is not RUNNING. **Access:** namespace OPERATOR or above (write)