# Sandbox and limits

Programs run unrestricted until you pass a sandbox flag. `--sandbox` denies filesystem access and subprocesses; the
network stays allowed until you list hosts:

```bash
elide --sandbox --allow-read=. --allow-net=example.com run app.js
```

<img src="/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" />

> [!WARNING] Java and Kotlin are not sandboxed
> Elide currently runs Java and Kotlin programs on HotSpot, which the sandbox does not cover. `--sandbox` and the
> `--allow-*`, `--deny-*` and `--no-native` restrictions are refused before Java/Kotlin compilation or execution.

The sandbox covers programs run with `elide run`, `elide python`, `elide serve` and `elide <file>`. With `--sandbox`,
`--allow-read`, `--allow-write`, `--allow-net`, `--allow-run`, `--deny-net`, `--deny-run` or `--no-native`, everything
else that runs code or tools exits with code `2` before it starts:

- Java and Kotlin programs, Android apps, Pkl and Markdown documents, and project scripts run with `elide run`
- `elide serve` of a directory, which serves its files from the host
- `elide java`, `javac`, `kotlinc`, `jar`, `native-image` and the other JVM and native tools
- every other subcommand, such as `build`, `test`, `format`, `install`, `uv`, `dev`, `mcp` and `repl`, and a bare
  `elide` that opens the REPL

`elide help` and `elide info` ignore these flags. Grants that restrict nothing, such as `--allow-read --allow-write`
together or a bare `--allow-net` or `--allow-run`, are not refused.

The restrictions apply to the program, not to what you ask Elide to do for you. The program can always read the entry
file you name and list the names in its directory, even outside `--allow-read`; the other files in that directory stay
denied. These options act outside the program's grants:

- reading an `@file` argument list or an `--env-file`
- writing diagnostics: `--heap-dump`, `--jfr`, `--jitdump`, `--coverage`, and engine options set with `-D` or `--vm`,
  such as a log file
- sending telemetry to `--otel-endpoint`
- listening for a debugger on `--debugger-host`

The legacy capability flags coordinate filesystem operations made by restricted guest contexts. They do not
isolate the host process from other programs that can modify the same files. Keep granted directories private
from untrusted native processes; use an OS sandbox for that boundary. The stronger `sandboxed` and `isolated`
profiles remain unavailable and are refused rather than falling back to legacy restrictions.

## Allow file access

```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](/docs/wasm#directory-access). These grants apply to mapped directories, and a WASI open needs both read
and write access.

## Allow network and subprocesses

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

A subprocess runs with your own access, outside the sandbox, so `--sandbox`, `--allow-read` and `--allow-write` deny
every subprocess until `--allow-run` names the commands, or allows all of them when bare. `--deny-run` alone does not
allow any. Before 1.6.4, these flags left subprocesses allowed; add `--allow-run` to keep that.

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

## Threads and native access

| Program | Threads by default | Native access by default |
| --- | --- | --- |
| JavaScript, TypeScript | Not applicable: `node:worker_threads` workers run under every flag | Allowed |
| Python entry | Allowed | Allowed |
| Python entry with `--sandbox` or an `--allow-read`/`--allow-write` grant | Denied; add `--allow-threads` | Allowed |
| Python under `--interop` | Denied, even with `--allow-threads` | Allowed |

```python
# threads.py
import threading
out = []
t = threading.Thread(target=lambda: out.append("worker ran"))
t.start(); t.join()
print(out[0])
```

```bash
elide python threads.py                                         # worker ran
elide --sandbox --allow-read=. python threads.py                # Creating threads is not allowed.
elide --sandbox --allow-read=. --allow-threads python threads.py  # worker ran
```

`--no-native` denies native access. Python then lacks some features, such as `AF_UNIX` sockets
(`AttributeError: module 'socket' has no attribute 'AF_UNIX'`) and arbitrary signals, and starts more slowly.
`--allow-native` states the default explicitly; combining it with `--no-native` is a usage error (exit `2`).

## Python child processes

A Python program that runs `sys.executable`, as `multiprocessing`'s `spawn` start method and Metaflow do, starts
Elide's Python again with the same flags. The child sees the environment the program passed it (its `os.environ`
unless it passes `env`), so it needs no `--allow-env` of its own. Started through another program such as a shell, the
child keeps the restrictions but not the environment.

Under a restricted parent, the child runs only programs (`elide run`, `elide python`, `elide FILE`) whose file the
parent may read, in the parent's working directory or one it may read. Each of these exits with code `2`:

- other subcommands such as `java` or `uv`, a project run (`elide run` with no file) and script names
- a file outside the parent's `--allow-read`, or a working directory outside it other than the parent's own
- `@argfiles`, `--use-version`, `--env-file`, `--properties-file` and `--project`
- flags that write files, listen or connect on the host, such as `--heap-dump`, `--jfr`, `--jitdump`, `--coverage`,
  `--debugger`, `--otel-endpoint`, `--redirect-warnings` and `-D`/`-X` engine options
- a grant the parent lacks such as `--allow-read`, and a different `--sandbox` profile

The child ignores `ELIDE_*` and `OTEL_*` variables, `NODE_REDIRECT_WARNINGS` and `NODE_EXTRA_CA_CERTS` in its
environment, and loads no `.env`, `.properties` or `.elideversion` file.

Other programs the child or the parent starts are not sandboxed. Limit them with `--allow-run`. `--allow-run=elide`
permits only the running Elide binary, started through `sys.executable` or `process.execPath`, and no other file named
`elide`:

```bash
elide --sandbox --allow-read=. --allow-run=elide python app.py   # subprocesses are Elide's Python, reading only .
```

## Set limits

`--limit` applies to JavaScript and TypeScript programs. A value is a number, `0` to forbid, or `unlimited`, the
default. 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.

## Pick a profile

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

## Flags

| Flag | Effect |
| --- | --- |
| `--sandbox` | Deny filesystem access and subprocesses. The network stays 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. Needed under `--sandbox`. |
| `--deny-net=HOSTS` | Deny hosts even when allowed. |
| `--deny-run=CMDS` | Deny commands even when allowed. |
| `--allow-env[=NAMES]` | Pass the listed host environment variables, or all of them, to Python's `os.environ`, and let `elide.pkl` read them. `process.env` is unchanged. |
| `--allow-threads` | Allow Python threads in a sandbox. |
| `--allow-native` | Allow native access (the default). |
| `--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.

An `elide.pkl` or `package.json` script, or a `node_modules/.bin` command, run with `elide run NAME` is a host command
and cannot be sandboxed. With `--sandbox`, `--allow-read`, `--allow-write`, `--allow-net`, `--allow-run`, `--deny-net`,
`--deny-run` or `--no-native` it exits with code `2`.

## Samples

- [Sandboxed subprocess](/docs/code-samples#sandboxed-subprocess)
- [Limit workers](/docs/code-samples#limit-workers)
- [Request limits](/docs/code-samples#request-limits)
