Agent frameworks

Flue

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

The Flue adapter gives a Flue 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 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 cover the contract and Flue's sandbox guide 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 shows how to install it.
  • A Nevia key file for a service account with the editor role. Use an automation key file shows how a workspace admin issues one.

Install the adapter

Invited testers only

The SDKs are in early access for invited testers. To ask for access, see Request access to Nevia.

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

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

Authenticate

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

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.

Give an agent a computer

Save this as agent.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:

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:

v24.22.2

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

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.

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

On this page