Configuration

Environment variables, PATH for apps launched from a GUI, and pnpm build approval.

The sandbox has two settings beyond the directory: env and homeDirectory. This page covers env and the two situations where you will reach for it. homeDirectory is in Working directory and $HOME.

Environment variables

Commands the sandbox runs get your process environment, a HOME of the sandbox’s own, plus whatever you pass as env:

const sandboxSession = await createLocalSandboxSession({
	workingDirectory: '/path/to/your/repo',
	env: { GIT_AUTHOR_NAME: 'Agent' },
});

env adds to process.env, it does not replace it. When the same name appears more than once, the last of these wins:

1. The pnpm build-approval defaults, described below.
2. process.env.
3. HOME, set to homeDirectory. By default this is a directory under the OS temp dir, not your real home; see Working directory and $HOME.
4. The env option, so env.HOME beats homeDirectory.
5. The env of a single run or spawn call, which is how the harness passes its per-process values.

The same env applies to every command, including the ones the harness runs to install and start its bridge, and to a restricted() view of the session.

PATH for GUI-launched apps

An app launched from the Finder or Dock inherits a bare PATH that usually misses where node and pnpm live. The harness needs both: it installs the CLI with pnpm install and runs its bridge with node. Start from a terminal and you never notice; launch the packaged app and the first createSession can fail with a command-not-found error.

Set PATH yourself:

import { homedir } from 'node:os';

const sandboxSession = await createLocalSandboxSession({
	workingDirectory: '/path/to/your/repo',
	env: {
		PATH: [
			`${homedir()}/.local/bin`,
			'/opt/homebrew/bin',
			'/usr/local/bin',
			'/usr/bin',
			'/bin',
		].join(':'),
	},
});

Put the directories that hold node and pnpm on your machine first. The package never widens PATH for you, so what you set is exactly what the agent gets.

pnpm build approval

Since pnpm 10, a dependency’s build script (such as postinstall) is blocked until someone runs pnpm approve-builds. A harness installing its CLI for the first time has no terminal to answer that prompt, so every command the sandbox runs carries pnpm’s dangerouslyAllowAllBuilds setting, switched on through three environment variables:

const PNPM_BUILD_APPROVAL_ENV = {
	npm_config_dangerously_allow_all_builds: 'true',
	pnpm_config_dangerously_allow_all_builds: 'true',
	PNPM_CONFIG_DANGEROUSLY_ALLOW_ALL_BUILDS: 'true',
};

pnpm’s prefix for these variables changed across versions, which is why there are three.

To turn it off, set all three to 'false' in env. A harness whose first-run install needs an unapproved build script will then fail until you approve it yourself.

env: {
	npm_config_dangerously_allow_all_builds: 'false',
	pnpm_config_dangerously_allow_all_builds: 'false',
	PNPM_CONFIG_DANGEROUSLY_ALLOW_ALL_BUILDS: 'false',
},