composio

When to Apply

• User wants to access or interact with external apps (Gmail, Slack, GitHub, Notion, etc.)
• User wants to automate a task using an external service (send email, create issue, post message)
• Building an AI agent or app that integrates with external tools
• Multi-user apps that need per-user connections to external services

Setup

Check if the CLI is installed; if not, install it:

curl -fsSL https://composio.dev/install | bash

After installation, restart your terminal or source your shell config, then authenticate:

composio login       # OAuth; interactive org/project picker (use -y to skip)
composio whoami      # verify org_id, project_id, user_id

For agents without direct browser access: composio login --no-wait | jq to get URL/key, share URL with user, then composio login --key <cli_key> --no-wait once they complete login.

1. Use Apps via Composio CLI

Use this when: The user wants to take action on an external app directly — no code writing needed. The agent uses the CLI to search, connect, and execute tools on behalf of the user.

Key commands (new top-level aliases):

• composio search "<query>" — find tools by use case
• composio execute "<TOOL_SLUG>" -d '{...<input params>}' — execute a tool
• composio link [toolkit] — connect a user account to an app (agents: always use --no-wait for non-interactive mode)
• composio listen — listen for real-time trigger events

Typical workflow: search → link (if needed) → execute

Full reference: Composio CLI Guide

2. Building Apps and Agents with Composio

Use this when: Writing code — an AI agent, app, or backend service that integrates with external tools via the Composio SDK.

Run this first inside the project directory to set up the API key:

composio init

Full reference: Building with Composio

Sandbox and network

Composio operations are network-heavy: CLI install, OAuth login, tool search, tool execution, and trigger subscriptions all make outbound calls. If any of these fail with a network error (ECONNREFUSED, ETIMEDOUT, "unreachable", or a hung login), check whether Codex is running inside a sandbox before declaring the install or login broken. Codex sandboxing can block:

• curl -fsSL https://composio.dev/install | bash (and the post-install binary download from Composio's CDN).
• composio login (OAuth redirect, browser handoff, and token exchange).
• composio execute, composio search, and composio listen (calls to Composio's tool-router and the 1000+ external app APIs).
• mcp__composio__* MCP tool calls and COMPOSIO_REMOTE_BASH_TOOL / COMPOSIO_REMOTE_WORKBENCH if outbound network is sandboxed.

Request approval and retry the same command outside the sandbox. If the outside-sandbox retry succeeds, treat the in-sandbox failure as a sandbox artifact and continue. Do not report that the install URL is invalid, the auth flow is broken, or a remote app is unreachable until the outside-sandbox retry also fails. For agents without direct browser access, composio login --no-wait | jq is the recommended handoff — make sure that pattern is not swallowed by the sandbox.