Agents

anycloud's CLI is designed so AI coding agents can drive deployments end-to-end — submit, monitor, terminate, attribute cost.

Recipe: let an agent drive deployments

End to end, giving Claude Code / Codex / Cursor / Aider the ability to submit and monitor jobs with per-session spend caps:

1. Install and connect a cloud account (once):

   curl -fsSL https://get.anycloud.sh | sh
   anycloud login
   anycloud api start
   anycloud credentials new my-aws --provider aws \
     --access-key-id AKIA... --secret-access-key ...
   # other clouds: --provider azure | gcp | lambda

   The agent uses the same credentials and CLI you do — no separate config. See Getting Started for the full setup.

2. Cap per-session spend so a runaway loop can't drain your account:

   anycloud throttle set 20 --agent-session           # max $20/hr per session
   anycloud budget set 200 --per day --agent-session   # max $200/day per session

   Caps gate dispatch and never kill running jobs. See Spend Controls.

3. Let the agent submit. Ask it to use the anycloud CLI directly — anycloud auto-detects the agent and stamps each deployment with the session id. A useful prompt prefix:

   Use anycloud submit to run jobs. Pass --gpu-type or --vm-type; don't pick a --region yourself — leave region selection to anycloud unless the user gives an explicit quota/debug constraint. Use anycloud list --json, anycloud status <id> --json, and anycloud cost <id> --json for structured output. If a submit is queued, read the blocked-by reason with anycloud status <id>. Run anycloud docs for the topic index and anycloud docs --all for the full corpus.

4. Monitor from your own shell:

   anycloud list --agent claude          # everything this agent submitted
   anycloud list --session <id> --json   # one session, structured
   anycloud cost --json                  # aggregate spend

5. Clean up when done:

   anycloud list --only-ids --agent claude --status running | xargs anycloud terminate
   anycloud throttle unset --agent-session
   anycloud budget unset --per day --agent-session

The rest of this page explains each piece — tagging, machine-readable output, spend caps, and the read-only DB query.

Session tagging

Every anycloud submit (CLI or Python SDK) is stamped with the session of the agent that invoked it. Tagged deployments show up in anycloud list and anycloud status with the agent name and session id, and anycloud list can be filtered by either.

Auto-detected agents:

Agent	Marker env	Native session id env
Claude Code	CLAUDECODE	CLAUDE_CODE_SESSION_ID
Codex	CODEX_BIN_PATH	— (uses <agent>-<ppid>)
Cursor	CURSOR_TRACE_ID	CURSOR_TRACE_ID
Aider	AIDER_MODEL	— (uses <agent>-<ppid>)

Detection is TTY-guarded: when the CLI is running in an interactive shell (you typed the command), auto-tagging is suppressed — even if the shell was opened from inside an agent.

For Claude Code sessions, anycloud list (and the per-session rows in anycloud spend, throttle, and budget) shows the session's own title — the human-readable name Claude gives the conversation — instead of the raw id, so deployments are easy to recognize at a glance. Other agents keep showing the agent name and a short session id. Filtering with --session / --agent always matches the underlying id, not the title.

Filter deployments by agent or session:

anycloud list --agent claude              # all deployments from Claude Code
anycloud list --session abc-123-def        # exact session match
anycloud list --agent claude --status failed --json

Session scoping

When an agent runs anycloud list or anycloud cost non-interactively, the output is scoped to that agent's own session — so parallel agents don't see each other's deployments. To look at another session, pass --session <id> or --agent <name> explicitly:

anycloud list                  # agent: only its own session; human shell: everything
anycloud list --agent codex    # explicitly target another agent's deployments

Interactive (TTY) runs are never scoped — when you type the command yourself you see all sessions. Scoping is cooperative, not an access boundary: it sets the default filter, and the server still returns any session a caller explicitly names.

Machine-readable output

Every command that prints a table also accepts --json for compact, parseable output:

anycloud list --json                      # one-line JSON array
anycloud status <id> --json
anycloud cost --json                      # aggregate report
anycloud cost <id> --json                 # per-deployment fields
anycloud regions aws --vm-type p4d.24xlarge --json

anycloud list also supports two output modes optimized for piping:

anycloud list --csv                       # header + one row per deployment
anycloud list --only-ids --status running # one ID per line; pairs with xargs

Combine with filters for batch operations:

anycloud list --only-ids --status Failed | xargs anycloud terminate

Self-documenting CLI

anycloud --help lists every command; for full product context an agent can fetch the docs directly:

anycloud docs              # short index — titles + descriptions
anycloud docs --all        # full markdown corpus (every concept, guide, reference)
anycloud docs --url        # print the URL only — for piping or caching

anycloud docs is a thin wrapper over https://anycloud.sh/llms.txt and https://anycloud.sh/llms-full.txt, so an agent without the CLI installed can curl the same URLs.

Per-session spend controls

Cap an agent's burn rate or daily spend so a runaway loop can't drain your account. The --agent-session flag on throttle and budget applies the cap per session — each agent run is capped independently, so one agent hitting its cap doesn't block other work.

anycloud throttle set 20 --agent-session  # each session: $20/hr
anycloud budget set 100 --per day --agent-session

Account-wide caps (the default, no --agent-session) coexist with per-session caps. Both are checked before dispatch; whichever is tighter wins. See Spend Controls for the full surface.

Read-only DB query

anycloud db query runs a SELECT, WITH, EXPLAIN, or PRAGMA against the local API database. Writes are refused. Useful when an agent (or you) needs to answer a question the CLI doesn't have a flag for.

anycloud db query "SELECT id, state, agent, session FROM deployments WHERE state='failed' ORDER BY started_at DESC LIMIT 20" --json

anycloud db query "SELECT d.session, SUM(COALESCE(v.cost, 0)) AS spent FROM deployments d JOIN vms v ON v.deployment_id = d.id WHERE d.agent='claude' GROUP BY d.session ORDER BY spent DESC" --json

Discover tables and columns with anycloud db schema:

anycloud db schema                        # all tables
anycloud db schema deployments            # columns, FKs, indexes for one table
anycloud db schema --json                 # parseable