Quickstart

This walks from a fresh install to a first finding. It assumes locac is on your PATH; see Installation if it is not.

1. Create the config file

locac config init

This writes a template to ~/.locac/config.json (or $LOCAC_HOME/config.json) with tightened file permissions, because the next thing you do is paste an API key into it:

{
  "provider": "anthropic",
  "model": "claude-opus-4-8",
  "budget": { "maxTokens": 500000 }
}

If the file already exists, config init leaves it alone and tells you so. To find it later:

locac config path

The config file always lives under LOCAC_HOME, never inside the repository you are auditing. That repository is untrusted input; a config read from it would let the target choose your provider, your base URL, and your API key.

2. Point it at a provider

The simplest path is to leave the key out of the config file entirely and let locac read it from the provider's environment variable:

export ANTHROPIC_API_KEY=sk-ant-...

Every built-in provider has one: OPENAI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, DEEPSEEK_API_KEY, ZAI_API_KEY, and so on. The Providers page has the full list.

If you prefer the config file, you can reference the variable rather than inlining the secret:

{
  "provider": "anthropic",
  "model": "claude-opus-4-8",
  "apiKey": "$ANTHROPIC_API_KEY"
}

Both "$VAR" and "${VAR}" are expanded at run time. An unset variable fails loudly rather than sending an empty key.

Check what locac resolved:

locac config show

config show prints the effective settings, and that includes any literal apiKey you put in the file. Do not paste its output into a bug report.

3. A read-only recon pass

Before letting an agent run commands in an unfamiliar repository, do a pass with an explicit tool allow-list. Nothing here can write, execute, or reach the network:

cd /path/to/target
locac run "map the attack surface: entry points, routes, parsers, auth boundaries" \
  --tools "read,search,find,ls,outline,code_search,glob" \
  --print

--print gives plain streaming output instead of the TUI, which is what you want when you are piping or reading a log. Drop it for the interactive interface.

The allow-list applies to subagents too. submit_report is never removable, because a subagent has to be able to answer its parent.

4. A full audit

cd /path/to/target
locac run "audit the HTTP request handling path for injection and deserialization bugs" \
  --require-sandbox \
  --auto

Two flags are doing the real work here:

--require-sandbox refuses to start unless the OS sandbox is actually available. Without it, a host missing its sandbox dependencies runs unconfined and only says so in the header.
--auto is guardian mode: read-only shell commands are auto-approved, everything else fail-closed. The alternatives are no flag at all (an interactive prompt in the TUI, blocked everywhere else) and --yes (aliased as --allow-all), which approves dangerous tools outright.

On a real terminal this opens the fullscreen TUI. Use --inline for the scrollback renderer, or --print for no TUI at all.

Bound the run while you are still calibrating:

locac run "..." --max-tool-calls 200 --max-wall-clock-ms 900000

Exit code 2 means a budget cap stopped the run. Resume it with a bigger budget rather than starting over.

5. Let it drive itself

--goal turns the run into an autopilot that keeps working toward an objective until it is done or a cap fires:

locac run --goal "find and prove one High-or-better RCE in the upload handler" --auto

Or explore first and commit later. --plan runs a read-only exploration phase that ends with a proposed plan; resuming the session without --plan executes it:

locac run "audit the auth module" --plan
locac resume <session-id> "go ahead"

The agent calls report_findings before it finishes, so the report is in the transcript. Everything is also persisted to a per-project SQLite database at ~/.locac/projects/<name>-<hash>/sessions.db, outside the target repository.

List what you have:

locac sessions
locac -c                       # continue the most-recent session
locac resume <session-id> "now check the sibling handlers"

Or open the dashboard, which renders sessions, transcripts, and the findings table with severity, CWE, CVSS and the cited evidence:

locac web

It binds 127.0.0.1:4173 by default. Binding a non-loopback address is refused unless you have configured a dashboard password and JWT secret. The dashboard can launch bash, so it is never exposed unauthenticated.

What to expect

A good run produces few findings. Each High or Critical finding had to cite an execution artifact whose checked assertion passed for that location and survive a 2-of-3 cross-verification quorum, so the pipeline discards a lot of plausible-looking candidates on purpose. If you get zero findings and a clear account of what was ruled out and why, that is a successful run.

Configuration covers every field of config.json: per-project overrides, custom endpoints, budgets, and the precedence rules that decide which layer wins. Then Running an audit documents locac run end to end, and Sessions and forking covers everything a finished run leaves behind.