Give an Eve agent a Nevia computer as its sandbox, so its file tools and commands run on the computer
The Eve adapter gives an Eve agent a sandbox on a Nevia computer. The agent's file tools and its commands 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 Eve's sandbox provider contract, so Eve's custom provider docs cover the options and the lifecycle. This page covers only what is particular to Nevia.
Prerequisites
You need:
- Node.js 24.22.1 or later.
eve0.91 or later.- An API key for the model provider. The quick start uses Anthropic, so it
needs
ANTHROPIC_API_KEY. - The
neviaCLI, signed in withnevia 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 -xzThen install the adapter, with the SDK beside it, from the bundle:
npm init -y
npm pkg set type=module
npm install ./vendor/nevia-sdk-0.1.0/typescript/nevia-sdk-0.1.0.tgz \
./vendor/nevia-sdk-0.1.0/typescript/nevia-eve-0.1.0.tgz \
eve zod
npm install --save-dev tsxName 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 loads its TypeScript files into Eve with tsx
through NODE_OPTIONS="--import tsx".
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
An Eve agent is a folder of files. Create agent/agent.ts:
import { defineAgent } from 'eve'
import { anthropic } from 'eve/models/anthropic'
export default defineAgent({
model: anthropic('claude-sonnet-5-5'),
})Create agent/instructions.md:
You write and run code in your sandbox. Work in /workspace. Use run_command to run commands.Create agent/sandbox.ts, which opens the sandbox on a Nevia computer:
import { defineSandbox } from 'eve/sandbox'
import { NeviaSandbox } from '@nevia/eve'
export const environment = NeviaSandbox.environment({ image: 'docker.io/library/node:24-slim' })
export default defineSandbox(() => environment.open())Create agent/tools/run_command.ts. Eve's own bash tool needs background
processes, which the adapter doesn't run, so this tool runs a foreground
command on the computer instead:
import { neviaComputerOf } from '@nevia/eve'
import { defineTool } from 'eve/tools'
import { z } from 'zod'
export default defineTool({
description: 'Run a shell command in the workspace and wait for it to end.',
inputSchema: z.object({ command: z.string() }),
async execute({ command }, ctx) {
const sandbox = await ctx.getSandbox()
const result = await neviaComputerOf(sandbox).exec(command, {
cwd: sandbox.resolvePath('.'),
transport: 'direct',
})
return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode }
},
})Create agent/tools/bash.ts to turn off Eve's bash tool so the model can't
pick it:
import { disableTool } from 'eve/tools'
export default disableTool()Start the agent in one terminal:
NODE_OPTIONS="--import tsx" npx eve dev --no-uiAsk it from a second terminal:
npx eve remote connect --url http://localhost:2000 --print \
"Write hello.js that prints the Node.js version, then run it. Answer with its output only."The agent writes /workspace/hello.js with Eve's write_file tool, runs
node hello.js with run_command and answers with the output. The Node.js
version varies:
v24.22.2The first tool call opens the session's sandbox, which creates the computer.
Clean up
Eve deletes the computer when it ends or deletes the session. Stopping
eve dev doesn't end its sessions, so the quick start's computer stays.
nevia ls lists it as eve- and a hash, and nevia rm deletes it:
nevia ls
nevia rm eve-<hash>To sleep or keep the computer when a session ends, set onSessionEnd to
'sleep' or 'keep' in NeviaSandbox.environment().
How the sandbox maps to a computer
NeviaSandbox.environment() returns an Eve sandbox environment that
environment.open() opens for each session, so the agent uses Eve's own file
tools. It takes image, env for environment variables stored on the
computer, workdir, onSessionEnd, onStop and nevia for client options.
neviaComputerOf() returns the SDK Computer behind a sandbox for tools you
write yourself.
The adapter names the computer after the Eve session, so a later turn finds
the same computer, files included. image and env apply only when the
adapter creates the computer. Relative paths resolve from /workspace, the
working directory.
sandbox.stop() sleeps the computer, and the next turn wakes it with its files
intact. onStop: 'keep' leaves it running instead. A sleeping computer's disk
still counts toward storage until the session ends with the default
onSessionEnd: 'delete' or you run nevia rm.
Commands run in the foreground. With transport: 'direct', exec() keeps the
last 64 KiB of each output stream and sets truncated when it drops output.
Pass maxOutputBytes for another cap.
Limitations
These add to the SDK's Limits and workarounds.
- No background processes or stdin. Eve's
spawn,run,bash,globandgrepanswernot_supported. Run commands,findandgrepthrough your own command tool, as the quick start does. Apreparecallback can't run commands either. - No network policy. The sandbox has no
setNetworkPolicy(), so the computer keeps its default network access. - No tool sessions. A keyed tool call that reaches the sandbox gets Eve's
ToolSessionSandboxUnsupportedError. - Cancelling doesn't stop the command. Aborting a call closes the connection, but the command can keep running on the computer.
- Large workspaces start slowly. Eve writes workspace and skill files one call at a time at every session start.
- The image needs
findandgrep. Eve's file tools call them. - Every turn wakes the computer. That includes a turn that never uses the sandbox.