---
description: Configure the light-run runner service that light-process needs to execute containers. Use when the user is setting up a fresh install, hits "LIGHT_RUN_URL not set", or wants to choose between local dev and prod two-process mode.
---

# Setup light-run

light-process never talks to Docker directly. It delegates all container work to a `light-run` HTTP service. You **must** have light-run running and reachable before `light run` or `light serve` will start.

## Two boot modes

`light serve` picks the mode automatically from `LIGHT_RUN_URL`.

### All-in-one (local dev)

`LIGHT_RUN_URL` unset.

```bash
light serve
```

Behavior:
- Spawns `light-run` as a child process on `--runner-port` (default 3001)
- Generates a token, waits for `/health`, then starts the orchestrator
- Runner stdout/stderr prefixed `[runner]`
- SIGINT/SIGTERM cleans up the child
- If the binary is missing, prints `Run: npm i -g @enixcode/light-run    (or: light serve --install)` and exits 1
- `--install` runs `npm i -g` synchronously before continuing

### Two-process (prod)

`LIGHT_RUN_URL` set. No spawn, no auto-install.

```bash
# terminal 1 - runner (needs Docker on the same host)
light-run serve --token $(openssl rand -hex 32) --port 3001

# terminal 2 - orchestrator
export LIGHT_RUN_URL=http://localhost:3001
export LIGHT_RUN_TOKEN=<same token>
light serve
```

## Environment variables

| Var | Required | Purpose |
|---|---|---|
| `LIGHT_RUN_URL` | recommended | `http://host:port` of the light-run service |
| `LIGHT_RUN_TOKEN` | optional | Bearer token if light-run was started with `--token` |
| `LP_API_KEY` | optional | Enables Bearer auth on light-process REST server (`/api/*` routes) |

## Install

```bash
npm install -g light-process @enixcode/light-run
```

Requires Node 20+ and Docker on the machine running `light-run`. light-process itself only needs Node.

## Health check

```bash
light doctor
```

Checks `LIGHT_RUN_URL` (required) and Docker / gVisor / GPU on the current host (informational - Docker must actually be on the light-run host).

## Troubleshooting

- **`light run` / `light serve` refuses to start** - `LIGHT_RUN_URL` is unset in two-process mode. Set it or unset to switch to all-in-one.
- **400 from light-run** - usually empty `files`. `Node.setCode()` / `addHelper()` / `loadDirectory()` always populate files; a bare `new Node({...})` in SDK mode would break.
- **Payload too large** - default body limit is 10 MiB. Bump `LIGHT_RUN_BODY_LIMIT` on the light-run side.
- **Cryptic timeout** - `node.timeout = 0` means "no timeout" -> light-run uses light-runner's 20-min default.