Claiming a stack

Claiming moves an anonymous stack into an account. The stack keeps its id, its URLs and its data, and loses its TTL. You can claim while the stack is live or within 7 days after it expired.

Where the claim code comes from#

Every anonymous deploy returns a claim_code and a claim_url. The CLI prints the URL after each deploy and keeps both in .agentserve/stack.json; the MCP tool deploy_stack and the HTTP API return them in the response. The agent's job is to hand the URL to its human, along with when the stack expires.

https://agentserve.sh/claim/CLM-7KQ4-XM2P-9RTW

Stacks deployed with an API key are already owned and have no claim code.

Claim in the browser#

1. Open the claim URL. If you only have the code, go to /claim and type it in. Case, spaces and dashes don't matter.
2. The page shows the stack, its services and their URLs, and how long it has left, or, if it expired, how long the snapshot is kept.
3. If you are signed in, the stack goes into that account. Otherwise enter an email and a password. A new email creates an account (the password needs at least 8 characters); an email that already has an account signs you in.
4. Submit. The stack is now yours, and you are signed in.

When the claim created a new account, the confirmation page shows your API key once. Store it: it is kept only as a hash. You can rotate it later from /account, which immediately invalidates the old key.

The claim form is rate limited to 10 attempts per minute per IP address.

Claim with the CLI#

An agent that has its human's API key can claim on their behalf:

export AGENTSERVE_API_KEY="as_live_..."
agentserve claim CLM-7KQ4-XM2P-9RTW

Claimed todo-app (stk_3f9a1c2b7d4e).

Without AGENTSERVE_API_KEY set, the command stops and tells you to open the claim URL in a browser instead. Under the hood it calls the API, which you can also use directly:

curl -X POST https://agentserve.sh/v0/claim \
  -H "Authorization: Bearer $AGENTSERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"claim_code": "CLM-7KQ4-XM2P-9RTW"}'

It returns the stack as JSON. A code that doesn't exist or was already used returns 404. API claims are rate limited to 10 per minute per IP address.

What changes after a claim#

• No TTL. expires_at becomes null and the stack never expires. agentserve extend on a claimed stack returns 409: claimed stacks have no TTL.
• Expired stacks come back. If the stack had expired, it is restored from its snapshot without a rebuild. The confirmation page says it's restoring; services are back within seconds, at the same URLs and with their data.
• The code is spent. The claim code stops working. A stack.claimed event records which account claimed it.
• The dashboard. The project appears in /dashboard, with a service map, deploy history, combined logs, per-service pages with a restart button, activity and settings.
• The API key works on it. The account's API key can read, redeploy and destroy the stack with Authorization: Bearer as_live_….

The agent's token after a claim#

The agent's manage token keeps working after a claim, so the agent can keep redeploying the same stack while you iterate together. When you want to cut it off, open the project's settings in the dashboard and choose Revoke agent token. This can't be undone. The stack emits stack.agent_revoked, and from then on only the account's API key can manage it.

The CLI and the MCP server always send the manage token stored in .agentserve/stack.json when the directory has one. After a revoke, that token is rejected with 403. On deploy, the CLI and the MCP server then retry with AGENTSERVE_API_KEY if it is set, so an owner can keep redeploying the claimed stack; without it, the deploy fails and the directory stays linked to the claimed stack. For anything else after revoking, call the HTTP API with the API key.

Restricting who can claim#

An agent that knows its human's email can bind the stack to it, so a leaked claim link is useless to anyone else. Set it in the manifest:

name: todo-app
claim_email: [email protected]
services:
  ...

or on the CLI with agentserve deploy --claim-email [email protected], or as the claim_email form field of POST /v0/stacks. The flag and the form field take precedence over the manifest. A claim from any other account is refused with "This stack can only be claimed by the email address the agent bound it to." The comparison ignores case.

claim_email only restricts who can claim. AgentServe sends no email: the agent still has to pass the claim URL on itself.