# AgentCloud

> The agent-native cloud. Deploy a source directory to a live HTTPS URL with
> managed Postgres/Redis/Mongo, via one API. The CLI, REST API, and MCP server
> are equivalent surfaces over the same contract. One bearer token plus the
> skill.md below is the entire onboarding — no human steps.

## Start here (fetch these first)
- [skill.md — the machine contract](https://api.agentcloud.ac/skill.md): every verb, error code, convention, and a runnable quickstart. This is the source of truth.
- [OpenAPI 3.1 spec](https://api.agentcloud.ac/v1/openapi): the full typed API.
- [Install the CLI](https://api.agentcloud.ac/install.sh): `curl -fsSL https://api.agentcloud.ac/install.sh | sh` (macOS/Linux, amd64/arm64).

## The shortest path to a deployed app
1. Install the CLI (above) or use MCP (below) or call REST directly.
2. `export CONWAY_ENDPOINT=https://api.agentcloud.ac CONWAY_TOKEN=<token>`
3. `conway init <name>` then `conway deploy --dir <path>` → returns a live URL.
4. `conway add postgres` injects DATABASE_URL into every service automatically.

## For agents (MCP)
- Install: `claude mcp add conway -e CONWAY_ENDPOINT=https://api.agentcloud.ac -e CONWAY_TOKEN=<token> -- conway-mcp` (the conway-mcp binary ships with the CLI install).
- Tools: conway_get_skill, conway_create_project, conway_status, conway_deploy (packs a local dir), conway_add_datastore, conway_db_query, conway_logs, conway_scale, conway_rollback, conway_set_env, conway_operation, conway_create_repo, conway_list_repos, conway_commit_files (commit generated files with no local git).

## Guides
- [Quickstart](https://docs.agentcloud.ac/guide/quickstart)
- [For agents](https://docs.agentcloud.ac/guide/agents)
- [Deploying services](https://docs.agentcloud.ac/guide/deploying)
- [Databases](https://docs.agentcloud.ac/guide/databases)
- [Environment variables](https://docs.agentcloud.ac/guide/environment)
- [Tokens & delegation](https://docs.agentcloud.ac/guide/tokens)
- [CLI](https://docs.agentcloud.ac/guide/cli)
- [MCP](https://docs.agentcloud.ac/guide/mcp)

## Reference
- [API & verbs](https://docs.agentcloud.ac/reference/api)
- [Error codes](https://docs.agentcloud.ac/reference/errors): every error is {code, message, hint, retryable}; the hint states the next action.

## Conventions an agent should know
- Long ops (deploy) return 202 + operation_id + stream_url (SSE: log/phase/done events, lossless replay). Poll GET /v1/operations/{id} or stream it.
- Idempotent creates return {created:false} when the resource exists.
- dry_run=true returns the planned change without applying.
- Your app must listen on $PORT (default 8080). Builds use a Dockerfile if present, else railpack autodetects the stack.