# Flue

> Give a Flue agent a Nevia computer as its sandbox, so its file tools and commands run on the computer

> Nevia is in early access for selected teams. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/agent-frameworks/flue

The Flue adapter gives a [Flue](https://flueframework.com) agent a sandbox on
a Nevia computer. The agent's `read`, `write`, `edit`, `bash`, `grep` and
`glob` tools run on the computer, not on your machine. The adapter is built on
the [TypeScript SDK](https://nevia.cloud/docs/reference/sdk/typescript.md) and is in early access,
so names and behaviour can change.

The quick start gives an agent a computer, asks it to write and run a program
and deletes the computer. The adapter follows Flue's sandbox factory contract,
so [Flue's sandbox adapter docs](https://flueframework.com/docs/reference/sandbox-api/)
cover the contract and [Flue's sandbox guide](https://flueframework.com/docs/guide/sandboxes/)
covers the tools. This page covers only what is particular to Nevia.

## Prerequisites

You need:

* Node.js 22.23.4 or later on 22, or 24.22.1 or later.
* `@flue/runtime` 2.3 or later, before 3.
* An API key for the model provider. The quick start uses Anthropic, so it
  needs `ANTHROPIC_API_KEY`.
* The `nevia` CLI, signed in with `nevia login`, to download the SDK bundle.
  The [Quickstart](https://nevia.cloud/docs/get-started/quickstart.md) shows how to install it.
* A Nevia key file for a service account with the **editor** role.
  [Use an automation key file](https://nevia.cloud/docs/guides/automation-key-file.md) shows how a
  workspace admin issues one.

## 1. Install the adapter

> **Invited testers only**
>
> The SDKs are in early access for invited testers. To ask for access, see
> [Request access to Nevia](https://nevia.cloud/docs/get-started/request-access.md).

From your project's root, download the SDK bundle. It unpacks to
`vendor/nevia-sdk-0.1.0/`:

```bash
curl -fsSL --oauth2-bearer "$(nevia auth access-token)" https://sdk.nevia.cloud/0.1.0.tar.gz | tar -xz
```

Then install the adapter, with the SDK beside it, from the bundle:

**npm**

```bash
npm init -y
npm pkg set type=module
npm pkg set 'overrides.@flue/runtime.@earendil-works/pi-ai=~1.4.0'
npm pkg set 'overrides.@modelcontextprotocol/client=2.4.0'
npm install ./vendor/nevia-sdk-0.1.0/typescript/nevia-sdk-0.1.0.tgz \
  ./vendor/nevia-sdk-0.1.0/typescript/nevia-flue-0.1.0.tgz \
  @flue/runtime
npm install --save-dev tsx
```

Name the SDK's file next to the adapter's, so both come from the bundle and
nothing is looked up on a public registry.

The quick start runs with [tsx](https://tsx.is). The two overrides fix Flue
2.3's dependencies. The first keeps pi-ai on 1.4, because Flue imports `Type`
from pi-ai and pi-ai 1.5 removed it. The second moves the MCP client from
2.0.0, which Flue pins and which has two security advisories, to 2.4.0.

## 2. Authenticate

Point the adapter at the key file and set the model provider's key:

```bash
export NEVIA_KEY_FILE="$HOME/path/to/key.json"
export ANTHROPIC_API_KEY="sk-ant-..."
```

Without `NEVIA_KEY_FILE`, the adapter falls back to your `nevia login`
session. It finds credentials in the same order as the
[TypeScript SDK](https://nevia.cloud/docs/reference/sdk/typescript.md#client).

## 3. Give an agent a computer

Save this as `agent.ts`:

```ts
'use agent'
import { init, useModel, useSandbox } from '@flue/runtime'
import { start } from '@flue/runtime/node'
import { neviaSandbox } from '@nevia/flue'

const sandbox = neviaSandbox({ image: 'docker.io/library/node:24-slim' })

export function Coder() {
  useModel('anthropic/claude-sonnet-5-5')
  useSandbox(sandbox)
  return 'You write and run code in your sandbox.'
}

const id = 'quickstart'
await using _flue = await start({ agents: [Coder] })
try {
  const coder = init(Coder, { id })
  const reply = await coder.read(
    await coder.dispatch('Write hello.js that prints the Node.js version, then run it. Answer with its output only.'),
  )
  console.log(reply.text)
} finally {
  await sandbox.destroy(id)
}
```

Run it:

```bash
npx tsx agent.ts
```

The agent writes `hello.js` with the `write` tool, runs `node hello.js` with
`bash` and answers with the output. The Node.js version varies:

```text
v24.22.2
```

Flue creates the computer when it initializes the agent and waits until it is
ready.

## 4. Clean up

Flue never tears a sandbox down, so the `finally` block deletes the computer
with `sandbox.destroy(id)`, also when the call throws. `nevia ls` confirms the
computer is gone.

To keep the computer between runs, skip `destroy()`. The agent `id` names the
computer, so a later program that calls `init()` with the same `id` finds the
same computer, files included. Call `sandbox.destroy(id)` from that program
when you are done.

## How the sandbox maps to a computer

`neviaSandbox()` returns a Flue sandbox factory, so `useSandbox()` gives the
agent Flue's own file and shell tools. It takes `image`, `env` for environment
variables stored on the computer, `cwd`, `prefix` and `nevia` for a client or
its options. `neviaComputer(sandbox)` returns the SDK `Computer` behind a
sandbox for tools you write yourself.

The adapter names the computer `<prefix>-<id>-<hash>` with `flue` as the
default `prefix`, so two agents with the same `id` share one computer. `image`
and `env` apply only when the adapter creates the computer. The working
directory is `/workspace`. The adapter creates it when it is missing.

Flue never sleeps a sandbox between messages, so the computer runs until
`sandbox.destroy(id)` deletes it. Calls on a destroyed sandbox you still hold
return an error. The next `init()` for that `id` creates an empty computer.

Commands run in the foreground with direct exec and keep the last 64 KiB of
each output stream. Truncated output ends `stderr` with a
note. A command that runs past its timeout returns exit code 124 and a note.
The timeout is at most 3600 seconds.

## Limitations

These add to the SDK's [Limits and workarounds](https://nevia.cloud/docs/reference/sdk/limits.md).

* **No background commands.** A command must end before the tool answers.
  Redirect long output to a file instead.
* **Output arrives at the end.** The agent sees a command's output only after
  the command ends.
* **Cancelling doesn't stop the command.** Aborting the call rejects at once,
  but the command and its children can keep running on the computer.
* **A dropped command isn't retried.** If the connection drops after a command
  starts, the call rejects with `bad_response` and the model decides whether to
  run it again.
* **The image needs `find` and `grep`.** Flue's tools call them. Commands run
  under `bash -c`, or `sh -c` when the image has no bash. Neither is a login
  shell.
* **A non-root image user may not be able to create `/workspace`.** Pass a
  `cwd` the user can write to, such as one under `$HOME`.
* **`stat` can leave out `size` and `mtime`.** A directory has no `size`.
  `mtime` is missing when the computer can't read it.
* **The adapter needs Node's HTTP/2.** It doesn't run on Cloudflare Workers.
