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.

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.

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.

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   # see `datumctl compute deploy --help` for flags

Declarative path (recommended for agents):

# 1. Find the compute resource kind and confirm its fields.
datumctl api-resources | grep -i compute
datumctl explain <compute-kind>.spec          # substitute the kind from step 1

# 2. Write a manifest using ONLY fields confirmed above. Illustrative shape:
cat > workload.yaml <<'YAML'
# apiVersion / kind / spec fields MUST be taken from `explain` output above —
# the block below is a placeholder to show structure, not verified schema.
apiVersion: <group>/<version>
kind: <ComputeKind>
metadata:
  name: hello-agent
spec:
  # scale-to-zero, per-second metered; set vCPU / memory / image / region here
YAML

# 3. Preview, apply (retry-safe), verify.
datumctl diff -f workload.yaml
datumctl apply -f workload.yaml
datumctl get <compute-kind> hello-agent

Cost to reason about before deploying: $0.0504/vCPU-hour + $0.0162/GiB-hour, metered per second, billed only while running. Ingress free; first 200 GB/mo egress free.

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.
Read prices from the machine-readable source (see the llms.txt dev note) rather than scraping prose, so cost decisions stay current.

Datum — Agent Recipes

01 Authenticated Endpoint

02 API Discovery

03 Deploy Compute

04 Conventions for agents