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

# Cloud Devin sessions and devin.api

> Run Devin in the cloud from the SDK: CloudDevin drives sessions over a WebSocket, resumes existing ones, and exposes the API client as api.

`CloudDevin` drives sessions running in Devin's cloud over the same
[Agent Client Protocol](https://agentclientprotocol.com/) as `LocalDevin`, connected over a
WebSocket and authenticated with a personal access token (`cog_…`). Turns, streaming, permission
handling, and `_cognition.ai/*` extension notifications work identically to local sessions.

```ts theme={null}
import { CloudDevin } from "@cognition-ai/sdk";

const cloud = await CloudDevin.connect({ orgId: "org_…" }); // apiKey from DEVIN_API_KEY

const session = await cloud.createSession();
const result = await session.send("Summarize the open PRs in this repo");
console.log(result.stopReason);

// Resume an existing cloud session by id.
const { session: resumed, replay } = await cloud.loadSession("devin-…");

cloud.close();
```

## MCP servers

`CloudDevin` accepts the same `mcpServers` session option as
[local sessions](https://docs.devin.ai/sdk/guides/local-sessions.md#mcp-servers):

```ts theme={null}
import type { McpServer } from "@cognition-ai/sdk";

const mcpServers: McpServer[] = [
  {
    name: "remote-tools",
    type: "http",
    url: "https://mcp.example.com/mcp",
    headers: [],
  },
];

const session = await cloud.createSession({ mcpServers });
```

When you load or attach to a session, pass the option again:
`cloud.loadSession(id, { mcpServers })` or `cloud.attach(id, { mcpServers })`.
The SDK forwards the list in ACP `session/new`, `session/load`, or `session/resume`
requests. An omitted option or `mcpServers: []` sends an empty list.

> [!NOTE]
>
> Tool availability depends on the cloud ACP endpoint and its MCP support.
> The SDK forwards the configuration but does not enable server-side MCP support.
> Support in the local CLI does not establish support in a cloud deployment.

## Where it runs

`CloudDevin` needs a `WebSocket` that can send the `Authorization` header, so it runs on Node.js,
Bun, Cloudflare Workers and Deno 2.5 or newer (since `0.0.1-beta.2`; the SDK uses the runtime's
built-in `WebSocket`, or a `fetch` upgrade on Workers, and no longer depends on `ws`). Runtimes
whose `WebSocket` cannot send headers — browsers, Vercel Edge, older Deno — get a `DevinError`
from `connect()`. Local sessions need Node.js or Bun, because they spawn the Devin CLI.

## Cancelling a turn

`session.stream()`, `streamUpdates()`, `send()`, `postMessage()` and `run()` accept `{ signal }`
(since `0.0.1-beta.2`). Aborting cancels the Devin turn right away — it ends with `stopReason:
"cancelled"` — and an already-aborted signal throws before the prompt is sent. In a server route,
pass the request's signal so a client that stops listening stops Devin too:

```ts theme={null}
export async function POST(request: Request) {
  const session = await cloud.attach(id);
  for await (const event of session.stream(prompt, { signal: request.signal })) {
    // …
  }
}
```

## The API client escape hatch

ACP covers live interaction; everything else — session snapshots, structured output, pull
requests, and platform resources (playbooks, secrets, organizations) — lives on the
[Devin REST API](https://docs.devin.ai/api-reference/overview.md). The cloud client exposes a typed client for all of it
as `api`, authenticated with the same key:

```ts theme={null}
const snapshot = await devin.api.sessions.getSession({ org_id: "org_…", devin_id: session.id });
console.log(snapshot.status_detail, snapshot.structured_output, snapshot.pull_requests);
```

`api` is cloud-only. See [Using devin.api](https://docs.devin.ai/sdk/api/overview.md) for the client's shape,
errors, pagination, and the generated reference for every resource. To point the client at a
deployment other than production, see [Environments](https://docs.devin.ai/sdk/guides/environments.md); for the same
session API on your own machine, see [Local sessions](https://docs.devin.ai/sdk/guides/local-sessions.md). To export
session traces to Langfuse or another OpenTelemetry backend, see [Tracing](https://docs.devin.ai/sdk/guides/tracing.md).


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