Local Devin sessions with the SDK

LocalDevin runs the Devin CLI as a subprocess in cwd. Tool calls edit real files and run real commands there, so permission requests are rejected unless you handle them.

import { createDevin } from "@cognition-ai/sdk";

await using devin = await createDevin({
  cwd: "/path/to/project",
  onPermission: () => "allow",
});

The CLI ships with the SDK as per-platform npm packages listed as optionalDependencies, so the binary is in node_modules and versioned by your lockfile. createDevin and LocalDevin.start always run that bundled, officially published build. It runs isolated from any Devin CLI you use interactively: the SDK hands it your API key and keeps its config, sessions, and cache under ~/.devin-sdk (override with stateDir), so it never picks up the host’s ~/.config/devin login, MCP servers, or skills, and a script behaves the same on a laptop and in CI. The SDK never falls back to the CLI’s own devin auth login credential store.

Driving the CLI directly

LocalDevin.start is the explicit form of createDevin({ cwd }):

import { LocalDevin } from "@cognition-ai/sdk";

const local = await LocalDevin.start({
  cwd: "/path/to/project",
  // Permission requests (e.g. running shell commands) are rejected unless handled.
  onPermission: (request) => {
    console.log(request.toolCall.title);
    return "allow";
  },
});

const session = await local.createSession();

// Stream the turn's typed events (message/thought deltas, tool calls, plans)…
for await (const event of session.stream("Fix the failing test in src/utils")) {
  if (event.type === "message_delta") process.stdout.write(event.text);
  if (event.type === "tool_call") console.log(event.call.title, event.call.status);
}

// …or just wait for the result.
const result = await session.send("Now run the test suite");
console.log(result.stopReason, result.usage);

local.close();

To run a CLI that is already installed and signed in, for example inside a sandbox, use LocalDevin.spawn(cliPath, options?, env?). It starts cliPath as devin acp with exactly env (default process.env) and does not take an API key or a stateDir, so the CLI uses its own login and config.

const local = await LocalDevin.spawn("/usr/local/bin/devin", { cwd: "/path/to/project" });

MCP servers

Pass mcpServers to createSession to give a session access to your MCP tools. The public McpServer type supports stdio, HTTP, and SSE servers.

import type { McpServer } from "@cognition-ai/sdk";

const mcpServers: McpServer[] = [
  {
    name: "project-tools",
    command: "node",
    args: ["/absolute/path/to/mcp-server.mjs"],
    env: [{ name: "PROJECT_ROOT", value: "/path/to/project" }],
  },
  {
    name: "remote-tools",
    type: "http",
    url: "https://mcp.example.com/mcp",
    headers: [],
  },
];

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

Replace the command, paths, and URL with your own servers. Stdio servers use command, args, and env. Their type: "stdio" field is optional. HTTP and SSE servers require type: "http" or type: "sse", a url, and a headers array. Both env and headers contain { name, value } entries and can be empty arrays. When you load or attach to a session, pass the servers again: local.loadSession(id, { mcpServers }) or local.attach(id, { mcpServers }). An omitted option or mcpServers: [] sends an empty list in the ACP request. The SDK does not change the caller’s configuration. The SDK’s bundled CLI updates to 3000.11.1 with this fix. That build registers the MCP servers supplied in ACP session requests. For LocalDevin.spawn or LocalDevin.connect, use CLI 3000.11.1 or a newer build with the same support. See the SDK changelog for the SDK release status.

Models and Fusion

model (on LocalDevin.start, createSession, or session.setModel) takes a model id the CLI accepts for your account, or a Fusion model that pairs a leader model with a sidekick model. session.models() lists both, with the model currently in effect:

import { Fusion, ModelRejectedError } from "@cognition-ai/sdk";

const session = await local.createSession();
const models = session.models();
console.log(models?.current); // e.g. "swe-2-high"
console.log(models?.options.filter((m) => m.id.startsWith("fusion-")).map((m) => m.id));

await session.setModel(Fusion({ leader: "claude-opus-5-max", sidekick: "swe-2-high" }));
await session.setModel("fusion-adaptive"); // let Fusion pick the pairing

Fusion({ leader: "claude-opus-5-max", sidekick: "swe-2-high" }).id;
// "fusion-claude-opus-5-max-sidekick-swe-2-high"

try {
  await session.setModel(Fusion({ leader: "claude-opus-5-max", sidekick: "claude-opus-5-max" }));
} catch (error) {
  if (error instanceof ModelRejectedError) console.error(error.reason); // the CLI's explanation
}

models() reads the model config option the CLI returns on createSession, loadSession, and every setModel, so it reflects the CLI version and account in use; session.configOptions exposes the other options the same way. The SDK does not check ids itself: a model or pairing the CLI does not advertise rejects setModel with a ModelRejectedError whose model and reason name the id and the CLI’s explanation, and the current model stays in place. To send these sessions’ turns, token usage, and tool calls to Langfuse, see Tracing. The same Session API, run in the cloud with devin.api alongside it, is covered in Cloud sessions. The runnable version of this page is the quickstart example with --local.

Get started

Sessions

Integrations

Examples

SDK reference

API client

Resources

Local Devin sessions with the SDK

Driving the CLI directly

MCP servers

Models and Fusion

​Driving the CLI directly

​MCP servers

​Models and Fusion

Driving the CLI directly

MCP servers

Models and Fusion