Skip to main content
Use this guide after the quickstart. For the full CLI and configuration reference, see Laser operations.

Start an engagement

From a Laser checkout with bin/ on your PATH, launch against an authorized target:
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. 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.
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

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

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:
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:
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:
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:
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:
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:
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:
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: installation and common usage.
  • Operations: configuration, capture limits, recovery, and troubleshooting.
  • Mission control: UI controls, Docker profiles, and opt-in Docker lifecycle tests.
  • Architecture: supervisor, evidence, and source ownership.
Last modified on November 17, 2026