Provisioning lifecycle

Creating a SEAOTTER agent is asynchronous and does not require SSH. POST /api/v1/agents returns in about a second with status=provisioning. Typical wall time until the Hermes dashboard is reachable is a few minutes (usually under five). Poll stages until wizard_reachable is ok and status is running. POST /api/v1/agents inserts a row, seeds URLs, enqueues work, then the worker walks a strict, ordered set of readiness gates stored on the agent:

config.provisioning_stages

Poll GET /api/v1/agents/{id} until stages complete and status is running (or error).

Stage order

Stage	Meaning
`namespace_created`	Per-agent Kubernetes namespace exists
`helm_installed`	Hermes chart applied
`pod_ready`	Deployment replicas ready and pod Ready (API + dashboard)
`sandbox_verified`	gVisor runtime confirmed when `config.sandbox=gvisor`; skipped when sandboxing is off
`dns_resolvable`	Public hostname has an A record
`tls_valid`	Shared wildcard TLS acknowledged (often completes quickly / may be `skipped` as a per-tenant wait)
`wizard_reachable`	HTTPS reachability hard gate on the dashboard host

Stages are not parallel. Later stages stay pending until earlier ones succeed.

Status values

Each stage object looks like:

{
  "status": "waiting",
  "ms": 12000,
  "detail": "waiting for Ready",
  "host": "my-hermes-abcd1234.agents.seaotter.dev"
}

Status	Meaning
`pending`	Not started yet
`waiting`	In progress / retrying (transient)
`ok`	Gate passed
`error`	Gate failed after retries; agent may move to `status=error`
`skipped`	Not applicable for this agent (e.g. sandbox disabled, TLS ack path)

Treat coral/error as terminal for that attempt. Amber/waiting is normal during Autopilot pull, DNS, and HTTP backoff.

Worked polling example

export SEAOTTER_API='https://api.seaotter.dev'
export SEAOTTER_API_KEY='so_…'
AGENT_ID='…'

poll() {
  curl -sS "$SEAOTTER_API/api/v1/agents/$AGENT_ID" \
    -H "Authorization: Bearer $SEAOTTER_API_KEY"
}

# Create
AGENT_ID=$(curl -sS -X POST "$SEAOTTER_API/api/v1/agents" \
  -H "Authorization: Bearer $SEAOTTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"lifecycle-demo"}' | jq -r .id)

# Poll until wizard_reachable is ok or agent errors
for i in $(seq 1 80); do
  body=$(poll)
  status=$(echo "$body" | jq -r .status)
  wizard=$(echo "$body" | jq -r '.config.provisioning_stages.wizard_reachable.status // "pending"')
  echo "[$i] agent=$status wizard=$wizard"
  echo "$body" | jq -c '.config.provisioning_stages'
  if [ "$wizard" = "ok" ] || [ "$status" = "error" ]; then
    break
  fi
  sleep 3
done

Typical wall time is a few minutes (image pull + PVC + DNS + HTTP gate). The product UI shows a similar poll cadence (~2.5s).

Retries and reprovision

Hard failures during provision may return 503 from the worker so Cloud Tasks retries with backoff.
After a sticky error, owners can call POST /api/v1/agents/{id}/reprovision to re-enqueue.
Restore flows add restore_* keys alongside the create stages; hostname stays the same.

After success

When status is running:

Open dashboard_url (basic auth — reveal password with POST …/credentials/reveal)
Call the tenant Hermes API at api_url with the tenant API key (not your so_ control-plane key)

Pause, restart, restore, and reprovision are API/dashboard operations — not SSH into the node.

How long does provision take?

Typical wall time is a few minutes (image pull + PVC + DNS + HTTP gate). The product UI polls about every 2.5 seconds. Treat waiting as in progress; error is terminal for that attempt until you reprovision.

Do I need SSH?

No. Lifecycle (start, stop, restart, restore, secrets, credentials, logs) is on the control plane. See What is SEAOTTER?.

Get started

Connect from chat

Concepts

Provisioning lifecycle

Stage order

Status values

Worked polling example

Retries and reprovision

After success

​Stage order

​Status values

​Worked polling example

​Retries and reprovision

​After success

Stage order

Status values

Worked polling example

Retries and reprovision

After success