---
title: Configuration
description: Environment variables, PATH for apps launched from a GUI, and pnpm build approval.
sidebar:
  order: 4
---

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](/working-directory#choose-it-with-homedirectory).

## Environment variables

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

```ts
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](#pnpm-build-approval).
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](/working-directory#where-harness-state-goes).
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()`](/sessions-and-processes#restricted-view) 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:

```ts
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:

```ts
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.

:::warning
The agent's own shell commands inherit this environment. A `pnpm install` the agent runs in your repo runs dependency build scripts without asking.
:::

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.

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