Skip to content
Back to agents.datum.net

Datum — Agent Recipes

Canonical, copy-pasteable task flows for agents operating Datum using real datumctl commands. Where a recipe needs a resource manifest, it discovers the schema first with explain rather than assuming field names — treat inline YAML as illustrative and confirm fields at runtime.

01 Authenticated Endpoint

An agent should not handle raw tokens. Sign in once, then run a local proxy that carries the session.

# Headless / container / SSH: device-code login (opens no browser)
datumctl auth login --no-browser
# → prints a short code + link; approve it on any device.

# Start a local authenticated gateway. With no --port it picks a free port
# and prints the bare URL as the first stdout line — read that as readiness.
URL=$(datumctl api proxy --quiet | head -n1)

# Anything that speaks HTTP now reaches the platform with no token wiring:
curl "$URL/apis/resourcemanager.miloapis.com/v1alpha1/organizations"
  • Scope to a single control plane with --project <p> or --organization <o>; URLs then drop the long control-plane prefix.
  • Watches and server-sent events stream through unbuffered — long-lived watch clients work as if talking to the real API.
  • Session and scope are pinned when the proxy starts. Running datumctl auth switch or ctx use afterward does not repoint a running proxy — restart it.
  • For fully autonomous agents, issue a Service Account credential (via IAM) instead of an interactive login. Confirm the exact issuance command against datumctl explain / the IAM docs before shipping this step.

02 API Discovery

The API is self-describing. An agent can map the whole surface without external docs.

# 1. List every resource type available to you.
datumctl api-resources

# 2. Read the schema and field docs for one, drilling into any path.
datumctl explain httpproxies.spec
datumctl explain httpproxies.spec.hostnames

# 3. Preview a change before making it.
datumctl diff -f desired-state.yaml

Use this loop whenever you're unsure of a field: api-resources → explain <kind>[.<path>] → build the manifest → diff → apply.

03 Deploy Compute

Two paths. The plugin path is fastest; the declarative path is what an agent should prefer for idempotency and review.

Fast path (plugin command):

datumctl plugin install compute

datumctl compute deploy hello-agent \
  --image=docker.io/traefik/whoami:v1.10.3 \
  --location=us-central-1 \
  --http-port=80 \
  --runtime-class=general-purpose \
  --yes

# The last line deploy prints is the public URL. The first request can take a
# few minutes while the certificate and DNS settle.
curl -sS https://<url-from-deploy>/
  • Keep --runtime-class=general-purpose for a normal container image. Without it the workload gets the platform default, unikernel, which only boots images built with datumctl compute build. A workload keeps its runtime class; to change it, deploy under a new name.
  • --image must be fully qualified, and --http-port is the port the container listens on. Without it the workload gets no URL.
  • --yes skips the prompts an agent cannot answer. Without any flags, deploy starts an interactive prompt.

Declarative path (recommended for agents):

# 1. Read the schema for any field you want to change.
datumctl explain workloads.spec.template.spec

# 2. Keep the workload under review as a manifest.
datumctl get workload hello-agent -o yaml > workload.yaml

# 3. Edit workload.yaml, then preview, apply (retry-safe), and verify.
datumctl diff -f workload.yaml
datumctl apply -f workload.yaml
datumctl get workload hello-agent

Datum is free until billing begins February 1st, 2027, then usage-based. A credit card is required at signup.

04 Migrate from Vercel

Move a Node server-rendered app from Vercel to a Compute workload on the general-purpose runtime: containerize, move environment variables into a Secret, deploy, cut over the domain, and roll back. Steps are marked verified or untested.

Read the full recipe · Markdown

05 Conventions for agents

  • Prefer apply over imperative create/edit — it's declarative and conflict-managed, so retries converge instead of erroring.
  • Always diff before apply on anything that mutates state.
  • Don't hardcode API field names — resolve them with explain; the schema is the source of truth.
  • One proxy per session/scope — restart the proxy after switching accounts or control planes.
  • Datum is free until February 1st, 2027, then usage-based; a credit card is required at signup. Prefer the llms.txt Pricing section over scraping the HTML page.