Pods

Pods are isolated compute environments where cPod skills and workflows execute. Each pod runs inside its own container with dedicated CPU, memory, and an OCI-compatible image. Pods can be started, stopped, and restarted independently, making them the fundamental unit of compute scheduling in cPod.

Pod Schema

Field	Type	Required	Description
`id`	`string`	auto	UUID
`name`	`string`	yes	Human-readable name (e.g. `"api-server-primary"`)
`status`	`enum`	auto	`pending` \| `provisioning` \| `running` \| `stopping` \| `stopped` \| `failed`
`spec.image`	`string`	yes	OCI image reference (e.g. `"docker.io/acme/api:v3.2.1"`)
`spec.cpu`	`string`	no	CPU request in millicores (e.g. `"1000m"`)
`spec.memory`	`string`	no	Memory request (e.g. `"2Gi"`)
`spec.replicas`	`number`	no	Number of replicas — defaults to `1`
`spec.env`	`object`	no	Environment variables as key/value pairs
`labels`	`object`	no	Arbitrary key/value labels for filtering
`organizationId`	`string`	yes	Organization this pod belongs to
`workspaceId`	`string`	yes	Workspace this pod belongs to
`createdAt`	`string`	auto	ISO 8601 UTC
`updatedAt`	`string`	auto	ISO 8601 UTC

List Pods

import { CpodClient } from '@cpod/sdk'
const sdk = CpodClient.fromEnv()
 
const result = await sdk.pods.list({
  workspaceId: 'c3d4e5f6-...',
  status: 'running',
  limit: 20,
})
 
for (const pod of result.data) {
  console.log(pod.id, pod.name, pod.status, pod.spec.image)
}

from cpod import CpodClient
sdk = CpodClient.from_env()
 
result = await sdk.pods.list(
    workspace_id="c3d4e5f6-...",
    status="running",
    limit=20,
)
 
for pod in result.data:
    print(pod.id, pod.name, pod.status, pod.spec.image)

import "github.com/cpod-ai/cpod-sdk-go/pods"
 
client := cpod.New(os.Getenv("CPOD_API_KEY"))
 
result, err := client.Pods.List(ctx, pods.ListOptions{
    WorkspaceID: "c3d4e5f6-...",
    Status:      "running",
    Limit:       20,
})
for _, pod := range result.Data {
    fmt.Println(pod.ID, pod.Name, pod.Status, pod.Spec.Image)
}

Get Pod Status

const pod = await sdk.pods.get('pod-uuid')
console.log(pod.status) // → "running" | "stopped" | "failed" …

pod = await sdk.pods.get("pod-uuid")
print(pod.status)  # → "running" | "stopped" | "failed" …

pod, err := client.Pods.Get(ctx, "pod-uuid")
fmt.Println(pod.Status)

Create a Pod

Newly created pods start in pending status and transition to provisioning then running automatically once compute is allocated.

const pod = await sdk.pods.create({
  workspaceId: 'c3d4e5f6-...',
  name: 'api-server-primary',
  spec: {
    image: 'docker.io/acme/api:v3.2.1',
    cpu: '1000m',
    memory: '2Gi',
    replicas: 3,
    env: {
      NODE_ENV: 'production',
      LOG_LEVEL: 'info',
    },
  },
  labels: {
    team: 'platform',
    tier: 'api',
  },
})
 
console.log(pod.id, pod.status) // → "pending"

pod = await sdk.pods.create(
    workspace_id="c3d4e5f6-...",
    name="api-server-primary",
    spec={
        "image": "docker.io/acme/api:v3.2.1",
        "cpu": "1000m",
        "memory": "2Gi",
        "replicas": 3,
        "env": {"NODE_ENV": "production", "LOG_LEVEL": "info"},
    },
    labels={"team": "platform", "tier": "api"},
)
 
print(pod.id, pod.status)  # → "pending"

pod, err := client.Pods.Create(ctx, pods.CreateInput{
    WorkspaceID: "c3d4e5f6-...",
    Name:        "api-server-primary",
    Spec: pods.PodSpec{
        Image:    "docker.io/acme/api:v3.2.1",
        CPU:      "1000m",
        Memory:   "2Gi",
        Replicas: 3,
        Env:      map[string]string{"NODE_ENV": "production"},
    },
    Labels: map[string]string{"team": "platform"},
})
 
fmt.Println(pod.ID, pod.Status) // → "pending"

Start and Stop a Pod

// Start a stopped pod
const started = await sdk.pods.start('pod-uuid')
console.log(started.status) // → "provisioning"
 
// Gracefully stop a running pod (resources are retained)
const stopped = await sdk.pods.stop('pod-uuid')
console.log(stopped.status) // → "stopping"

started = await sdk.pods.start("pod-uuid")
print(started.status)  # → "provisioning"
 
stopped = await sdk.pods.stop("pod-uuid")
print(stopped.status)  # → "stopping"

started, err := client.Pods.Start(ctx, "pod-uuid", nil)
fmt.Println(started.Status) // → "provisioning"
 
stopped, err := client.Pods.Stop(ctx, "pod-uuid")
fmt.Println(stopped.Status) // → "stopping"

Delete a Pod

⚠️

A pod must be in stopped or failed status before it can be deleted. Stop the pod first if it is running, then delete it to release compute resources permanently.

// Stop first, then delete
await sdk.pods.stop('pod-uuid')
 
// Poll until stopped (or use events to watch status)
let pod = await sdk.pods.get('pod-uuid')
while (pod.status === 'stopping') {
  await new Promise(r => setTimeout(r, 2000))
  pod = await sdk.pods.get('pod-uuid')
}
 
await sdk.pods.delete('pod-uuid')

import asyncio
 
await sdk.pods.stop("pod-uuid")
 
pod = await sdk.pods.get("pod-uuid")
while pod.status == "stopping":
    await asyncio.sleep(2)
    pod = await sdk.pods.get("pod-uuid")
 
await sdk.pods.delete("pod-uuid")

client.Pods.Stop(ctx, "pod-uuid")
 
for {
    pod, _ := client.Pods.Get(ctx, "pod-uuid")
    if pod.Status != "stopping" { break }
    time.Sleep(2 * time.Second)
}
 
err = client.Pods.Delete(ctx, "pod-uuid")

Credentials Events