> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# For agents

> Give an AI agent access in one approval. How Claude, Codex, or any agent connects to Orgo, creates a computer, and uses it.

An AI agent needs three things: access, a computer, and a way to use it. This page covers each in the fewest steps.

> [!TIP]
>
> Give your agent [orgo.ai/orgo.md](https://www.orgo.ai/orgo.md). It is this whole flow as one markdown file. For the full docs as text, use [llms.txt](https://docs.orgo.ai/llms.txt) or [llms-full.txt](https://docs.orgo.ai/llms-full.txt).

## Get access

Pick one. Each needs a person to approve once.

| Way | Use it when | The person |
| - | - | - |
| [MCP](#connect-over-mcp) | The agent runs in an MCP client: Claude Code, Claude Desktop, Cursor, Codex | Signs in and picks a workspace |
| [Device approval](#get-an-api-key-with-device-approval) | The agent can make HTTP calls or run a shell | Approves a short code |
| [Settings](https://docs.orgo.ai/api-reference/authentication.md) | A server or CI job needs a key | Creates and copies a key |

### Connect over MCP

Add the hosted server. No key to copy.

```bash theme={null}
claude mcp add --transport http orgo https://www.orgo.ai/mcp
```

In any other client, add `https://www.orgo.ai/mcp` as a remote MCP server. The client opens Orgo in a browser. The person signs in, chooses a workspace, and approves. The connection can create and use computers in that workspace. See [MCP](https://docs.orgo.ai/guides/mcp.md) for the tools and for local setups.

### Get an API key with device approval

The agent starts a request, the person approves it in a browser, and the agent collects an account-wide API key. No key is ever pasted into a chat.

**1. Start.** No auth needed.

```bash theme={null}
curl -X POST https://www.orgo.ai/api/cli/auth/start \
  -H "Content-Type: application/json" \
  -d '{"client": "my-agent", "hostname": "laptop"}'
```

```json theme={null}
{
  "device_code": "c893fbd6-60c8-449b-8298-6557ea306fa5",
  "user_code": "6K2-UY4-2Q6",
  "verification_uri": "https://www.orgo.ai/cli/approve",
  "verification_uri_complete": "https://www.orgo.ai/cli/approve?code=6K2-UY4-2Q6",
  "interval_seconds": 2,
  "expires_in_seconds": 1800
}
```

**2. Ask the person to approve.** Send them `verification_uri_complete`. They sign in and approve within 30 minutes.

**3. Poll** every `interval_seconds` with the `device_code`.

```bash theme={null}
curl -X POST https://www.orgo.ai/api/cli/auth/poll \
  -H "Content-Type: application/json" \
  -d '{"device_code": "c893fbd6-60c8-449b-8298-6557ea306fa5"}'
```

`status` is `pending` until the person acts, then one of:

| `status` | Next step |
| - | - |
| `approved` | Read `api_key` and keep it secret. It is returned once. Collect it before the code expires: a key nobody collects within a minute after that is revoked, and the poll answers `expired`. |
| `denied` | Stop. The person said no. |
| `expired` | Start again. |

```json theme={null}
{
  "status": "approved",
  "api_key": "sk_live_...",
  "key_id": "...",
  "user": { "id": "...", "email": "person@example.com" }
}
```

The key is named "CLI on" plus the `hostname` you sent. The person can revoke it in [API keys](https://www.orgo.ai/api-keys).

> [accordion] The whole flow as one script
>
> ```bash theme={null}
> start=$(curl -s -X POST https://www.orgo.ai/api/cli/auth/start \
>   -H "Content-Type: application/json" \
>   -d "{\"client\": \"my-agent\", \"hostname\": \"$(hostname)\"}")
> echo "Approve here: $(echo "$start" | jq -r .verification_uri_complete)"
>
> device_code=$(echo "$start" | jq -r .device_code)
> while :; do
>   sleep 2
>   poll=$(curl -s -X POST https://www.orgo.ai/api/cli/auth/poll \
>     -H "Content-Type: application/json" \
>     -d "{\"device_code\": \"$device_code\"}")
>   status=$(echo "$poll" | jq -r .status)
>   [ "$status" != "pending" ] && break
> done
>
> [ "$status" = "approved" ] || { echo "Not approved: $status"; exit 1; }
> export ORGO_API_KEY=$(echo "$poll" | jq -r .api_key)
> ```

An agent that can run a shell gets the same flow and a running computer from one command, `npx -y orgo@latest init`. It waits for the approval, so give it a 10 minute timeout; if the shell stops it, run it again and it continues. `orgo login` signs in only. See [CLI](https://docs.orgo.ai/guides/cli.md).

## Try Orgo free

You can test computer use with no plan. Two ways in:

* **A person is here.** Sign them in with device approval (above). A new account gets \$5 of starting credit the first time it is used signed in, if it passes the [free checks](https://docs.orgo.ai/guides/account-limits.md#free-accounts-without-a-card): a few accounts a day per address, network and email domain; nothing free from a server, datacenter or VPN address or a throwaway inbox; the credit once per inbox. If a check holds it back, adding a card gets it.
* **No person to approve.** [Agent signup](https://docs.orgo.ai/guides/agent-signup.md) gives the agent its own account with $2 of starting credit, no email or card. It pays for computers, not AI. An account that adds less than $5 of credit in all and is never claimed expires 72 hours after signup: its computers stop and its keys stop working, and 2 days later its computers are deleted.

What the starting credit runs:

* **One Medium Linux computer** (2 vCPU, 8 GB RAM, 40 GB disk) by the hour: $0.055 an hour while it runs, $0.0027 while it is stopped, so \$5 is about 90 running hours. Add `"billing_mode": "hourly"` to the create request below, or leave it out with an API key. A person's starting credit also pays for AI.
* **One at a time, Medium only.** Another computer answers `403` `HOURLY_LIMIT`. A size you name is ignored: a free account always gets a Medium. Free computers share running places: when they are full, a launch or a Start answers `503` `FREE_HOURLY_BUSY`; try again in a few minutes. Credit the person buys lifts the one at a time limit and the shared places, up to 50 Medium computers. Other sizes and Windows need a plan.
* **When a free check refuses**, the answer is `429` with code `NEEDS_CARD`, a plain `error` and often `needs` (`turnstile` or `phone`) with a `verify_url`. Send the person that link, or ask them to add a card. `NEEDS_PAYMENT` means their card already lifted another account: credit or a plan is the way on.

When the credit runs out, the computer stops and its files are kept 7 days. Add credit and start it, or choose a plan with room for it (the plan takes it over). After 7 days without credit, the computer and its files are deleted.

## Make sure the account has a plan

For always-on computers, other sizes and more of them, the account needs a plan or credit the person buys: either one lifts the account to 50 computers, and past 50 more run by the hour from credit, up to 999. If the account has no plan, the agent can get a checkout link for the person:

```bash theme={null}
curl -X POST https://www.orgo.ai/api/checkout \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan": "hacker_v2"}'
```

`plan` is `hacker_v2` (Starter), `startup_v2` (Growth), or `scale_v2` (Scale). The response has a Stripe Checkout `url`. Send it to the person to pay. Prices are in [pricing.md](https://www.orgo.ai/pricing.md).

> [!WARNING]
>
> Call checkout only for an account with no plan. With an API key, a call on an account that already has a plan changes that plan without asking.

## Create a computer

Find a workspace. The list is under `workspaces`.

```bash theme={null}
curl https://www.orgo.ai/api/workspaces \
  -H "Authorization: Bearer $ORGO_API_KEY"
```

If it is empty, create one with `POST /workspaces` and `{"name": "agents"}`. Then create the computer:

```bash theme={null}
curl -X POST https://www.orgo.ai/api/computers \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id": "'"$WORKSPACE_ID"'", "name": "agent-1"}'
```

It answers `201` with the computer's `status`. Until it is `running`, poll `GET /computers/$COMPUTER_ID`; a computer just made can take a few seconds to answer. With no size, a free account gets a Medium by the hour and a plan gets 4 GB and 1 vCPU. Its `id` is the `$COMPUTER_ID` for every call below. Set `os` to `windows` for Windows, which needs the Scale plan or a Windows add-on on another paid plan. See [Create computer](https://docs.orgo.ai/api-reference/computers/create.md) for sizes and templates.

## Use the computer

Run commands and see the screen directly:

```bash theme={null}
# Run a shell command
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/bash \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "uname -a"}'

# Save a screenshot
curl "https://www.orgo.ai/api/computers/$COMPUTER_ID/screenshot?response_format=binary&format=png" \
  -H "Authorization: Bearer $ORGO_API_KEY" -o screen.png

# Click, then type
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/click \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x": 640, "y": 400}'
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/type \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "hello"}'
```

Or hand over a whole task. Orgo's Computer Use agent screenshots, clicks, and types until it is done:

```bash theme={null}
curl https://www.orgo.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "computer_id": "'"$COMPUTER_ID"'",
    "messages": [{"role": "user", "content": "Open Chrome and find the weather in Paris"}]
  }'
```

The endpoint is OpenAI-compatible. See [Create chat completion](https://docs.orgo.ai/api-reference/chat/completions.md).

## When you're stuck, ask

Orgo's support agent answers questions about using Orgo, with full URLs and commands you can run. Ask it before guessing:

```bash theme={null}
curl -X POST https://www.orgo.ai/api/v1/support/ask \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "question": "How do I set up Hermes on my computer?" }'
```

With a key it also reads the account's plan and computers, and can hand the conversation to Orgo's team. See [Ask support](https://docs.orgo.ai/api-reference/support/ask.md).

## Reference for agents

| What | Where |
| - | - |
| The whole flow in one file | [orgo.ai/orgo.md](https://www.orgo.ai/orgo.md) |
| Authentication, OAuth discovery | [orgo.ai/auth.md](https://www.orgo.ai/auth.md) |
| OpenAPI spec | [orgo.ai/openapi.json](https://www.orgo.ai/openapi.json) |
| Plans and limits | [orgo.ai/pricing.md](https://www.orgo.ai/pricing.md) |
| Docs index | [docs.orgo.ai/llms.txt](https://docs.orgo.ai/llms.txt) |
| Claude Code skill | [Skill](https://docs.orgo.ai/guides/skill.md) |
| Questions about Orgo | [Ask support](https://docs.orgo.ai/api-reference/support/ask.md) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.