Quickstart

This walk-through installs the agentserve CLI, deploys a two-service app (a FastAPI backend plus a React/Vite frontend) and claims it into a new account. It takes a few minutes, most of it spent on the frontend's npm install, which runs on AgentServe, not on your machine.

You need uv to install the CLI. Nothing else: the build runs on AgentServe.

Deploy and claim#

1. Install the CLI#

   uv tool install agentserve
   agentserve --help

   The CLI deploys to https://agentserve.sh. You don't need an account yet.

2. Deploy#

   Point the CLI at a project directory. This one, todo-app, has a FastAPI backend and a React frontend, wired together by an agentserve.yaml like the one in Multi-service stacks:

   agentserve deploy ./todo-app

   The CLI packs the directory into a tar.gz (skipping node_modules, .git, virtualenvs and similar), uploads it, and waits for the build. The manifest sets ttl: 1h. When the stack is live you get something like:

     ✓ todo-app  stk_3f9a1c2b7d4e  [live]
       api      python-3.12  https://api-todo-app-8c1f.agentserve.sh
       web      static       https://web-todo-app-8c1f.agentserve.sh
   
     Expires in 59 min. To keep it, open:
     https://agentserve.sh/claim/CLM-7KQ4-XM2P-9RTW

   The CLI also writes .agentserve/stack.json into the project directory. It holds the stack id and the manage token, so the next deploy from that directory updates the same stack. It is git-ignored automatically; don't commit it. If the linked stack was deleted, the CLI says so and creates a new one; if it expired, the CLI stops and points at the claim URL. --new always starts a separate stack.

3. Open the URLs#

   Open the web URL in your browser and add a few todos. The frontend was built with VITE_API_URL set to the api URL, and the API allows the web origin through CORS_ORIGINS; both come from ${...} references in the manifest.

   curl https://api-todo-app-8c1f.agentserve.sh/todos

   The API stores todos in SQLite under $DATA_DIR, which survives redeploys, expiry and claiming.

4. Look around with the CLI#

   Point them at the project directory:

   agentserve status ./todo-app
   agentserve logs ./todo-app --service api
   agentserve logs ./todo-app --build
   agentserve events ./todo-app

   status shows the services and the expiry, logs shows runtime logs (or build logs with --build), and events lists what happened to the stack, such as service.building, service.ready and stack.live.

5. Claim it#

   Open the claim URL. The page shows the stack, its services and how long it has left. Enter an email and a password of at least 8 characters: a new email creates an account, an existing one signs you in. Submit, and the stack is yours.

   The confirmation page shows your API key once. Copy it now; it is stored only as a hash and can't be shown again (you can rotate it later from /account). The stack no longer has a TTL, and it appears in /dashboard.

6. Deploy straight into your account#

   With the key in the environment, new deploys go directly into your account, with no claim code and no TTL:

   export AGENTSERVE_API_KEY="as_live_..."
   agentserve deploy ./my-app

Clean up#

To remove a stack and its data, run agentserve destroy ./todo-app. This deletes the processes, the files and the credentials, and removes the local .agentserve/stack.json. For a claimed project you can also delete it from its settings page in the dashboard.

Next#

• How it works: states, TTLs, snapshots and tokens.
• Multi-service stacks: write your own agentserve.yaml.
• Connect your agent: let Claude Code, Cursor or another agent deploy for you.