> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safedep.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Stop Install Scripts from Reading Your Secrets

> Run package installs in the PMG sandbox to block credential files, secret environment variables, and the SSH agent.

An install script runs with your user rights. It can read your SSH keys, your cloud credentials, and every secret in your shell environment. The PMG sandbox runs the package manager and its scripts under an operating system policy that blocks these reads.

The sandbox:

* Blocks reads and writes of credential files such as `.env`, `.ssh`, `.aws`, and `.netrc`.
* Removes known secret variables, such as `AWS_SECRET_ACCESS_KEY` and `GITHUB_TOKEN`, from the package manager environment.
* Blocks host unix sockets, such as the SSH agent and the Docker daemon.
* Blocks writes to Git hooks and Git config.

> [!NOTE]
>
> The sandbox runs on macOS (Seatbelt) and Linux (Landlock on kernel 5.13 or later, or Bubblewrap). It does not run on Windows. The sandbox is off by default.

## Turn on the sandbox

**1. Enable the sandbox**

```bash theme={null}
pmg config set sandbox.enabled true
```

**2. Check the sandbox driver**

```bash theme={null}
pmg sandbox doctor
```

The output shows the driver that PMG uses on this machine. On Ubuntu 23.10 and later, follow the AppArmor fix that the doctor shows.

**3. Install a package**

```bash theme={null}
pmg npm install express
```

PMG applies the sandbox to install commands. Other commands, such as `npm run build`, run without it.

To try the sandbox for one command without a config change, add `--sandbox`:

```bash theme={null}
pmg --sandbox npm install express
```

## Fix a denied operation

A denied operation fails in the package manager with a permission error. PMG records the denials that the sandbox driver reports. The Landlock and Bubblewrap drivers do not report every denial. See the [sandbox debug commands](https://github.com/safedep/pmg/blob/main/docs/sandbox.md#sandbox-debug-commands).

**1. Find the cause**

```bash theme={null}
pmg sandbox explain --last
```

The output names the denied path, command, or variable, and the command that allows it.

**2. Allow it for one run**

```bash theme={null}
pmg --sandbox-allow write=./.gitignore npx create-next-app@latest
```

The types are `read`, `write`, `exec`, `net-connect`, `net-bind`, `env`, and `preset`. For a removed variable, use `env=NAME`.

**3. Keep it for this repository**

```bash theme={null}
pmg sandbox allow --last
```

PMG saves the allowance in a project overlay outside the repository, and applies it on every run in this repository. A cloned repository cannot add an overlay. Show the overlay with `pmg sandbox project show`.

> [!WARNING]
>
> `pmg sandbox allow` refuses a credential file, such as `.env` or `.npmrc`, unless you add `--force`. A package that reads the file during an install can send it to an attacker.

## Use a preset for a known tool

A preset is a set of allowances for one tool, such as a dev server. Use a preset instead of allowing each denial:

```bash theme={null}
pmg sandbox preset list
pmg sandbox allow preset=vite
```

A preset only adds allowances. It cannot remove a deny rule or open a credential file.

## With SafeDep Cloud

The sandbox is free in PMG. With SafeDep Cloud, you see the sandbox allowances on every endpoint of your team. PMG records each `--sandbox-allow` and each project allowance as a sandbox override event. This query lists the endpoints that use an override, and the number of sessions on each:

```sql theme={null}
SELECT endpoints.identifier,
       COUNT(DISTINCT package_guard_events.invocation_id) AS sessions
FROM package_guard_events
JOIN endpoints ON endpoints.id = package_guard_events.invocation_id
WHERE package_guard_events.event_type = 'PMG_EVENT_TYPE_SANDBOX_OVERRIDE'
GROUP BY endpoints.identifier
```

> [!NOTE]
>
> This section needs the SafeDep Cloud Team or Enterprise plan, with PMG [connected to your tenant](/governance/cloud/endpoint-hub/package-guard). See [pricing](https://safedep.io/pricing).

## Next steps

For the profile format, custom profiles, and platform limits, see the [sandbox documentation](https://github.com/safedep/pmg/blob/main/docs/sandbox.md) in the PMG repository.

> **[Limit the Hosts a Package Install Can Reach](/package-security/pmg/network-policy)**
>
> Allow only the registries an install needs.

> **[Sandbox Your AI Coding Agent](/ai-security/sandbox-coding-agents)**
>
> Run Claude Code, Codex, or Pi in the PMG sandbox.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.