←Back to agents.datum.netDatum — 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
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
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
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
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
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.