---
title: 'camelRun'
sidebarTitle: 'Overview'
description: 'A hosted runtime for durable agents. Your tools stay in your code; camelRun runs the model loop, keeps history and files, and wakes agents when there is work.'
---
[View as Markdown](https://camelai.com/docs/camelrun/overview.md) · [Docs index for coding agents](https://run.camelai.com/llms.txt)

> **Tip:**
>
> **Set up with your coding agent.** Paste this into Claude Code, Codex, Cursor
> or any coding agent. It asks you what the agent should do, installs the SDK,
> connects your account without pasting keys into chat, and runs your first
> agent.
>
> ```text
> Read https://run.camelai.com/SKILL.md and set up camelRun in this project. Ask me what the agent should do.
> ```

> **Self-host it.** The runtime is open source and runs anywhere with Docker: one
> container and Postgres. See [Self-hosting](/docs/camelrun/self-hosting).

camelRun is camelAI's hosted agent runtime. You define an agent's tools in your
own code with the TypeScript or Python SDK, or serve them over HTTP. camelRun
runs the model loop, keeps each agent's history and files, compacts long
conversations, runs model-written code in a sandbox, and wakes agents when there
is work. Most agents are asleep at any moment and cost nothing while they are.

```ts TypeScript
import { Agents } from "@camelai/run";

const agents = new Agents(); // reads CAMELAI_API_KEY
const agent = await agents.upsert("support-triage", {
  instructions: "Be concise.",
});
console.log((await agent.run("Which tickets look urgent?")).text);
await agents.close();
```

```python Python
import asyncio
from camelai_run import Agents

async def main():
    async with Agents() as agents:  # reads CAMELAI_API_KEY
        agent = await agents.upsert("support-triage", instructions="Be concise.")
        print((await agent.run("Which tickets look urgent?")).text)

asyncio.run(main())
```

|                     |                                                               |
| ------------------- | ------------------------------------------------------------- |
| **API**             | `https://run.camelai.com/v1`                                  |
| **Console**         | [run.camelai.com/console](https://run.camelai.com/console)    |
| **OpenAPI spec**    | [`/v1/openapi.json`](https://run.camelai.com/v1/openapi.json) |
| **Docs for agents** | [`/llms.txt`](https://run.camelai.com/llms.txt)               |
| **Source**          | [github.com/qaml-ai/run](https://github.com/qaml-ai/run)      |

## Connect your coding agent

The hosted MCP server at `https://run.camelai.com/mcp` needs no API key: sign
in with GitHub or Google when your client asks, which creates your account.
GitHub accounts older than 30 days start with free credit; everyone else
verifies a card on the [Billing](https://run.camelai.com/console/billing) page
(no charge).

### Claude Code

```bash
claude mcp add --transport http camelrun https://run.camelai.com/mcp
# Then run /mcp in Claude Code to sign in. Or skip signing in with a key from your environment:
claude mcp add --scope project --transport http camelrun https://run.camelai.com/mcp \
  --header 'Authorization: Bearer ${CAMELAI_API_KEY}'
```

The single quotes keep `${CAMELAI_API_KEY}` as written: the project's
`.mcp.json` names the variable, and Claude Code reads its value from the
environment. Never write a key's value into an MCP config; they are often
committed.

### Codex

```bash
codex mcp add camelrun --url https://run.camelai.com/mcp
codex mcp login camelrun
```

### Cursor

[Add camelRun to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=camelrun\&config=eyJ1cmwiOiJodHRwczovL3J1bi5jYW1lbGFpLmNvbS9tY3AifQ==),
or add it to `.cursor/mcp.json`:

```json
{ "mcpServers": { "camelrun": { "url": "https://run.camelai.com/mcp" } } }
```

### VS Code

[Add camelRun to VS Code](https://vscode.dev/redirect/mcp/install?name=camelrun\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Frun.camelai.com%2Fmcp%22%7D),
then start the server and sign in when VS Code asks.

### Claude

In claude.ai or the desktop app, go to **Settings**, then **Connectors**,
then **Add custom connector**, and enter
`https://run.camelai.com/mcp`.

## What you get

### Durable, keyed agents

The same key is the same agent, with its history and files, from any
process, until you delete it.

### Tools in your code

Tools run in your process or on your HTTPS endpoint, with your credentials.
MCP servers and OpenAPI specs work too.

### People in the loop

Approvals, questions and forms suspend a run for days, then resume it where
it stopped.

### Chat UI in minutes

React, Vue, Svelte and Solid components stream an agent into your app
without exposing your API key.

### Channels

Slack, Telegram, Discord, GitHub and any service that sends
webhooks can start and talk to agents.

### [Agents as MCP servers](/docs/camelrun/mcp-server)

Every agent is an MCP server, so Claude, Cursor or any MCP client can
message it.

### Any model

Pick from the catalog, bring your own provider keys, or add a model server
of your own.

## Start here

### [Quickstart](/docs/camelrun/quickstart)

An agent that calls a tool in your process, in five minutes.

### [Build a chat app](/docs/camelrun/chat-app)

A streaming chat with your users' agents, from one command.

### [Concepts](/docs/camelrun/concepts)

Keyed agents, runs, events, and where tools run.

### [CLI and MCP server](/docs/camelrun/cli)

Deploy and manage agents from a terminal, or from a coding agent.

## Packages

| Package                   |                                                                                                          |
| ------------------------- | -------------------------------------------------------------------------------------------------------- |
| `@camelai/run` (npm)      | TypeScript SDK: Node 22+, Bun, Deno, Cloudflare Workers                                                  |
| `camelai-run` (PyPI)      | Python SDK: Python 3.11+                                                                                 |
| `@camelai/run-react`      | Chat components and hooks. Vue, Svelte and Solid bindings are `@camelai/run-vue`, `-svelte` and `-solid` |
| `@camelai/create-run-app` | `npm create @camelai/run-app` scaffolds a Next.js chat app                                               |
| `@camelai/camelrun`       | The `camelrun` CLI and local MCP server                                                                  |

## Licensing

The camelRun runtime is licensed under the GNU AGPL-3.0. The SDKs, frontend
packages, CLI and examples are MIT, so you can use them in any application.
Commercial licenses for the runtime are available: contact us through
[camelai.com](https://camelai.com). See [Self-hosting](/docs/camelrun/self-hosting)
to run the runtime yourself.