Skip to content

api-examples.md

Latest commit

 

History

History
170 lines (136 loc) · 4.04 KB

api-examples.md

File metadata and controls

170 lines (136 loc) · 4.04 KB
Raw

API examples

These examples call Context Service directly. Agent workloads normally use a runtime integration such as Serverless Harness.

export CS_URL=https://example.test/context-service
export CS_TOKEN=replace-with-gateway-token

The gateway authenticates the token and supplies the verified X-Context-Subject identity used by Context Service grants. The curl examples omit that deployment-specific identity injection. See Context access and consumers.

Health

curl --fail --silent --show-error \
  -H "X-SH-Auth: $CS_TOKEN" \
  "$CS_URL/healthz"

Dedicated RWO workspaces

ReadWriteOnce creates one managed PVC per sandbox:

flowchart LR
    CS["Context Service"] --> S1["Sandbox 1"] --> P1["RWO PVC 1"]
    CS --> S2["Sandbox 2"] --> P2["RWO PVC 2"]
    CS --> S3["Sandbox 3"] --> P3["RWO PVC 3"]
Loading 
curl --fail --silent --show-error \
  -H "X-SH-Auth: $CS_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$CS_URL/v1/sandbox-pools" \
  -d '{
    "name": "code-review",
    "replicas": 3,
    "workspace": {
      "size": "5Gi",
      "accessMode": "ReadWriteOnce",
      "storageClass": "ibm-scale-csi"
    }
  }'

Sandbox runtime profile

Administrators define allowed runtime settings as SandboxTemplate resources. Workload callers select one by name without sending arbitrary Pod specifications:

kubectl apply -f deploy/examples/sandbox-profile.yaml
contextctl sb create code-review --sandbox-profile shell --replicas 3

Equivalent API field:

"sandboxProfile": "shell"

The profile controls the image, command, environment, resources, and security settings. Context Service injects the requested workspace at /workspace. Omit the field to use the built-in runtime configured by CS_SANDBOX_IMAGE.

Shared RWX workspace

ReadWriteMany creates one managed PVC mounted by every sandbox:

flowchart LR
    CS["Context Service"] --> S1["Sandbox 1"]
    CS --> S2["Sandbox 2"]
    CS --> S3["Sandbox 3"]
    S1 --> P["Shared RWX PVC"]
    S2 --> P
    S3 --> P
Loading 
curl --fail --silent --show-error \
  -H "X-SH-Auth: $CS_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$CS_URL/v1/sandbox-pools" \
  -d '{
    "name": "shared-review",
    "replicas": 3,
    "workspace": {
      "size": "5Gi",
      "accessMode": "ReadWriteMany",
      "storageClass": "ibm-scale-csi"
    }
  }'
accessMode PVCs created Topology
ReadWriteOnce One per replica Dedicated workspace per sandbox
ReadWriteMany One total Shared workspace across all sandboxes

Existing PVC

An existing claim requires an explicit read policy. Multiple sandboxes require the PVC to support ReadWriteMany.

curl --fail --silent --show-error \
  -H "X-SH-Auth: $CS_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$CS_URL/v1/sandbox-pools" \
  -d '{
    "name": "readers",
    "replicas": 3,
    "workspace": {
      "claimName": "prepared-workspace",
      "readOnly": true
    }
  }'

Set readOnly to false for explicit read-write attachment. Context Service never deletes this caller-owned PVC.

Existing WarmPool

The SandboxWarmPool and SandboxTemplate must already exist. Context Service creates SandboxClaims; compute and storage configuration come from the template.

curl --fail --silent --show-error \
  -H "X-SH-Auth: $CS_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "$CS_URL/v1/sandbox-pools" \
  -d '{
    "name": "fast-review",
    "replicas": 3,
    "warmPoolRef": "research-agents",
    "workspace": {}
  }'

warmPoolRef cannot be combined with workspace settings.

List pools

curl --fail --silent --show-error \
  -H "X-SH-Auth: $CS_TOKEN" \
  "$CS_URL/v1/sandbox-pools"

Read status

curl --fail --silent --show-error \
  -H "X-SH-Auth: $CS_TOKEN" \
  "$CS_URL/v1/sandbox-pools/shared-review"

Release

curl --fail --silent --show-error \
  -H "X-SH-Auth: $CS_TOKEN" \
  -X DELETE "$CS_URL/v1/sandbox-pools/shared-review"