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

# Local Devin sessions with the SDK

> Run Devin locally from the Devin SDK: LocalDevin starts the bundled Devin CLI as a subprocess in a directory on your machine.

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

```ts theme={null}
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 })`:

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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](https://docs.devin.ai/sdk/changelog.md) 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:

```ts theme={null}
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](https://docs.devin.ai/sdk/guides/tracing.md).

The same `Session` API, run in the cloud with `devin.api` alongside it, is covered in
[Cloud sessions](https://docs.devin.ai/sdk/guides/cloud-sessions.md). The runnable version of this page is the
[quickstart example](https://docs.devin.ai/sdk/examples/quickstart.md) with `--local`.


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