# Sandbox and Limits

> Restrict filesystem, network, subprocess and native access, and limit resources and run time.

Programs run unrestricted until you pass a sandbox flag.

<img src="https://elide.help/assets/demos/sandbox.gif" alt="elide --sandbox — filesystem, network and subprocess policy" width="1591" height="546" loading="lazy" decoding="async" class="rounded-lg border border-border my-6 w-full" />

| Flag | Effect |
| --- | --- |
| `--sandbox` | Deny filesystem access. Network and subprocesses stay allowed. |
| `--allow-read[=PATHS]` | Allow reads everywhere, or at the listed paths. Implies `--sandbox`. |
| `--allow-write[=PATHS]` | Allow writes everywhere, or at the listed paths. Implies `--sandbox`. |
| `--fs-audit` | Log each filesystem decision to stderr. |
| `--allow-net[=HOSTS]` | Allow all network access, or only the listed hosts (`HOST` or `HOST:PORT`). |
| `--allow-run[=CMDS]` | Allow all subprocesses, or only the listed commands. |
| `--deny-net=HOSTS` | Deny hosts even when allowed. |
| `--deny-run=CMDS` | Deny commands even when allowed. |
| `--allow-env[=NAMES]` | Limit which environment variables `elide.pkl` may read. Guest `process.env` is unchanged. |
| `--no-native` | Deny native access. |
| `--limit=workers=N` | Limit live workers; exceeding it throws `ERR_WORKER_LIMIT`. |
| `--limit=fds=N` | Limit open `node:fs` handles; exceeding it throws `EMFILE`. |
| `--max-mem=SIZE` | Limit the heap size; exceeding it is an out-of-memory error with a nonzero exit. |
| `--timeout=DURATION` | Stop the program after `DURATION` with exit `124`. |

Lists are comma-separated. `--deny-net` and `--deny-run` need the `=` form.

## Filesystem

```bash
elide --allow-read=. --fs-audit run app.js
```

```text
[elide.fs] allow read open hello.txt
[elide.fs] DENY  write open out.txt
```

A denied access fails like a protected file: `EACCES: permission denied, open 'hello.txt'`. Relative paths resolve
from the working directory.

WASI programs cannot access host directories until you map one with `WasiMapDirs`; see
[WebAssembly](https://elide.help/docs/wasm#directory-access). These grants apply to mapped directories, and a WASI open needs both read
and write access.

## Network and subprocesses

```bash
elide --allow-net=localhost --allow-run=ls run app.js
```

A denied call names the grant it needs:

```text
TypeError: fetch to 'example.com:443' is not permitted; grant it with --allow-net=example.com
Error: spawn of 'echo' is not permitted; grant it with --allow-run=echo
```

A `--deny-*` match reports `denied by --deny-net` or `denied by --deny-run`. Policy checks the command that runs, so a
shell invocation is checked as `sh`. Spawn with `execFileSync` from `node:child_process`.

## Native access

`--no-native` denies native access. Python then lacks some features, such as `AF_UNIX` sockets and arbitrary signals,
and starts more slowly.

## Limits

`--limit` applies to JavaScript and TypeScript programs. Use `0` to forbid, or `unlimited`; omitted limits are
unlimited. Other names, languages or commands are usage errors.

```bash
elide --limit=workers=4 --limit=fds=128 --max-mem=512m --timeout=30s run app.js
```

Workers inherit their parent's grants. These flags do not isolate the process from a native crash.

## Profiles

`--sandbox=trusted` is the default profile. `--sandbox=sandboxed` and `--sandbox=isolated` are unavailable and exit
with code `2`.