---
name: agentserve
description: Deploy a project (one or more services, e.g. a FastAPI backend plus a React frontend) to a live URL without an account. Use when the user wants to see, share or test what you built. Unclaimed stacks expire; hand the claim URL to the user so they can keep it.
---

# AgentServe

Deploys are anonymous and temporary. You get live URLs, a manage token and a **claim URL**. The stack runs for
its TTL (default and max 1h), then stops. The user can open the claim URL at any time, create an account and
keep the stack: it comes back at the same URLs with its data.

## Deploy

```bash
agentserve deploy ./my-project --ttl 30m
```

Run it again in the same directory to redeploy the same stack: the URLs stay the same. The CLI saves its state in
`.agentserve/stack.json`. That file holds a secret token, so don't commit it.

With no manifest, a single service is inferred from `requirements.txt`/`pyproject.toml` (Python), `package.json`
(Node, or static if it has a build step but no start script) or `index.html` (static). For several services,
add `agentserve.yaml`:

```yaml
name: todo-app
ttl: 1h
services:
  api:
    path: ./backend
    runtime: python-3.12
    start: uvicorn main:app --host 127.0.0.1 --port $PORT
    health: /healthz
    env:
      CORS_ORIGINS: ${web.url}
  web:
    path: ./frontend
    runtime: static          # built once, served by AgentServe
    build: npm run build
    output: dist
    env:
      VITE_API_URL: ${api.url}   # resolved before the build, so it is baked into the bundle
    depends_on: [api]
```

- Services must listen on `127.0.0.1:$PORT`.
- References: `${svc.url}`, `${svc.host}`, `${svc.internal_url}`, `${svc.port}`.
- Limits: 4 services, a 50 MB upload, and 3 unclaimed stacks running per network. No managed databases yet. Keep
  SQLite files and uploads in `$DATA_DIR`, a per-service directory that survives redeploys, expiry and claim.
  Anything written elsewhere is lost on the next deploy.

## After deploying

1. Give the user the URLs **and the claim URL**. Tell them when the stack expires. For example: "Live at … until
   15:40. Open the claim link to keep it."
2. If a redeploy fails, the previous version keeps serving. The response has `deploy_error` and the CLI exits 1.
   If the deploy failed, read the logs with `agentserve logs --build` (build) or `agentserve logs --service api`
   (runtime). Fix the problem and run `agentserve deploy` again.
3. `agentserve extend --ttl 30m` moves the expiry to 30 minutes from now, up to 1h after creation. `agentserve destroy` removes the stack.

Never claim a stack yourself unless the user gave you their `AGENTSERVE_API_KEY`. With that key in the
environment, deploys go straight into their account with no TTL.

## HTTP API (if the CLI isn't available)

- `POST /v0/stacks`: multipart form with `source` (a tar.gz) and optional `manifest`, `ttl` and `name`.
  Add `?wait=true`. The response contains `manage_token`, `claim_url` and the services' URLs. `wait` holds the
  request for at most 90 s: if `status` is still `building` (or `deploying` is set), repeat
  `GET /v0/stacks/{id}?wait=true` until it isn't.
- `GET|PATCH|DELETE /v0/stacks/{id}` with `Authorization: Bearer <manage_token>`. PATCH takes `{"ttl": "30m"}`.
- `POST /v0/stacks/{id}/deploy` redeploys. `GET /v0/stacks/{id}/logs?service=api&kind=build|run`.
- `GET /v0/stacks/{id}/events` returns `stack.live`, `stack.deploy_failed`, `service.crashed`/`service.restarted`
  (crashed services are restarted automatically), `stack.expiring`, `stack.expired`, `stack.claimed`, and so on.
- `notify: {webhook: URL}` in the manifest pushes the same events to that URL. They are signed with the
  `webhook_secret` returned at creation: `X-AgentServe-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<body>">`.