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

# Developer guide

> Launch, monitor, and configure Laser engagements

Use this guide after the [quickstart](https://developers.reflection.ai/laser-quickstart.md). For the full CLI and configuration reference, see [Laser operations](https://github.com/reflectionai/laser/blob/main/docs/operations.md).

## Start an engagement

From a Laser checkout with `bin/` on your `PATH`, launch against an authorized target:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
laser "$HOME/engagements/local-review" \
  --target http://127.0.0.1:8101/ \
  --mode redteam --objective report \
  --session laser-review \
  --task "Assess the authorized local application and report supported findings."
```

Autonomous host execution requires Mirror, Python 3, Bash, cURL, `readlink -f`, tmux, and a Reflection API key in `REFLECTION_API_KEY` or `~/.mirror/reflection_api_key`. The launcher installs Laser's extension and skills into the workspace; there is no separate extension-install step.

Run `laser` without arguments in a terminal for guided setup. Omit `--task` for an interactive Mirror session, or use `laser --help` for all options. Autonomous startup waits up to 60 seconds for confirmed task acceptance (`LASER_STARTUP_TIMEOUT` overrides this); if startup is unconfirmed, inspect the session before retrying.

| Option | Use |
| - | - |
| `--target URL\|HOST`, `--domain DOMAIN` | Add authorized assets; repeat as needed. |
| `--out-of-scope ITEM` | Exclude an asset. |
| `--mode ctf\|redteam\|src` | Select instructions and tools; CLI default: `redteam`. |
| `--objective TEXT`, `--objectives N` | Set the objective and required count; default count: 1. |
| `--task TEXT`, `--message TEXT` | Start an autonomous task and append instructions. `--message` requires `--task`. |
| `--session NAME` | Choose a unique tmux session; default: `laser-main`. |
| `--approval auto\|approve` | Set tool approval policy; default: `auto`. |
| `--model ID`, `--base-url URL` | Pin a model or OpenAI-compatible endpoint. |

Without an explicit model, Laser uses `LASER_MODEL` or selects from the endpoint's model list. A pinned endpoint must answer the launcher's authenticated `/models` probe. Supply a suitable API key through `REFLECTION_API_KEY`; the launcher requires a nonempty value even for local endpoints. The resolved endpoint and model also configure the supervisor and workers.

> [!WARNING]
>
> Test only authorized assets. A URL target authorizes its host across ports and paths; URL exclusions also apply to the host and its subdomains. `http_capture` and `fanout_probe` enforce scope and check redirects, but arbitrary shell traffic is not gated. `browser_probe` checks only its initial URL. Use an independently isolated environment when these boundaries matter.

## Set an objective

| Mode | Default objective | Completion behavior |
| - | - | - |
| `ctf` | `flag` | Counts distinct flags that pass format checks or receive explicit format confirmation; with an [external judge](https://github.com/reflectionai/laser/blob/main/docs/operations.md#flag-judging), only accepted flags count. `--objectives N` sets the required count. |
| `redteam` | `getshell` | Counts recorded `goal:shell` graph nodes. |
| `src` | `report` | Requires a supervisor assessment of the findings and coverage. |

Override the default with `--objective`. Custom objective text does not create a custom evaluator: report/custom objectives require assessment, and a report file alone does not satisfy them. Put detailed instructions in `--task`.

`src` is bug-bounty-style testing, not a source-code auditing mode. The separate `source-review` skill supports source-assisted investigation when code is available. `flag_report` is available only in CTF mode. The setup wizard offers `ctf`; the explicit CLI defaults to `redteam`.

## Web UI

1. From the Laser checkout on the engagement host, start the server in a terminal with your model credentials configured:

   ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
   python3 webui/laser_webui.py --root "$HOME/engagements" \
     --launch-root "$HOME/laser-web-runs" --port 8875
   ```

2. Leave that terminal running and open `http://127.0.0.1:8875` on the same machine.

3. Choose **New engagement**, enter a unique name, target, and task, then choose **Host** or a configured **Docker** profile. Set the mode, objective, and worker limits, then click **Launch engagement**. **Live** shows startup and the running terminal.

`--root` discovers existing workspaces; `--workspace /path/to/engagement` pins one run. `--launch-root` provides the directory for new engagements and enables session controls. Without it, the browser is read-only.

The server has no login; keep it bound to loopback.

Host uses the installed Mirror runtime; Docker uses an administrator-defined [profile](#docker-execution-profiles). Each launch gets a fresh workspace and tmux session. Names are unique across managed launches and discovered workspaces, ignoring case and repeated whitespace; failed and stopped names remain reserved.

| View or control | Use |
| - | - |
| **Overview** | See the recorded outcome, pending reviews, and evidence issues. Select an activity interval to inspect its records. |
| **Live** | Read the terminal snapshot and startup/runtime state. Updates arrive every five seconds. |
| **Send input** | Click the terminal to focus input. Enter sends to the main Mirror pane; Shift+Enter adds a line. Drafts and scroll position survive refreshes. |
| **Interrupt agent** | Send Mirror's Escape key. This is separate from stopping the engagement. |
| **Stop engagement** | End the engagement and its workers; see [Stop a run](#stop-a-run) for cleanup and control boundaries. |
| **Evidence / Findings** | Inspect captured support, compare two captures, and review a finding's reproduction and rationale. |
| **Attack graph** | Follow recorded relationships or explicit evidence references; **Path from target** isolates one shortest recorded route. |

The terminal is a refreshed snapshot with input, not a full terminal emulator. Input does not silently reopen a supervisor stop; give an explicit continuation request.

Inside Mirror, `/laser` expands the native panel and `/laser-brief` prints its cached decision brief. For command-line monitoring:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
laser-status "$HOME/engagements/local-review" --watch 10
laser-status "$HOME/engagements/local-review" --json
tmux attach -t laser-review
```

Run these separately as needed. Detach from tmux with **Ctrl+B**, then **D**; the run continues. Activity age and stale worker heartbeats are signals to inspect, not proof of a stuck model or dead process. Recorded objectives, supervisor stops, and process liveness are separate. See [Mission control](https://github.com/reflectionai/laser/blob/main/docs/mission-control.md) for detailed UI behavior.

## Worker delegation

Workers are separate Mirror sessions sharing the engagement's scope and ledger. They cannot spawn more workers or control the supervisor loop. The executor can delegate independent work, and completed worker reports return to the executor and supervisor.

The defaults are **3 concurrent workers** and **8 total**. These are ceilings, not a request to spawn that many immediately. In New engagement, set **Maximum concurrent workers** and, under **Options**, **Total worker budget**; zero concurrent workers disables spawning.

**Automatically add workers when stalled** lets the harness start workers under the supervisor's stalled-progress policy. It is on by default for web launches and off for CLI launches. Turning it off still lets the executor delegate within the budgets. An explicit server value of `LASER_SUPERVISOR_SPAWN=0` or an empty value disables the web default.

For CLI launches, set configuration before running `laser`:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
export LASER_MAX_WORKERS=3
export LASER_MAX_WORKERS_TOTAL=8
export LASER_SUPERVISOR_SPAWN=1
```

Host and Docker launches pass these settings explicitly, independently of an existing tmux server's environment. A completed worker retains its concurrent slot until session exit is confirmed; unknown liveness does not free capacity. All created workers still count toward the total budget.

Other useful settings are `LASER_MAX_PLANS` (initial supervisor cap, default 40), `LASER_TURN_SECONDS` (watchdog threshold without a completed supervisor checkpoint, default 420 seconds), and `LASER_AUTHOR` (`deferred`, `1` for immediate authoring, or `0` for manual). With `LASER_MISSION_SECONDS` set and a valid mission clock, reaching the plan cap before 80% of the mission slows reviews instead of stopping. The watcher can prompt idle sessions or interrupt an overlong turn; it respects drafts and pending approvals. See [operations](https://github.com/reflectionai/laser/blob/main/docs/operations.md#monitoring-and-budgets) for all settings.

## Evidence and reports

Laser automatically saves committed native tool/task results as hashed artifacts, with session and worker provenance. User messages and assistant prose are excluded. Capturing output preserves an observation; it does not establish impact or create a finding automatically.

`http_capture` and `fanout_probe` save structured HTTP evidence. Non-bare Docker launches also attempt to start a proxy for clients that honor proxy environment variables; `LASER_TRAFFIC_PROXY_DISABLE=1` opts out. Ordinary host launches do not enable it. HTTPS CONNECT traffic retains metadata only. Partial transfers, oversized-output notices, and storage failures remain visible as capture gaps.

The main artifacts under the workspace's `.laser/` directory are:

| Path | Contents |
| - | - |
| `facts.jsonl`, `traffic/`, `evidence/` | Observations, captured exchanges, and saved artifacts. |
| `graph.json`, `findings.json` | Recorded relationships, finding claims, and review support. |
| `plans.json`, `workers/` | Supervisor decisions and worker records. |
| `reports/` | Engagement/finding reports and the self-contained `graph.html`; prior revisions stay in `reports/history/`. |
| `closeout.json` | Recording completeness and unresolved issues, separate from objective achievement. |
| `launches/`, `timings.jsonl` | Launch provenance and local tool durations. |

A finding review records an **agent verdict with saved support**, not independent reproduction. Legacy `verified` records without support remain visible as reviews lacking evidence. OWASP categories and CVSS v3.1 scores describe findings; they do not validate them.

Graph links are recorded relationships, not inferred from traffic volume or nearby timestamps. `finding_report` creates or binds a vulnerability node; attack edges still need explicit recording. A sparse graph can mean relationships are missing. Inspect support before treating a recorded route as a successful attack chain.

Finding intake writes a report scaffold immediately. Model-written prose is deferred by default: ask the agent to call `report_author` for pending findings, review the draft, and use `report_generate` for the engagement report. At a terminal decision, the harness also generates a deterministic report and records closeout status. A report can exist while evidence recording is incomplete; prose alone cannot resolve missing support. Inspect incomplete-closeout issues before delivering results.

Evidence can contain credentials and sensitive target data. List previews redact common credential patterns; original captures retain their saved contents. Review artifacts before sharing them. The state files are experimental formats, not a versioned public API.

## Continue a stopped run

Ask the agent to continue with specific instructions. Its `resume_run` tool records the request and can add targets/domains you explicitly authorize. Each resume adds 20 plans, up to five resumes. Workers cannot reopen a run.

A workspace retains its locked scope. Conflicting mode, objective, count, or scope arguments are rejected; use a fresh workspace for a substantially new engagement. Updating the checkout does not replace code in a running session. A later launch refreshes installed extensions, but the launcher refuses to reprovision a workspace that still has a live session.

## Docker setup

The [quickstart](https://developers.reflection.ai/laser-quickstart.md) puts only the target in Docker. The following setup also runs Mirror and its tools in a separate agent container. Laser supplies the agent recipe and web controller; targets, isolated networks, and a restricted model gateway must already exist.

### Build the agent image

Use a **Linux x86-64 host** with Docker running, Mirror installed as a `uv` tool, and mise Python **3.12.13**. Build as a non-root user with the standard locations:

* Mirror: `$HOME/.local/share/uv/tools/mirror`.
* Python: `$HOME/.local/share/mise/installs/python/3.12.13`.

The recipe copies those installations into Ubuntu 24.04 at their absolute paths. It cannot reuse a macOS installation; a root-owned runtime would be hidden by the engagement mount over `/root`.

From the Laser source checkout with `bin/` on `PATH`:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
docker info
uv tool dir
mise where python@3.12.13
laser --build-image
```

This builds **`laser-agent:7`** and runs an in-container dependency check. The build needs internet access for packages/tools. Rebuild after changing the recipe or host Mirror installation. For a custom tag:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
laser --build-image --tag laser-agent:dev
export LASER_AGENT_IMAGE=laser-agent:dev
```

### Agent sandbox

Prepare an authorized target reachable on a Docker network with both `Internal=true` and `com.docker.network.bridge.gateway_mode_ipv4=isolated`. The network must also reach a restricted model gateway at **`http://model-gateway:8080/v1`**. Provider credentials stay in the gateway; only its per-engagement credential enters the agent.

The controller needs Python, tmux, and Docker CLI. It does not need host Mirror or a provider key. An ordinary bridge network or `--base-url` cannot replace the sandbox requirements.

For CLI execution, supply `LASER_DOCKER_NETWORK`, `LASER_MODEL`, and `LASER_CELL_TOKEN` from your deployment, then launch:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
: "${LASER_CELL_TOKEN:?Set the engagement credential from your gateway}"
export LASER_CELL_TOKEN

laser "$HOME/engagements/laser-docker-demo" \
  --sandbox \
  --docker-network "${LASER_DOCKER_NETWORK:?Set the engagement network name}" \
  --agent-name laser-agent-demo \
  --sandbox-gateway http://model-gateway:8080/v1 \
  --model "${LASER_MODEL:?Set the gateway model ID}" \
  --session laser-docker-demo \
  --target http://target:80/ \
  --mode ctf --objective flag \
  --task "Capture the flag from the authorized lab target."
```

Use the target's address **inside the engagement network**; `127.0.0.1` inside the agent refers to that container. Choose unique workspace, session, and container names. The launcher mounts the workspace at `/eng`, keeps evidence on the host, drops Linux capabilities, and limits the agent to 2 CPUs, 4 GB of memory, and 256 processes. Image checks verify dependencies, not model access or engagement isolation.

### Docker execution profiles

For browser launches, copy `containers/webui/docker-profiles.example.json` to a private path and fill in your deployment values:

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "profiles": {
    "lab": {
      "label": "Isolated lab",
      "image": "laser-agent:7",
      "network": "laser-lab",
      "gateway": "http://model-gateway:8080/v1",
      "model": "your-gateway-model",
      "token_env": "LASER_LAB_TOKEN"
    }
  }
}
```

`token_env` names a server environment variable holding the gateway credential. Export it through your usual secret configuration; keep the value out of the JSON, browser form, and command-line arguments. Then start the UI:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
python3 webui/laser_webui.py --launch-root "$HOME/laser-web-runs" \
  --docker-config /absolute/path/docker-profiles.json --port 8875
```

Choose **Docker** and a ready profile in New engagement. The profile fixes the model, image, network, and gateway; the form still controls scope and worker budgets. Profiles are read at startup. Invalid configuration fails startup, while missing images, networks, credentials, or daemon access appear as readiness reasons. The UI does not provision those resources.

The same Live input, interrupt, and stop controls apply to Docker launches.

### Run the controller in Docker

Build the controller image from the Laser source checkout:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
docker build -f containers/webui/Dockerfile -t laser-webui:local .
```

It contains the web UI and runtime control dependencies. Mirror runs in the separate agent image; agent builds and self-tests require the source checkout.

On a Linux Docker host, use host networking to keep the listener on loopback. Set the private profile path and export `LASER_LAB_TOKEN` first:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
LASER_RUNS="$HOME/laser-web-runs"
LASER_DOCKER_CONFIG="/absolute/path/docker-profiles.json"
mkdir -p "$LASER_RUNS"
LASER_RUNS="$(cd "$LASER_RUNS" && pwd -P)"
docker run --rm --init --name laser-webui --network host \
  --user "$(id -u):$(id -g)" \
  --group-add "$(stat -c %g /var/run/docker.sock)" \
  --env LASER_LAB_TOKEN \
  --mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \
  --mount "type=bind,src=$LASER_RUNS,dst=$LASER_RUNS" \
  --mount "type=bind,src=$LASER_DOCKER_CONFIG,dst=/etc/laser/docker-profiles.json,readonly" \
  laser-webui:local --launch-root "$LASER_RUNS" \
  --docker-config /etc/laser/docker-profiles.json --port 8875
```

The launch directory must have the **same absolute path inside the controller and on the Docker host** because the host daemon resolves the agent's bind mounts. Mount archive roots too if you want to browse them. Keep `--init` enabled to reap exited terminal processes.

The Docker socket gives the controller host-level Docker authority. Use a trusted operator environment. This recipe targets conventional Linux Docker, not Docker Desktop or bridge-port forwarding. Keep the gateway and network available while runs are active.

## Stop a run

Use **Stop engagement** in Live and read its result. It closes verified main/worker sessions and removes a managed Docker agent container, including unrecorded workers inside it. Refused or unresolved actions produce a partial result. Stop preserves the workspace but does not remove the target, gateway, or network.

For a CLI-launched container outside the web controller's managed launches:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
docker stop laser-agent-demo
docker logs laser-agent-demo
```

After saving any needed logs, remove the stopped agent with `docker rm laser-agent-demo` and close its remaining tmux session. Killing only the host tmux session does not reliably stop a Docker agent.

For a host CLI session, `tmux kill-session -t laser-review` closes the main session; inspect and close its worker sessions separately. Host processes detached from tracked sessions are outside web controls too. A supervisor stop or tmux detach does not guarantee process termination. Preserve your artifacts before shutting down the disposable lab, and avoid terminating unrelated workloads.

Remove the quickstart's target separately with `docker rm -f laser-demo`. Removing the target alone does not stop the agent.

## Development reference

Run the offline suite from the source checkout:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
./bin/laser-selftest
```

It uses the Mirror Python environment at `$HOME/.local/share/uv/tools/mirror`; set `MIRROR_VENV` to another environment root if needed. The suite uses temporary ledgers, fake CLIs, and a loopback server, without model calls. It checks harness behavior, not exploitation success.

For implementation and deployment details:

* [README](https://github.com/reflectionai/laser/blob/main/README.md): installation and common usage.
* [Operations](https://github.com/reflectionai/laser/blob/main/docs/operations.md): configuration, capture limits, recovery, and troubleshooting.
* [Mission control](https://github.com/reflectionai/laser/blob/main/docs/mission-control.md): UI controls, Docker profiles, and opt-in Docker lifecycle tests.
* [Architecture](https://github.com/reflectionai/laser/blob/main/docs/architecture.md): supervisor, evidence, and source ownership.
