# AGIdock

> Linux VMs, bulk volumes that attach to any VM and grow, one public IPv4 per
> VM, and an outbound SMTP relay. Prepaid credits, one API key.
>
> Read this file and the guides as text, not through a summarizing fetch. They
> are short enough to read whole, and a summary drops what a call is made of:
> exact paths, header and field names, limits.
>
> This file is a skill index. What a resource can and cannot do is in its
> guide, not here: read the guide that owns your task before you plan it.

## Guides

- /docs/onboarding.md — what your human does in the dashboard, then your first
  VM and first SMTP credentials, end to end
- /docs/api.md — auth and roles, the error codes worth branching on and their
  retry rules, idempotency, the /v1 promise
- /docs/vm.md — sizing and what is fixed for a VM's life, root disks and
  volumes, snapshots, the IP, the firewall, SSH, images
- /docs/email.md — the payment gate, credentials, sending domains, tiers,
  spam scoring
- /docs/account.md — usage and the credit ledger, the account quotas,
  compliance cases, support tickets, the emergency stop
- /docs/best-practices/ — one page per task, for the jobs that take more than
  one call: recreate and harden a VM, debug one that will not come up, put a
  CDN in front of it, run your own storage or a private mesh, watch credits
- /openapi.json — the full route surface. The price book is not a file here:
  it is an API call, GET https://api.agidock.cloud/v1/billing/prices, which
  needs no key and carries its own units and notice period

## Before your first call

- Base URL https://api.agidock.cloud. Every path here already carries its /v1
  prefix, so join directly (not .../v1 + /v1/vms).
- `Authorization: Bearer agd_...` — your API key, the only credential you will
  hold. Your human mints the first one at https://dashboard.agidock.cloud.
- Send an `Idempotency-Key` on every mutating call: nothing rejects you for
  omitting it, and it is what makes a retry after a timeout safe.
- Errors are RFC 7807 problem+json — `code`, `detail`, `status`, `title` — with
  a stable `code` and a `detail` that states the fix. Read `detail` before
  retrying anything.

## The machines

- One site, Los Angeles, US. No region field, and no second region to fail
  into.
- AMD EPYC Milan (Zen 3) — `x86-64-v3`, AVX2, no AVX-512. Pick binaries to
  match.
- 10 Gbps network, shared with other VMs. Egress metered per GB, inbound
  free.
- Storage is redundant, on root disks and volumes alike. Not a backup — only a
  snapshot covers your own deletes.

## Money

- Prepaid credits only; nobody can owe anything, 1 credit = 1 USD, and adding
  any is your human's.
- At zero, mutating calls answer `402 credit_cutoff` and running VMs are NOT
  killed. `GET /v1/billing/balance` carries the runway estimate that warns you
  first; what happens if the balance stays there is under that code in
  /docs/api.md.

## What will refuse you

- HUMAN-ONLY (403 `human_required`) says WHO may call: a dashboard session,
  never an API key. It covers money, every call under /v1/account/totp, and
  POST /v1/account/unfreeze. No retry and no step-up changes it — ask your
  human.
- STEP-UP (403 `totp_step_up_required`) says HOW RECENTLY a dashboard session
  entered an authenticator code. Sessions only; it never challenges an API key,
  so this code cannot reach you and needs no handling.
- Past that boundary the calls are yours to MAKE, not to hand over. Your human
  holds no key and runs no client, so a list of requests for them to execute is
  not an answer to "set me up".

## What can stop you

- `POST /v1/account/freeze` halts the account at once, and your key may call
  it — an agent that concludes it is doing damage can stop itself. Only your
  human can release it: unfreeze is human-only and wants an authenticator code
  besides.
- Compliance cases carry deadlines you have to answer by; missing one escalates
  to content takedown or your VMs stopped. Poll `GET /v1/compliance/cases`.
- `POST /v1/support/tickets` reaches a human and keeps working while
  credit-capped and while suspended. The `feedback` type needs no problem
  behind it and is the only channel there is for one — file it yourself.

## Not offered, and not pending

Managed databases, runtimes, build pipelines, object storage, a platform
firewall beyond anti-spoof, log and metric dashboards, VM consoles, and VM
live migration. Run what you need on a VM.

## Legal

ToS /legal/tos.html · AUP /legal/aup.html · Privacy /legal/privacy.html,
versioned, with signup recording the accepted version. DMCA designated agent:
abuse@agidock.cloud