@asciidev/eve-box connects the two. It is an Eve sandbox backend that maps Eve’s filesystem and process operations onto the Box API, so your Eve agents run on real Box machines instead of your laptop.
New to both? You only need two things to follow this guide: Node.js 18+ and a Box API key. No prior Eve or Box experience required.
How it fits together
- Eve owns your agent logic and calls a sandbox to do filesystem and shell work.
@asciidev/eve-boxis the adapter you plug into Eve.- Box is the machine the work actually happens on.
Set it up
Create a Box account
Sign in at box.ascii.dev with GitHub and start the base plan, which includes a free 7-day trial. You need an account to create boxes. See the Box quickstart for the full onboarding walkthrough.
Get a Box API key
Create a key from the API keys tab of the Box dashboard. Keep it secret: store it in an environment variable, never in source control.
Install the packages
"module": "NodeNext", "target": "ES2022", "lib": ["ES2022", "DOM"]) and "type": "module" in package.json.A complete example
This standalone script creates a Box-backed sandbox session and exercises the operations Eve relies on: running commands, reading files, and writing files. It runs on its own so you can verify your setup before wiring the backend into a larger Eve agent.hello-box.ts
uname output, and exit code 0.
What the backend maps
| Eve operation | Box behaviour |
|---|---|
run | Executes a bounded command in the Box work directory. |
spawn | Starts a background process, with streamed stdout/stderr, wait(), and kill(). |
readTextFile / writeTextFile | Reads and writes files under the Box work directory. |
readBinaryFile / writeBinaryFile | Same, using base64 transfer for binary content. |
removePath | Removes files and directories in the workspace. |
resolvePath | Anchors relative paths to /workspace. |
| create / resume | Creates a new Box, or reconnects to one from Eve’s persisted session state. |
Configuration
asciiBox(options) accepts:
| Option | Default | Description |
|---|---|---|
apiKey | process.env.BOX_API_KEY | Box API key. |
baseUrl | public Box API | Box API base URL. |
name | eve-<sessionKey> | Name, or (input) => string, for boxes Eve creates. |
ttlSeconds | 3600 | Auto-stop TTL in seconds. null disables auto-stop. |
noEnv | false | Withhold your account’s secrets and credentials from boxes (see below). |
env | none | Per-box environment variables for every box Eve creates (see below). |
pollMs | 500 | Poll cadence for spawn() streams and wait(). |
commandTimeoutMs | none | Timeout for blocking run() commands. |
networkPolicy | none | Initial network policy (see below). |
Running agents for other people
WithnoEnv: true the box starts empty and confined to itself. You then give it exactly what it needs: secrets through env, and files and setup through Eve’s onSession hook.
sandbox.ts
env keys merge over your account variables (per-box wins; at most 100 variables, 64 KB total; reserved Box-internal names are rejected). writeFile/readFile move bytes in and out and run/spawn execute commands as the Eve-native equivalents of box scp and box ssh <id> <cmd>. A no-env box can’t reach your private repos, so clone public ones or have the user authenticate inside the box. See No-env boxes.
Reusing a prepared environment
Setup runs when each session’s box is first created. If you want many sessions to start from the same fully prepared state, fork a box: prepare one, stop it so its snapshot completes, then fork it; each clone keeps the entire filesystem. See Fork box.Network policies
Box does not yet enforce Eve’s fine-grained network policies. The backend accepts"allow-all" and throws EveBoxUnsupportedError for stricter policies ("deny-all", allow-lists, subnet rules), so you never get a false sense of isolation. If you need firewall-backed policies, run that Eve agent on a backend that supports them.
Resources
npm package
@asciidev/eve-box on npm.Source on GitHub
Issues, examples, and the adapter source.
Box quickstart
Install Box and create your first sandbox.
Box API keys
Create and manage the key this adapter needs.