# Cosmos Agent

> An AI coding agent you call over HTTPS. Describe a task; Cosmos does the work on its own cloud computer and returns the result.

Cosmos Agent is Clatter Labs' AI agent for coding, available as an API. You send instructions in plain language. Cosmos plans the work, writes and runs code, uses a browser, keeps files, and reports back with an answer and any files it produced.

<CardGroup cols={2}>
<Card title="Start in five minutes" icon="rocket" href="/quickstart">Create a key and run your first task.</Card>
<Card title="API reference" icon="code" href="/api-reference/runs/create">Create, stream, read and cancel runs.</Card>
</CardGroup>

## What a run can do

Each run works on your account's own cloud computer, with these tools:

| Tool | What Cosmos uses it for |
| --- | --- |
| Terminal and files | Install packages, run builds and tests, read and edit code |
| Browser | Open sites, click and type, check what a page really shows |
| Web search and fetch | Look up docs and references |
| Cloud Repos | Keep code in a repository, with history |
| Hosting | Deploy sites and APIs to `<name>.clatterai.com`, with DNS, a SQL database and key-value storage |
| Database and storage | Store data and assets, install skills |
| Sub-agents | Split a big job into parallel pieces |
| Memory | Remember what it learned for later runs |
| Connected apps | Use the connectors and MCP servers on your account |
| Outputs | Save files you get back with the run |

## The run lifecycle

```text
queued ─▶ running ─▶ completed
                 ├─▶ failed      (error.code: run_failed | out_of_credits)
                 └─▶ cancelled   (POST /v1/runs/{id}/cancel)
```

1. **Create** a run with `POST /v1/runs`. You get the run back immediately with status `running`.
2. **Follow** it with the event stream (`GET /v1/runs/{id}/events`) or poll `GET /v1/runs/{id}`.
3. **Read** the result: `output` is Cosmos's final answer; `files` lists what it saved.

Runs keep going if you disconnect. A long task continues in segments past any single request's time limit, up to 150 steps.

## Base URL and authentication

```text
https://api.agent.clatterlabs.xyz
```

Every request sends two headers: your key as a bearer token and your Account ID.

```http
Authorization: Bearer clsk_...
X-Clatter-Account: CL-XXXXXXXX
```

See [Authentication](/api-reference/authentication) for details.

<Note>
The Agent API is **generally available** on **every plan, Free included**. Runs are pay as you go from your [credits](/billing/credits) (plans don't cover API calls); see [Rates](/billing/rates).
</Note>