> ## 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).
</Tip>

## 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](/api-reference/authentication) | 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](/guides/mcp) 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": 600
}
```

**2. Ask the person to approve.** Send them `verification_uri_complete`. They sign in and approve within 10 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. |
| `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 [Settings → Credentials](https://www.orgo.ai/settings/credentials).

<Accordion title="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)
  ```
</Accordion>

An agent that can run the [CLI](/guides/cli) gets the same flow from `orgo login`.

## Make sure the account has a plan

Accounts are free. Creating a computer needs a paid plan. If the account has none, 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.
</Warning>

## 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"}'
```

The request returns when the computer is running. Its `id` is the `$COMPUTER_ID` for every call below. Set `os` to `windows` for Windows. See [Create computer](/api-reference/computers/create) 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](/api-reference/chat/completions).

## 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](/guides/skill) |


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