CLI

The agentserve command uploads a project directory, links the directory to the stack it created, and manages that stack afterwards. It talks to the HTTP API; everything it does can be done with curl.

uv tool install agentserve
agentserve deploy ./todo-app --ttl 30m

Synopsis#

agentserve deploy  [PATH] [--ttl TTL] [--name NAME] [--claim-email EMAIL] [--new] [--json]
agentserve status  [PATH] [--json]
agentserve logs    [PATH] [--service NAME] [--build] [--tail N]
agentserve events  [PATH]
agentserve extend  [PATH] --ttl TTL
agentserve destroy [PATH]
agentserve claim   CODE

PATH defaults to the current directory. Every command except deploy and claim needs a stack linked to PATH by an earlier deploy; otherwise it exits with error: no stack linked here; run `agentserve deploy` first.

deploy#

Packs PATH into a tar.gz, uploads it and waits until the build has finished, polling the stack's status. If PATH is already linked to a stack, it redeploys that stack and the URLs stay the same. Otherwise it creates a stack and writes the state file.

Flag	Default	Meaning
--ttl TTL	1h (server default)	Lifetime of a new unclaimed stack, e.g. 30m or 1h. Minimum 15m. Overrides ttl in the manifest.
--name NAME	see below	Stack name. Overrides name in the manifest.
--claim-email EMAIL	none	Only an account with this email can claim the stack.
--new	off	Ignore the linked stack and create a new one. The state file is overwritten.
--json	off	Print the stack object as JSON, with claim_url and claim_code added.

• --ttl, --name and --claim-email only apply when a stack is created. On a redeploy, passing --ttl or --name prints a note; use agentserve extend or --new.
• Without --name, the CLI sends the directory's name when the directory has no agentserve.yaml, agentserve.yml or agentserve.json. With a manifest, the manifest's name is used.
• If the linked stack was deleted (404), the CLI prints The linked stack … no longer exists; creating a new one with new URLs. and relinks the directory to the new stack.
• Any other refusal exits with an error and leaves the directory linked: an expired stack points at its claim URL (or --new), a running build asks you to wait, and a revoked token (403) is retried with AGENTSERVE_API_KEY when set.
• With AGENTSERVE_API_KEY set, a new stack is created in that account: no TTL, no claim URL.

Output:

Uploading todo-app (42 kB)…

  ✓ todo-app  stk_3f9a1c0b2d4e  [live]
    api      python-3.12  https://api-todo-app-3f9a.agentserve.sh
    web      static       https://web-todo-app-3f9a.agentserve.sh

  Expires in 29 min. To keep it, open:
  https://agentserve.sh/claim/CLM-7KQ2-M9XD-4HTW

When a redeploy fails and was rolled back, the output adds The redeploy failed; still serving generation N: and the error, and the command exits 1.

What gets uploaded#

Everything under PATH except these directories: node_modules, .git, __pycache__, .venv, venv, .agentserve, .agentserve-venv, .mypy_cache, .pytest_cache, .ruff_cache, .next; and these files: .DS_Store, *.pyc. There is no ignore file. .env files and other secrets in the directory are uploaded. The upload limit is 50 MB.

status#

Prints the linked stack's status, services and URLs, its expiry and, while unclaimed, the claim URL. --json prints the stack object from GET /v0/stacks/{id}, including role.

logs#

Flag	Default	Meaning
--service NAME	all services	Only this service.
--build	off	Build logs instead of runtime logs.
--tail N	100	Last N lines per service.

agentserve logs --build              # why did the build fail?
agentserve logs --service api --tail 50

Each service's section starts with ### <service> (run) or ### <service> (build).

events#

Prints the first 200 events of the linked stack, oldest first, one per line: local time, type and the JSON payload.

14:02:11  stack.created      {"anonymous": true}
14:02:11  service.building   {"service": "api", "generation": 1}
14:02:19  service.ready      {"service": "api", "url": "https://api-todo-app-3f9a.agentserve.sh"}

The command accepts --json but ignores it. See Events for every type.

extend#

Sets the expiry of an unclaimed stack to now plus --ttl (required). This replaces the current expiry; it does not add to it.

agentserve extend --ttl 1h
# Extended. Expires in 59 min.

Fails with 409 if the stack is claimed (claimed stacks have no TTL) or has already expired, and with 422 if the duration is invalid or the new expiry is past the limit for unclaimed stacks. In that case the error message gives the latest possible expiry.

destroy#

Deletes the linked stack, its processes, files and data, then deletes .agentserve/stack.json. Prints Destroyed stk_…. It cannot be undone. The command accepts --json but ignores it.

claim#

Claims a stack into the account of AGENTSERVE_API_KEY, using its claim code. Without the variable it exits with error: set AGENTSERVE_API_KEY, or open the claim URL in a browser instead.

AGENTSERVE_API_KEY=as_live_… agentserve claim CLM-7KQ2-M9XD-4HTW
# Claimed todo-app (stk_3f9a1c0b2d4e).

The code is accepted in any case, with or without dashes and the CLM prefix. An agent should only claim when its human gave it their API key; otherwise hand the claim URL to the human. See Claiming.

State file#

deploy writes PATH/.agentserve/stack.json and a .gitignore containing * next to it, so the directory is never committed. The MCP server reads and writes the same file, so a stack deployed with one can be managed with the other.

{
  "id": "stk_3f9a1c0b2d4e",
  "manage_token": "ast_anon_…",
  "claim_code": "CLM-7KQ2-M9XD-4HTW",
  "claim_url": "https://agentserve.sh/claim/CLM-7KQ2-M9XD-4HTW",
  "server": "https://agentserve.sh"
}

Field	Meaning
id	Stack id.
manage_token	Secret that manages this stack. Sent as Authorization: Bearer on every later command.
claim_code, claim_url	Anyone with these can take the stack. null for stacks created with an API key.
server	The server the stack was created on. Informational: later commands use AGENTSERVE_URL, not this field.

If the file has no manage token, commands authenticate with AGENTSERVE_API_KEY instead.

Environment variables#

Variable	Default	Meaning
AGENTSERVE_URL	https://agentserve.sh	Server base URL. A trailing slash is removed.
AGENTSERVE_API_KEY	none	An account API key (as_live_…). New stacks go into that account, and claim uses it.

Exit codes#

Code	When
0	Success.
1	Any HTTP error (printed as error: <status> <detail> on stderr), server unreachable, no linked stack, PATH not a directory, claim without an API key. deploy also exits 1 when the stack ends up failed or a redeploy was rolled back (deploy_error is set).
2	Invalid arguments (argparse usage error).

If the server can't be reached, the message is error: can't reach AgentServe at <url> (check your network connection).