> ## 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.

# Composio

> Give an agent built on Composio its own Orgo computers. Connect an Orgo API key once and the agent can create, control and delete computers alongside its other apps.

![Composio](https://mintcdn.com/orgo/1i6tklq7D4D0DkJj/images/composio-light.svg?fit=max\&auto=format\&n=1i6tklq7D4D0DkJj\&q=85\&s=7b7665441aaea8d36e430f649dbc58be)

[Composio](https://composio.dev) connects AI agents to the apps their users already use. Orgo is a Composio toolkit, with the slug `orgo`. An agent built on Composio can create an Orgo computer, run code on it, read its screen, click and type, and stop or delete it, through the same session it uses for Gmail, GitHub or Slack.

The toolkit has 34 tools, listed in [Tools in the Orgo toolkit](#tools-in-the-orgo-toolkit). It reaches Orgo with your Orgo API key, so it can do what that key can do and no more.

> [!NOTE]
>
> Computers the agent creates run on your Orgo account and bill to it, the same as computers you create from the dashboard, the API or the CLI.

Composio also works the other way round. Orgo's own [Connectors](https://docs.orgo.ai/guides/connectors.md) sign an agent on an Orgo computer into Gmail, Slack, Notion and other apps through Composio, as described in [Composio inside Orgo](#composio-inside-orgo).

## Before you start

You need three keys:

* **An Orgo API key.** Create one at [orgo.ai/api-keys](https://www.orgo.ai/api-keys). [Choose what the key can reach](#choose-what-the-key-can-reach) before you create it.
* **A Composio API key.** Copy it from your project's settings in the [Composio dashboard](https://dashboard.composio.dev) and set it as `COMPOSIO_API_KEY`.
* **A model key.** The examples on this page use Claude, so set `ANTHROPIC_API_KEY`. Composio supports other providers, listed in [Composio's providers](https://docs.composio.dev/docs/providers).

## Choose what the key can reach

The toolkit acts with the Orgo key you give it. Give it a key made for the agent, not your own account key.

* **Limit it to one workspace.** A workspace-scoped key reaches that workspace's computers and no others.
* **Limit what it can do.** A key can be restricted to some permission groups at read or write, as described in [API key permissions](https://docs.orgo.ai/api-reference/api-keys/permissions.md).
* **Give it an end date.** A key can expire, as described in [Key expiry and rotation](https://docs.orgo.ai/api-reference/api-keys/expiry-and-rotation.md).

> [!WARNING]
>
> The four template tools need an account-wide key: `ORGO_LIST_TEMPLATES`, `ORGO_GET_TEMPLATE`, `ORGO_LIST_TEMPLATE_VERSIONS` and `ORGO_VALIDATE_TEMPLATE`. With a workspace-scoped key they fail with `403` and the code `workspace_scope_mismatch`.

To cut the agent off, delete the key at [orgo.ai/api-keys](https://www.orgo.ai/api-keys).

## Connect your Orgo account to Composio

The Orgo toolkit signs in with an API key, not OAuth. Composio stores the key for one of your users, under the `user_id` you pass when you create a session. Connect it once per user.

There are two ways to connect:

* **Let the agent ask.** The first time the agent calls an Orgo tool with no connection, Composio's `COMPOSIO_MANAGE_CONNECTIONS` tool returns a Connect Link. Show the link to the user.
* **Connect up front.** Create the link yourself, before the agent runs, for onboarding or a settings page.

To create the link up front:

```python Python theme={null}
from composio import Composio

composio = Composio()

session = composio.create(user_id="user_123", toolkits=["orgo"])
connection_request = session.authorize("orgo")

# Open this URL and paste the Orgo API key.
print(connection_request.redirect_url)
```

```typescript TypeScript theme={null}
import { Composio } from "@composio/core";

const composio = new Composio();

const session = await composio.create("user_123", { toolkits: ["orgo"] });
const connectionRequest = await session.authorize("orgo");

// Open this URL and paste the Orgo API key.
console.log(connectionRequest.redirectUrl);
```

Replace `user_123` with a stable ID for the person the agent acts for, such as their database ID. Open the link, paste the Orgo API key, and save. The key goes to Composio, not through your app or the model.

## Give an agent Orgo tools

Create a session limited to the `orgo` toolkit, hand its tools to the model, and run the tool calls it asks for. Each example asks the agent to list your workspaces and create a computer.

> [tab] Python
>
> ```bash theme={null}
> pip install composio composio_anthropic anthropic
> ```
>
> ```python theme={null}
> import json
>
> import anthropic
> from composio import Composio
> from composio_anthropic import AnthropicProvider
>
> provider = AnthropicProvider()
> composio = Composio(provider=provider)
> client = anthropic.Anthropic()
>
> session = composio.create(user_id="user_123", toolkits=["orgo"])
> tools = session.tools()
>
> messages = [
>     {
>         "role": "user",
>         "content": "List my Orgo workspaces, then create a computer named qa-browser "
>         "in the first one. I confirm the creation. Reply with its computer ID.",
>     }
> ]
>
> response = client.messages.create(
>     model="claude-opus-5-5",
>     max_tokens=4096,
>     tools=tools,
>     messages=messages,
> )
>
> while response.stop_reason == "tool_use":
>     tool_use_blocks = [block for block in response.content if block.type == "tool_use"]
>     results = provider.handle_tool_calls(response=response, session=session)
>     messages.append({"role": "assistant", "content": response.content})
>     messages.append(
>         {
>             "role": "user",
>             "content": [
>                 {
>                     "type": "tool_result",
>                     "tool_use_id": tool_use_blocks[i].id,
>                     "content": json.dumps(result),
>                 }
>                 for i, result in enumerate(results)
>             ],
>         }
>     )
>     response = client.messages.create(
>         model="claude-opus-5-5",
>         max_tokens=4096,
>         tools=tools,
>         messages=messages,
>     )
>
> for block in response.content:
>     if block.type == "text":
>         print(block.text)
> ```

> [tab] TypeScript
>
> ```bash theme={null}
> npm install @composio/core @composio/anthropic @anthropic-ai/sdk
> ```
>
> ```typescript theme={null}
> import Anthropic from "@anthropic-ai/sdk";
> import { Composio } from "@composio/core";
> import { AnthropicProvider } from "@composio/anthropic";
>
> const composio = new Composio({ provider: new AnthropicProvider() });
> const client = new Anthropic();
>
> const session = await composio.create("user_123", { toolkits: ["orgo"] });
> const tools = await session.tools();
>
> const messages: Anthropic.MessageParam[] = [
>   {
>     role: "user",
>     content:
>       "List my Orgo workspaces, then create a computer named qa-browser " +
>       "in the first one. I confirm the creation. Reply with its computer ID.",
>   },
> ];
>
> let response = await client.messages.create({
>   model: "claude-opus-5-5",
>   max_tokens: 4096,
>   tools,
>   messages,
> });
>
> while (response.stop_reason === "tool_use") {
>   const toolResults = await composio.provider.handleToolCalls(session, response);
>   messages.push({ role: "assistant", content: response.content });
>   messages.push(...toolResults);
>   response = await client.messages.create({
>     model: "claude-opus-5-5",
>     max_tokens: 4096,
>     tools,
>     messages,
>   });
> }
>
> for (const block of response.content) {
>   if (block.type === "text") console.log(block.text);
> }
> ```

> [tab] MCP
>
> Create the session with `mcp` turned on, then pass its URL and headers to any MCP client. No provider package is needed.
>
> ```bash theme={null}
> pip install composio claude-agent-sdk
> ```
>
> ```python theme={null}
> import asyncio
>
> from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, ClaudeSDKClient
> from composio import Composio
>
> composio = Composio()
> session = composio.create(user_id="user_123", toolkits=["orgo"], mcp=True)
>
>
> async def main():
>     options = ClaudeAgentOptions(
>         mcp_servers={
>             "composio": {
>                 "type": "http",
>                 "url": session.mcp.url,
>                 "headers": session.mcp.headers,
>             }
>         },
>     )
>     async with ClaudeSDKClient(options=options) as client:
>         await client.query("List my Orgo workspaces and the computers in each.")
>         async for msg in client.receive_response():
>             if isinstance(msg, AssistantMessage):
>                 print(msg.content)
>
>
> asyncio.run(main())
> ```
>
> `session.mcp.headers` holds your Composio API key. Keep it server side, as you would the key itself.

Composio's own guides cover the [OpenAI](https://docs.composio.dev/docs/providers/openai) provider, the [Claude Agent SDK](https://docs.composio.dev/docs/providers/anthropic) provider, and [sessions over MCP](https://docs.composio.dev/docs/sessions-via-mcp).

## Tools that ask for confirmation

Eleven tools change something you may not be able to undo. Each takes a required `confirmed` boolean, which the model must set to `true` only after the user approves that exact action:

`ORGO_CREATE_COMPUTER`, `ORGO_DELETE_COMPUTER`, `ORGO_SET_COMPUTER_POWER_STATE`, `ORGO_SUSPEND_COMPUTER`, `ORGO_RESUME_COMPUTER`, `ORGO_EXECUTE_CODE`, `ORGO_RUN_COMPUTER_AGENT`, `ORGO_CONTROL_POINTER`, `ORGO_SEND_KEYBOARD_INPUT`, `ORGO_DELETE_SCREEN` and `ORGO_DELETE_FILE`.

> [!WARNING]
>
> `confirmed` is an instruction to the model, not a check. Composio does not send it to Orgo, and an agent running with no one watching can set it itself. Limit what the agent can do with the key, as described in [Choose what the key can reach](#choose-what-the-key-can-reach).

## Find the IDs the tools need

* **`workspace_id`.** `ORGO_CREATE_COMPUTER` needs it with your own Orgo key, and Orgo rejects a create without one. `ORGO_LIST_WORKSPACES` returns every workspace the key can reach, with its computers. Tell the agent which workspace to use, or let it call `ORGO_LIST_WORKSPACES` first.
* **`computer_id`.** The computer's UUID, the same ID as in `GET /computers/{id}`. `ORGO_CREATE_COMPUTER` returns it, and so does `ORGO_LIST_WORKSPACES`.
* **`screen_id`.** `default` is the screen the computer boots with. `ORGO_LIST_SCREENS` returns the rest.

## Tools in the Orgo toolkit

| Group | Tools |
| - | - |
| Workspaces | `ORGO_LIST_WORKSPACES` |
| Computers | `ORGO_CREATE_COMPUTER`, `ORGO_GET_COMPUTER`, `ORGO_DELETE_COMPUTER`, `ORGO_SET_COMPUTER_POWER_STATE` (start, stop, restart), `ORGO_GET_COMPUTER_OPERATION`, `ORGO_SUSPEND_COMPUTER`, `ORGO_RESUME_COMPUTER`, `ORGO_GET_COMPUTER_SUSPENSION`, `ORGO_WAIT_ON_COMPUTER` |
| Screen and input | `ORGO_GET_SCREENSHOT`, `ORGO_CONTROL_POINTER` (click, drag, scroll), `ORGO_MOVE_MOUSE`, `ORGO_SEND_KEYBOARD_INPUT` |
| Code and agents | `ORGO_EXECUTE_CODE` (Bash or Python), `ORGO_RUN_COMPUTER_AGENT` |
| Screens | `ORGO_LIST_SCREENS`, `ORGO_GET_SCREEN`, `ORGO_CREATE_SCREEN`, `ORGO_RESIZE_SCREEN`, `ORGO_DELETE_SCREEN` |
| Files | `ORGO_LIST_FILES`, `ORGO_UPLOAD_WORKSPACE_FILE`, `ORGO_PLACE_FILE_ON_COMPUTER`, `ORGO_START_FILE_UPLOAD`, `ORGO_COMPLETE_FILE_UPLOAD`, `ORGO_EXPORT_FILE`, `ORGO_GET_FILE_DOWNLOAD_URL`, `ORGO_DELETE_FILE` |
| Templates | `ORGO_LIST_TEMPLATES`, `ORGO_GET_TEMPLATE`, `ORGO_LIST_TEMPLATE_VERSIONS`, `ORGO_VALIDATE_TEMPLATE`, `ORGO_GET_TEMPLATE_SCHEMA` |

Every parameter, with its type and allowed values, is on [Composio's Orgo toolkit page](https://docs.composio.dev/toolkits/orgo).

## Composio inside Orgo

An agent running on an Orgo computer, such as Hermes or OpenClaw, can use Gmail, Google Calendar, Slack, Notion and more through Orgo's [Connectors](https://docs.orgo.ai/guides/connectors.md). Orgo connects some of those apps through Composio, so their sign-in pages show Composio's name. Connecting an app there needs no Composio account of your own.

## Composio or Orgo's own MCP server

Use Composio when your agent already runs on Composio, or needs Orgo next to other apps in one session with one place for each user's connections. For an MCP client that needs only Orgo, such as Claude, Cursor or Codex, connect [Orgo's MCP server](https://docs.orgo.ai/guides/mcp.md) directly. To call Orgo from your own code without either, use the [API](https://docs.orgo.ai/api-reference/introduction.md) or the [CLI](https://docs.orgo.ai/guides/cli.md).

## Good to know

* Composio's tools call the same Orgo API as everything else, so the limits on your account apply, as described in [Account limits](https://docs.orgo.ai/guides/account-limits.md).
* A tool result comes back as Composio's `{ "data", "error", "successful" }` object, with Orgo's response or error inside it.
* Full reference: [docs.composio.dev/toolkits/orgo](https://docs.composio.dev/toolkits/orgo).


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