Xeonr Developer Docs
API SpecificationSandboxes

Get Sandbox

POST
/containers.api.v1.SandboxService/GetSandbox

Returns one sandbox. Egress fields are filled from the live egress binding, so they show what the proxy enforces now (expired grants are omitted). NotFound for an unknown id.

Access: namespace VIEWER or above (read)

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/GetSandbox" \  -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": {}
    }
  ]
}

Expose Sandbox Port POST

Publishes a sandbox port on an isolated preview URL and records it on the sandbox; idempotent per port. port must be 1-65535, and 53, 80 and 443 are refused because the egress capture owns them (InvalidArgument). Only AUTH_SIGNED_URL returns an access token (embedded in the URL); FORWARD_AUTH and PUBLIC are resolved at access time. Unimplemented when no preview domain is configured. **Access:** namespace OPERATOR or above (write)

Grant Egress POST

Adds one additive, independently revocable egress grant on top of the sandbox's base policy; the egress in force is the base unioned with every active grant. Takes effect on the proxy through the live policy feed without a restart. ttl_sec 0 means no expiry; otherwise at most 86400. The reason is recorded in the audit log. Rejects a missing policy (InvalidArgument) and a sandbox created without egress configured (FailedPrecondition); Unimplemented when egress signing is not configured. Returns the new grant id. **Access:** namespace OPERATOR or above (write)