How the Devin SDK works: local vs cloud

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.

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:

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 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. 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):

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 SessionEvents. 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, and CloudDevin exposes a typed client for it as devin.api, already authenticated with your key:

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 for the client’s shape, how it is generated, and what it covers.

Local sessions

The bundled CLI, its state directory, permissions and file access.

Cloud sessions

Resume, attach, base URLs and organizations.

Environments

Point either client at a deployment other than production.

SDK reference

createDevin, CloudDevin, LocalDevin, and every session and event type.

Get started

Sessions

Integrations

Examples

SDK reference

API client

Resources

How the Devin SDK works: local vs cloud

Cloud or local: one option

Choosing the ACP version

Where the API client fits

Local sessions

Cloud sessions

Environments

SDK reference

​Cloud or local: one option

​Choosing the ACP version

​Where the API client fits

Local sessions

Cloud sessions

Environments

SDK reference

Cloud or local: one option

Choosing the ACP version

Where the API client fits