---
title: "Ample for developers and agents"
description: "The CLI, REST API, remote MCP server, agent skills and machine-readable files for building on Ample."
canonical_url: "https://ample.computer/docs"
last_updated: "2026-10-31"
---

# Ample for developers and agents

Ample is driven from the command line or from an agent. Install the CLI, or connect through the REST API and the remote MCP server.

## Quick start

```sh
curl -fsSL https://get.ample.computer/install.sh | sh
ample auth signup
ample plan --write && ample up
```

Base URL for the REST API: `https://api.ample.computer`.

## Deploy over HTTP

No CLI needed: send the app's source as a tar.gz and get back a live URL, or the reason it failed.

```sh
TOKEN=$(curl -s -X POST https://api.ample.computer/v1/auth/signup -H 'Content-Type: application/json' \
  -d '{"name":"my-agent","request_key":"<fresh UUID v4>"}' | jq -r .access_token)
tar -czf app.tgz -C ./my-app .
curl -X POST https://api.ample.computer/v1/deploy -H "Authorization: Bearer $TOKEN" -H 'Idempotency-Key: my-app-1' \
  -F name=my-app -F public=true -F env=API_KEY=... -F source=@app.tgz
# 200 {"status":"live","url":"https://….ample.run","deployment_id":"dep_…","unchanged":false,"execution_id":"run_…"}
# 200 {"status":"failed","error":{"code":"health_check_failed","message":"…","details":{"owner":"app","diagnosis":"…",
#        "evidence":[…],"suggested_fix":{"change":"…","confidence":"high"}}},"execution_id":"run_…"}
# 202 {"status":"running","execution_id":"run_…","poll":"/v1/deploy/run_…"}
```

- Fields: `source` (the app as a tar.gz, up to 32 MiB), `name` (letters, digits, `-`, `_`, `.`; deploying the same name again updates that app), `public` (`true` or `false`; web apps are public by default), `env` (`KEY=value`, repeatable, stored encrypted) and `start` (optional: the command that starts the app, listening on `$PORT`, for a source Ample can't read it from). Needs the `servers:read` and `servers:write` scopes.
- Ample detects the stack from the source, builds it and starts it, exactly as `ample deploy` does.
- The request waits up to 50 seconds. A longer deploy answers 202: `GET https://api.ample.computer/v1/deploy/<execution_id>` (it also waits up to 50 seconds) until it answers 200.
- `status` is `live`, `failed` or `needs_input`. On `failed`, `error.details` says who must act (`owner`: `app`, `account`, `platform` or `unknown`), with a `diagnosis`, the `evidence` (such as the app's log tail) and a `suggested_fix` (`change` and `confidence`). On `needs_input`, `error.resolution` says what to send; usually it is `start`, when the source has nothing Ample knows how to start. An unchanged redeploy returns `unchanged: true`.
- A failed redeploy rolls back to the previous release. When the server has room, Ample first starts the new release beside the live one and switches over only once it answers, so a release that crashes on start never takes the app down.
- Send the same `Idempotency-Key` (8 to 96 characters) with the same request to retry after a disconnect: it reattaches to the deploy that key started. The same key with a different request answers 409 `idempotency_conflict`. A deploy of an app that is already deploying answers 409 with that deploy's poll URL.

## Resources

- [Agent instructions](https://ample.computer/AGENTS.md): When to use Ample, how to deploy, accounts and scopes.
- [Authentication](https://ample.computer/auth.md): Self-serve signup, OAuth client credentials, scoped tokens.
- [OpenAPI 3.1](https://ample.computer/openapi.json): REST API description for https://api.ample.computer.
- [Remote MCP](https://api.ample.computer/mcp): Streamable HTTP endpoint. Setup: https://api.ample.computer/mcp/setup. Tool catalog: https://api.ample.computer/mcp/catalog.
- [MCP server card](https://ample.computer/.well-known/mcp/server-card.json): Registry-format record of the remote MCP server.
- [A2A agent](https://api.ample.computer/a2a): A2A 1.0 over JSON-RPC; the MCP tools as skills. Agent card: https://ample.computer/.well-known/agent-card.json.
- [Agent skills](https://ample.computer/.well-known/agent-skills/index.json): deploy-app, connect-app-services and migrate-app-components skills for Claude Code, Cursor and Codex.
- [Recipe catalog API](https://api.ample.computer/v1/catalog): Public JSON catalog of verified deployment recipes; POST /v1/catalog/search to rank by constraints.
- [Resource discovery](https://ample.computer/.well-known/ard.json): Agentic Resource Discovery manifest; RFC 9727 catalog at /.well-known/api-catalog.
- [llms.txt](https://ample.computer/llms.txt): Curated site index for language models; llms-full.txt has every guide in full.
- [API health](https://api.ample.computer/health): Returns 200 when the API is serving.

## Conventions

- `ample deploy` and `ample up` are synchronous; exit code 0 is live, 1 failed, 2 blocked on a required action. Never poll by re-running.
- Every MCP tool takes an `execution_key`; reusing it after a disconnect retrieves the result instead of replaying the mutation.
- Errors are JSON objects `{"error":{"code":"...","message":"..."}}`.
- Every HTML page on this site has a Markdown alternate: append `.md` or send `Accept: text/markdown`.