Sandboxes

mayura/sandbox gives an agent an isolated Linux machine: it runs commands, reads and writes files and, on some providers, serves ports or shows a desktop. Docker on your own machine is built in (mayura/sandbox/docker); hosted providers come as @mayurajs/sandbox-* packages. Every sandbox has a lifetime, and none reaches the network unless you allow it.

import { createSandboxes } from 'mayura/sandbox';
import { dockerSandboxes } from 'mayura/sandbox/docker';

const sandboxes = createSandboxes(dockerSandboxes({ image: 'node:24-slim' }), {
  maxSandboxes: 4,
  maxLifetimeMs: 30 * 60_000,
});

const sandbox = await sandboxes.create({ lifetimeMs: 10 * 60_000 });
try {
  await sandbox.writeFile('index.js', 'console.log(6 * 7)');
  const result = await sandbox.exec(['node', 'index.js']);
  console.log(result.exitCode, result.stdout); // 0 '42\n'
} finally {
  await sandbox.release();
}

This is not Code Mode, which runs one model-written JavaScript program against your tools. A sandbox is a whole machine for an agent to work in: installing packages, running tests, building things.

#Limits

createSandboxes(provider, options) holds every sandbox from a provider to the same limits.

sandboxes.close() releases every sandbox still alive and refuses new ones.

#A sandbox

sandboxes.create(options) takes lifetimeMs (required), and optionally network, env (variables every command sees), ports, cpus, memoryMiB, image (the provider's image or template) and labels. The provider ends the sandbox when its lifetime is over, if release() did not end it first; after that every call fails with a SandboxError whose reason is gone.

Paths are absolute, or relative to the sandbox's workdir. exec resolves with the exit code, stdout and stderr as text, truncated and durationMs. A command still running at its timeout is stopped, with every process it started, and resolves with timedOut: true and no exit code. Cancelling with signal stops it too, and fails with CANCELLED.

import { createSandboxes } from 'mayura/sandbox';
import { dockerSandboxes } from 'mayura/sandbox/docker';

const sandboxes = createSandboxes(dockerSandboxes({ image: 'node:24-slim' }), { maxSandboxes: 1, maxLifetimeMs: 600_000 });
const sandbox = await sandboxes.create({ lifetimeMs: 600_000, env: { NODE_ENV: 'test' } });

const tests = await sandbox.exec(['npm', 'test'], { cwd: 'app', timeoutMs: 120_000 });
if (tests.timedOut) console.log('The tests took too long.');
else if (tests.exitCode !== 0) console.log(tests.stderr);
await sandbox.release();

What each provider supports beyond commands and files is in sandbox.features: stdin, ports, desktop, and the network kinds it can enforce. Asking for something a provider does not support fails with INVALID_INPUT before anything is created.

#Network

A sandbox reaches nothing by default. Its network is one of:

• 'none': no network at all. The default.
• 'all': the internet, and serving ports.
• { allow: ['registry.npmjs.org', '*.github.com'] }: only these domains, on providers that filter by domain.

Each kind other than 'none' must be listed in the network option of createSandboxes; asking for one that is not fails with PERMISSION_DENIED. So permission to reach the network is given once, where the sandboxes are set up, never by whoever creates a sandbox.

A provider that cannot keep sandboxes off the network (Fly Machines, for one) leaves 'none' out of its features.network. Its sandboxes are then created only with 'all', listed in createSandboxes and asked for; the default fails with INVALID_INPUT instead of making a sandbox that is online when you expect it offline.

import { createSandboxes } from 'mayura/sandbox';
import { dockerSandboxes } from 'mayura/sandbox/docker';

const sandboxes = createSandboxes(dockerSandboxes({ image: 'node:24-slim' }), {
  maxSandboxes: 2, maxLifetimeMs: 600_000, network: ['none', 'all'],
});
const server = await sandboxes.create({ lifetimeMs: 600_000, network: 'all', ports: [3000] });
await server.exec(['sh', '-c', 'setsid nohup npx serve -l 3000 . >/dev/null 2>&1 < /dev/null &']);
console.log(await server.url(3000));

Start a process that must outlive its command, such as a server, with setsid as above: some providers (Daytona, for one) end everything in a command's process group when the command returns.

#Tools for agents

sandboxTools(sandbox, { name }) makes tools that let an agent work in a sandbox. Only reading is on by default; each further power is enabled by its own option and needs its own permission.

Other options: execTimeoutMs (5 minutes by default), execCostMicros (what one command costs against the run's budget; 0 by default), maxOutputBytes (32 KiB of each stream returned to the model, the middle of longer output left out), maxReadBytes and maxWriteBytes.

Most agents need a sandbox of their own for each run, so one run's files never reach another. sandboxPerRun creates the run's sandbox the first time one of its tools needs it; release it when the run ends, from an onFinally lifecycle hook:

import { defineHook } from 'mayura';
import { createSandboxes, sandboxPerRun, sandboxTools } from 'mayura/sandbox';
import { dockerSandboxes } from 'mayura/sandbox/docker';

const sandboxes = createSandboxes(dockerSandboxes({ image: 'node:24-slim' }), { maxSandboxes: 8, maxLifetimeMs: 3_600_000 });
const perRun = sandboxPerRun(sandboxes, ({ runId }) => ({ lifetimeMs: 3_600_000, labels: { run: runId } }));

const tools = sandboxTools(perRun.source, { name: 'workspace', exec: true, write: true });
const releaseSandbox = defineHook({
  id: 'sandbox.release', version: '1', stage: 'onFinally',
  handler: async (_event, context) => { await perRun.release(context.runId); },
});

Grant the run tool:workspace.exec, sandbox:workspace:exec and the tool's effect (and the same for each other tool), as for any tool. exec, write, remove and the desktop actions (click, scroll, type, key) have write effects and need effect:write; read, list, url and screenshot need effect:read.

#Docker

dockerSandboxes(options) from mayura/sandbox/docker runs each sandbox as a container on this machine. It runs on Node, and needs Docker. Each container is locked down:

• no network unless 'all' was allowed and asked for, and then ports published on 127.0.0.1 only;
• every Linux capability dropped, and no privilege escalation (no-new-privileges);
• a non-root user (1000:1000 by default);
• the image's file system read-only, with an in-memory working directory and /tmp;
• bounded CPUs, memory (with no swap) and processes;
• removed when released, and when its lifetime is over.

Images are never pulled: a sandbox with an image that is not on the machine fails with INVALID_CONFIG. An image needs a POSIX shell, sleep and the usual tools, from BusyBox or coreutils, as Alpine, Debian and most language images have. Environment variables reach commands through a file inside the container, so their values are not in the container's configuration or on the host's command lines.

#Providers

#Writing a provider

A provider implements SandboxProvider: its id, features, workdir and maxLifetimeMs, and create, which resolves with a SandboxBackend. createSandboxes checks every path, size and option before calling the provider, and everything the provider returns before the caller sees it. A provider maps failures to SandboxError (use sandboxHttpFailure(status) for HTTP statuses) without the provider's own text, and stops a command and everything it started when exec's signal aborts.

A provider whose API only runs commands can do the rest with sandboxScripts from mayura/sandbox: shell scripts that read, list and remove files, and stop every process of a command by a tag in its environment (sandboxScripts.kill), with parseSandboxListing for the listing.

A provider whose API runs only short commands and answers with text can get the whole contract from commandSandboxBackend(id, transport, release): give it a transport whose run(command, { stdin, signal }) runs a short command and resolves with its exit code and stdout. Commands then start in the background and are polled to their end, output and files move as base64 in chunks (inside the command line when the transport takes no standard input), and a timeout or cancellation stops every process a command started. Fly Machines and AgentCore are built on it.

sandboxConformance from mayura/sandbox/testing runs the contract against a real sandbox:

import { describe, expect, it } from 'vitest';
import { createSandboxes } from 'mayura/sandbox';
import { dockerSandboxes } from 'mayura/sandbox/docker';
import { sandboxConformance } from 'mayura/sandbox/testing';

describe('my sandbox provider', async () => {
  const sandboxes = createSandboxes(dockerSandboxes({ image: 'alpine:3.22' }), { maxSandboxes: 1, maxLifetimeMs: 600_000 });
  const sandbox = await sandboxes.create({ lifetimeMs: 600_000 });
  for (const test of sandboxConformance) it(test.name, async () => { expect(await test.run({ sandbox })).toBe('passed'); });
});