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

# How the Devin SDK works: local vs cloud

> How the Devin SDK chooses between cloud sessions and local Devin CLI sessions, what they share, and where the API client (devin.api) fits in.

The SDK has three layers. Most code only touches the first.

| Layer | What it is |
| - | - |
| **Sessions** (`createDevin`, `session.run()`) | Drive Devin turn by turn and read what it does as typed events. Runs in the cloud or in the Devin CLI on your machine. |
| **API client** (`devin.api`) | A typed client for everything around sessions: history, pull requests, playbooks, secrets, enterprise. Cloud only. |
| **Integrations** (`@cognition-ai/ai-sdk`, `@cognition-ai/cloudflare-agents`, `@cognition-ai/harness-devin`) | Devin plugged into other frameworks: cloud sessions as AI SDK UI message streams for `useChat`, a Cloudflare Agents `AIChatAgent`, and an AI SDK harness that runs Devin as a `HarnessV1` inside an AI SDK sandbox. |

## Cloud or local: one option

`createDevin()` connects to Devin's cloud over a WebSocket and returns a `CloudDevin`. Pass `cwd`
and it spawns the Devin CLI bundled with the SDK instead, returning a `LocalDevin`. Nothing else
decides which you get, and TypeScript narrows the return type from the options you pass.

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

await using cloud = await createDevin(); // CloudDevin
await using local = await createDevin({ cwd: process.cwd() }); // LocalDevin
```

Both need a `cog_…` API key, from the `apiKey` option or `DEVIN_API_KEY`. Both implement the
same `DevinClient` interface, and their sessions share `run()`, `send()`, `stream()` and
`cancel()`, so code that drives a session does not know where it runs:

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

async function summarize(devin: DevinClient, path: string) {
  const session = await devin.createSession();
  const result = await session.run(`Summarize what ${path} does in two sentences.`);
  return result.text;
}
```

| | Cloud (`CloudDevin`) | Local (`LocalDevin`) |
| - | - | - |
| Where Devin runs | A cloud VM, the same as sessions started from the web app or Slack | A Devin CLI subprocess in `cwd`; tool calls edit real files and run real commands on your machine |
| Connection | WebSocket to the ACP endpoint, `Authorization: Bearer <apiKey>` | ACP over stdio to the bundled CLI |
| Working on a repository | `createSession({ repos: ["org/repo"] })`, cloned into the VM | Whatever is in `cwd` |
| Resuming | `loadSession(id)` resumes; `attach(id)` observes sessions started from the web app or Slack | `loadSession(id)` resumes from the CLI's state directory, which survives restarts |
| `devin.api` | Available | Not available; there is no cloud session behind a local one |
| Isolation from your setup | n/a | Own state under `~/.devin-sdk`; never picks up your interactive CLI login, MCP servers or skills |

The [quickstart example](https://docs.devin.ai/sdk/examples/quickstart.md) runs the same two programs against either with a
`--local` flag; the code is identical, only `createDevin({ cwd })` changes.

## Choosing the ACP version

Both transports speak the [Agent Client Protocol](https://agentclientprotocol.com/). The agent
selects the protocol version during `initialize`: the SDK offers a version, and the agent answers
with the one it will speak. By default the SDK offers ACP v2 and accepts an agent that selects v1,
so a v1-only agent still works. To require v1 instead, for example because the rest of your
stack speaks the stable v1 protocol, pass `acpVersion: 1` (since `0.0.1-beta.6`):

```ts theme={null}
await using cloud = await createDevin({ acpVersion: 1 });
await using local = await createDevin({ cwd: process.cwd(), acpVersion: 1 });

console.log(cloud.protocolVersion); // 1
```

With `acpVersion: 1` the SDK sends only v1 `initialize` fields (`clientCapabilities`,
`clientInfo`) and rejects an agent that selects v2. The same option exists on
`CloudDevin.connect` and `LocalDevin.start`, and `devin.protocolVersion` reports what was
selected. Values other than `1` or `2` are rejected.

Application code does not change with the version. `createSession()`, `loadSession()`, `run()`,
`send()` and `events()` pick the matching protocol methods (`session/load` on v1,
`session/resume` on v2) and completion signal (the prompt result on v1, the idle `state_update`
on v2), and `SessionEventReducer` turns either version's updates into the same typed
`SessionEvent`s. Two things are v2-only: `turn_state` events, and the `replay: "tail"` and
`replay: "none"` options of a cloud `loadSession` (v1's `session/load` always replays the whole
transcript). Raw ACP updates keep their version-specific shapes.

## Where the API client fits

A session object covers live interaction: prompts, streaming events, permissions, cancel. It does
not cover what happens around sessions, and neither does the CLI. That is the
[Devin REST API](https://docs.devin.ai/api-reference/overview.md), and `CloudDevin` exposes a typed client for it as
`devin.api`, already authenticated with your key:

```ts theme={null}
const { session } = await devin.loadSession("devin-…");
await session.run("Open the PR");

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

See [Using devin.api](https://docs.devin.ai/sdk/api/overview.md) for the client's shape, how it is generated, and what it
covers.

> [card] [Local sessions](https://docs.devin.ai/sdk/guides/local-sessions.md)
>
> The bundled CLI, its state directory, permissions and file access.

> [card] [Cloud sessions](https://docs.devin.ai/sdk/guides/cloud-sessions.md)
>
> Resume, attach, base URLs and organizations.

> [card] [Environments](https://docs.devin.ai/sdk/guides/environments.md)
>
> Point either client at a deployment other than production.

> [card] [SDK reference](https://docs.devin.ai/sdk/reference/overview.md)
>
> `createDevin`, `CloudDevin`, `LocalDevin`, and every session and event type.


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