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

# Devin AI SDK harness

> Run Devin inside an AI SDK sandbox with @cognition-ai/harness-devin, a HarnessV1 adapter for HarnessAgent and useChat.

`@cognition-ai/harness-devin` is a [`HarnessV1`](https://ai-sdk.dev/providers/ai-sdk-harnesses)
adapter backed by `@cognition-ai/sdk`, which drives the Devin CLI over ACP. The adapter ships a
bridge process that runs inside a sandbox and talks to the host over a WebSocket on a
sandbox-proxied loopback port.

This is Devin running inside a sandbox you own. To put a Devin *cloud* session behind `useChat`
instead — no sandbox, Devin works in its own VM — use [`@cognition-ai/ai-sdk`](https://docs.devin.ai/sdk/ai-sdk/overview),
or [`@cognition-ai/cloudflare-agents`](https://docs.devin.ai/sdk/cloudflare-agents/overview) on Cloudflare Workers.

## Setup

Install the adapter together with the AI SDK harness packages:

```sh theme={null}
npm install @cognition-ai/harness-devin@beta @ai-sdk/harness @ai-sdk/sandbox-vercel ai
```

> [!NOTE]
>
> The `@cognition-ai` packages are in beta. Every release is a `0.0.1-beta.N` prerelease on the
> `beta` dist-tag (currently `0.0.1-beta.7`), so the `@beta` suffix is required: a bare
> `npm install @cognition-ai/sdk` fails on purpose. Pin the exact version in your lockfile, and keep
> every `@cognition-ai` package you use (`sdk`, `ai-sdk`, `cloudflare-agents`, `harness-devin`) on
> the same version; they release together. Each published version is stable, but the API can
> change between beta bumps; see the [changelog](https://docs.devin.ai/sdk/changelog.md) for what moved.

## Usage

```ts theme={null}
import { HarnessAgent } from "@ai-sdk/harness/agent";
import { createDevin } from "@cognition-ai/harness-devin";
import { createVercelSandbox } from "@ai-sdk/sandbox-vercel";
import { tool } from "ai";
import { z } from "zod";

const agent = new HarnessAgent({
  harness: createDevin({
    apiKey: process.env.DEVIN_API_KEY,
    model: "claude-sonnet-5-medium",
  }),
  sandbox: createVercelSandbox({
    runtime: "node24",
    ports: [4000],
  }),
  tools: {
    deploy: tool({
      description: "Deploy a service.",
      inputSchema: z.object({ env: z.enum(["staging", "production"]) }),
      execute: async ({ env }) => ({ url: `https://${env}.example.com` }),
    }),
  },
});

const session = await agent.createSession();

try {
  const result = await agent.generate({
    session,
    prompt: "List the files in this workspace and describe their purpose.",
  });
  console.log(result.text);
} finally {
  await session.destroy();
}
```

The adapter requires a `HarnessV1SandboxProvider` whose handles expose at least one port for the
bridge WebSocket (`ports: [<port>]`, or `createDevin({ port })`). Use `session.detach()` to park
the bridge and sandbox, `session.stop()` to save state and stop the sandbox, or
`session.destroy()` to clean up without keeping resume state.

## Known limitations

The adapter preserves live text streaming, but cannot faithfully apply ACP updates that replace
or withdraw text already sent. The current `HarnessV1` text events support starting a block,
appending text, and ending it; they have no replacement or withdrawal event.

If Devin revises earlier text, the streamed and assembled response can retain the old text or
append the replacement beside it. For example, `"draft"` followed by a replacement of `"final"`
can appear as `"draftfinal"`. Ordinary append-only streaming is unaffected.

This limitation applies to the harness adapter. The core SDK's `SessionEventReducer` handles
replacement and withdrawal updates; use `@cognition-ai/sdk` directly when those semantics are
required.

What the adapter reports while it sets up the sandbox and session is listed in
[Diagnostics](https://docs.devin.ai/sdk/harness/diagnostics.md); the [harness-chat example](https://docs.devin.ai/sdk/examples/harness-chat.md)
is a complete Next.js app built on it.


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