# AgentMetal: llms-full.txt # The full agent manual. It's the long version of /llms.txt: same product, more # detail. The whole endpoint reference, both payment rails, the MCP tools, # lifecycle and the error contract, all in one file. # # AgentMetal is an infra provider you can use start to finish. There's no signup: # paying IS the signup. Pay with USDC on Base (x402) or a card. Any plan, either # rail, no account. VMs from $1.20/day, with add-on block storage ($0.01/GB/day) # and bandwidth ($2/TB). Coming soon: Agent Memory (a cheap persistence layer in # plain Markdown for what an agent learns). # Status: Phase 1 is live: catalog/provision/status/list/extend/destroy/claim, plus # add-on storage/bandwidth and operate (reboot/diagnostics/exec). BASE_URL: https://api.agentmetal.dev SITE: https://agentmetal.dev MCP_LOCAL: npx @agentmetal/mcp MCP_REMOTE: https://api.agentmetal.dev/mcp DOCS: https://agentmetal.dev/docs/ BLOG: https://agentmetal.dev/blog/ (RSS: https://agentmetal.dev/blog/feed.xml) ## What AgentMetal is (and is not) AgentMetal sells raw Linux VMs to autonomous agents and the humans who run them. You don't need an account to buy, and nobody from sales gets involved. An agent quotes a plan, pays for it inline (HTTP 402), and gets SSH access to a real server in one round-trip. The paying wallet or card owns the server. Accounts are optional. They give you one API key across a fleet, monthly billing and higher quotas. It's NOT a PaaS, a container host, or a managed-app platform. You get a plain VM with a hardened image and root access, and you decide what runs on it. ## Discover for free (no payment, no account) GET /v1/catalog -> plans (specs + per-day price), locations, selectable OS images, and add-on pricing (storage $/GB/day, bandwidth $/TB). Quote before you commit a payment. Discovery needs no auth and costs nothing: the catalog, any server's public status (GET /v1/servers/:id), and the remote MCP's read-only tools. You only pay when you provision or extend. ## Provision a server (the whole product) 1) Request without payment: POST /v1/servers {"plan": "nano", "days": 7} Optional "os": pick an image, e.g. "debian-12" (default "ubuntu-24.04"). Optional "location": a zone. Omit it and you get Hetzner US (ash, then hil). "cdmx-1" is our own bare metal in Mexico City: Ubuntu 22.04/24.04 only, and SSH is on the box's own port of a shared IP (the 201 has ssh_port and the full ssh command). No storage, firewall or bandwidth add-ons there yet. GET /v1/catalog -> images for the list. Other fields: ssh_key, managed_key, via, code (coupon). -> 402 Payment Required listing ALL payment options: accepts[]: x402: exact USDC amount (atomic, 6dp), asset (USDC on Base), payTo address, terms in `description`. card: Stripe card rail: { checkout_url, session_id, poll, note }. 2a) USDC path (x402 v2, synchronous; use this if you're an autonomous agent): - Sign the accepts[0] requirement (EIP-3009 transferWithAuthorization, USDC on Base). It's a gasless signed authorization, not an on-chain send. - base64-encode the payment payload, retry the identical request with: X-PAYMENT: Idempotency-Key: # replays return the original response - -> 201 {id, status, plan, ipv4, ssh:"root@", expires_at, renew} NOTE: x402 is a SIGNED authorization in this header, not a transfer. Do NOT send USDC by hand to payTo. A manual transfer isn't tied to a request, never provisions a box, and the funds are lost. Pay through an x402 client (@x402/fetch + @x402/evm, or @agentmetal/mcp). ACCESS: pass your own "ssh_key" (public key) in the request to authorize SSH; without one the box has no inbound SSH access. MANAGED KEY: pass "managed_key": true and AgentMetal generates a server-side ed25519 keypair. You get the private key ONCE in the 201 response (it's stored encrypted and never shown again). It's what lets the /exec route run commands. 2b) Card path (async, human-in-the-loop): - Hand card.checkout_url to a human to pay in a browser. - Poll card.poll (GET /v1/orders/) until it returns {status:"ready", server:{...}, ssh_private_key}. - Card checkout can't carry your key, so a managed key is auto-issued and handed back there once (the human also sees it on /ok). If you hold a wallet, use 2a: it's one call and needs no human. COUPONS: add "code":"AM-…" to the POST. - A percentage code lowers the quoted amount on both rails (shown in card checkout). - A 100% code skips payment and returns the box plus a managed SSH key in the 201. - Each code works once. A coupon can also grant a lease longer than the standard 1-30 day cap (up to 90 days). FAILURE GUARANTEE: crypto is verify -> provision -> settle (never charged if provisioning fails). Card provisioning retries across locations and Stripe redelivers the webhook until it succeeds. A charge is refunded only if no location can fulfil the server. You never keep a charge without a server. ## Plans (prepaid per day, 1-30 days per payment; any payer, no registration) nano 2 vCPU / 2 GB / 40 GB $1.20/day (or $30/mo monthly with account) small 3 vCPU / 4 GB / 80 GB $2.20/day (or $55/mo monthly with account) medium 4 vCPU / 8 GB / 160 GB $4.20/day (or $99/mo monthly with account) All plans include: 20 TB/mo egress, NVMe storage, US regions (ash + hil), outbound port 25 blocked, hardened base image, root access. ## Add-ons (on a provisioned server) Bandwidth: buy extra egress at $2/TB beyond the 20 TB/mo included: POST /v1/servers/{id}/bandwidth {"tb": N} Storage: attach a block volume at $0.01/GB/day (prorated): POST /v1/servers/{id}/storage {"gb": 10-1000} # auto-mounted at /mnt/HC_Volume_ ## Accounts & claiming (optional, for convenience) Anonymous purchases keep working; the paying wallet/payment owns the server. Register an account and you get one api_key (am_live_...) managing all claimed machines, fleet-wide list_servers, monthly card billing, higher fair-use quotas. POST /v1/claim {"email": "..."} -> OTP email (AgentMail OK) POST /v1/claim/verify {"email","code"[,"wallet","wallet_signature"]} -> {account, api_key, servers_claimed} Linking a wallet requires wallet_signature: sign the message "AgentMetal: link wallet to " with the wallet. Omit it and the 400 hint returns the exact message to sign. ## Fair use (defaults, not gates) Default quotas (active servers per wallet/account, provisioning rate) are there to stop abuse; registered accounts get higher defaults. AgentMetal may ask for verification (email/card) on risk signals, at its discretion. Quota errors say what happened and what to do next. Mining, DDoS and spam are banned. ## Endpoints (full reference) GET /v1/catalog plans + locations + add-on pricing (free) POST /v1/servers provision (402-gated: x402 or card) GET /v1/servers/:id status (free) POST /v1/servers/:id/extend {"days": N} renew (402-gated; anyone may pay) DELETE /v1/servers/:id destroy (owner only, no refund) POST /v1/servers/:id/bandwidth {"tb": N} extra egress at $2/TB (402-gated) POST /v1/servers/:id/storage {"gb": 10-1000} block volume $0.01/GB/day (402-gated) POST /v1/servers/:id/reboot soft reboot (account key + ownership) GET /v1/servers/:id/diagnostics status + recent actions + VNC console + metrics, hypervisor-level, no SSH (account key + ownership) POST /v1/servers/:id/exec {"command","timeout_seconds"?} run as root over SSH -> {exit_code, stdout, stderr}; 1-120s / 256 KB bounded; needs managed_key:true (account key + ownership) GET /v1/self who am I? call FROM the box; authed by source IP, no account (AWS-IMDS-style) -> {server_id, plan, status, ipv4, expires_at, firewall} GET /v1/servers/:id/firewall list inbound firewall rules POST /v1/servers/:id/firewall/rules {"protocol":"tcp","port":"443"} open a port DELETE /v1/servers/:id/firewall/rules {"protocol":"tcp","port":"443"} close a port POST /v1/claim {"email": "..."} -> OTP email POST /v1/claim/verify {"email","code","wallet"} -> api_key POST /v1/billing/checkout Stripe subscription Checkout (accounts) GET /v1/orders/:session_id card-order poll (from the 402 card.poll link) FIREWALL DEFAULTS: new boxes boot locked down, with inbound SSH(22) + ICMP only. You open anything else through the firewall routes. Authed by source-IP from the box, OR account key + ownership off-box. Removing the last SSH(22) rule needs {"force":true}. AUTH SUMMARY: none + X-PAYMENT (or card checkout) for purchase/status; reboot/diagnostics/exec require Authorization: Bearer am_live_... AND ownership of the server. ## Connect via MCP (Model Context Protocol) Local: all tools; signs USDC payments with YOUR wallet: npx @agentmetal/mcp # set WALLET_PRIVATE_KEY = an EVM key with USDC on Base tools (13): provision_server, get_server, list_servers, extend_server, destroy_server, claim_account, verify_claim, get_catalog, reboot_server, server_logs, exec_command, get_firewall, manage_firewall Remote: no key; discover + quote + status only. Add this URL as a custom/remote MCP connector in ChatGPT (Developer mode), Claude.ai, or Le Chat: https://api.agentmetal.dev/mcp tools: list_plans, get_payment_options, get_server, list_servers ## Machine discovery surfaces - /llms.txt this manual's short form - /llms-full.txt this file - /openapi.json full OpenAPI spec - /.well-known/api-catalog RFC 9727 API catalog - /.well-known/mcp/server-card.json MCP server card - /.well-known/agent-skills/index.json agent skills index - /.well-known/acp.json, /.well-known/ucp.json agent/usage capability profiles - /.well-known/security.txt RFC 9116 security contact - /index.md Markdown homepage (also via Accept: text/markdown) ## Lifecycle - T-24h before expiry: your server's preinstalled cron warns you (MOTD + file). - At expiry: status=expired, VM keeps running (2h grace). - Expiry + 2h: VM destroyed. Renew anytime before that via the `renew` URL. - Your server's /root/SERVER.md is its birth certificate: id, expiry, and the exact renew/claim/spawn commands. ## Errors Every non-2xx body is self-documenting: {error, message, hint, docs}. The `hint` always names the way forward; `docs` links the relevant page. Common cases: 402 (payment required; read accepts[]/card), 400 (bad request; the hint gives the fix), 403 (ownership/auth), 404 (unknown server), 409/429 (quota or rate; the message says what to do next). ## Guides Writeups (x402, the MCP setup, gasless USDC/EIP-3009, ephemeral compute, no-signup VPS): https://agentmetal.dev/blog/ (RSS: /blog/feed.xml) ## Humans Same API, same prices. Pay the card checkout link instead of signing USDC. Human docs: https://agentmetal.dev/docs/ Prefer a web console? AgentMetal Cloud (https://cloud.agentmetal.dev) is our own OpenStack cloud with a browser UI for people: VMs, private networks, load balancers, Heat stacks. Invite-only beta; not reachable through this API yet. Guide: https://agentmetal.dev/docs/#cloud