Installation

locac is a single self-contained executable. Take it from a release, or build your own: either way you end up with one file and no sibling data directories.

A bash-compatible shell is required on every host. Tool execution and the OS sandbox run commands through it, and locac never falls back to cmd.exe or PowerShell for that. macOS and Linux have one already; on Windows install Git for Windows and see Windows notes.

Install a release

curl -fsSL https://locac.dev/install.sh | sh

irm https://locac.dev/install.ps1 | iex

Both scripts pick the archive for your OS and architecture, download the release's SHA256SUMS alongside it, and refuse to unpack an archive the checksum file does not vouch for. A release that publishes no SHA256SUMS is a hard failure, not a warning: this script is the supply chain, and "probably fine" is not a verification step. The check runs before the archive is extracted, because extraction is the first moment a download gets to decide what lands on disk. The binary is staged inside the destination directory and renamed into place, so an interrupted download never leaves a half-written file at the name you are about to run.

Neither script edits your shell profile or your PATH. They print the one line you need and stop.

Assets are compressed - a single-file Bun binary is around 116 MB and about a third of that on the wire. Each archive holds exactly one file, locac (or locac.exe), with no target suffix and no enclosing directory.

The format follows what the destination can already open: tar is present on every image that can run curl, while unzip is missing from most minimal ones, and Windows opens a .zip by double-click with nothing installed.

Bun has no Windows arm64 target, so arm64 Windows machines install the x64 build and run it under the OS emulation layer. To verify a download by hand instead, take the archive and SHA256SUMS from Releases and check it yourself:

sha256sum -c --ignore-missing SHA256SUMS
tar -xzf locac-linux-x64.tar.gz

Build from source

Requires Bun >= 1.3.0 and Git. Nothing else.

git clone https://github.com/Losec-io/locac.git
cd locac
bun install
bun run build:exe

build:exe compiles src/cli/main.ts with bun build --compile and writes:

Every piece of runtime data is embedded in that one file: the tree-sitter WASM grammars, the web dashboard assets, the bundled skills, and the platform's sandbox helper - the broker srt-win.exe on Windows, the apply-seccomp installer on Linux. Copy the single file wherever you want it.

Cross-compiling

Pass a Bun target triple to build for another platform. One host can cut every artifact:

bun run build:exe --target=bun-linux-x64      # -> dist/locac-linux-x64
bun run build:exe --target=bun-darwin-arm64   # -> dist/locac-darwin-arm64
bun run build:exe --target=bun-windows-x64    # -> dist/locac-windows-x64.exe

Cross-built artifacts are suffixed so a matrix writing into one dist/ cannot clobber itself; a plain build:exe keeps the unsuffixed name. Which sandbox helpers get embedded is decided by the target, not the host, so each artifact carries only its own platform's helpers and none of the others' weight.

Verify the build

locac selftest

  ✓ tree-sitter AST — 1 call site(s)
  ✓ bundled skills — srcwalk, variant, verify
  ✓ web dashboard assets — 52032 bytes embedded
  ✓ srt-win helper — 2987008 bytes at ~/.locac/bin/srt-win.exe
  · OS sandbox — os

selftest: OK

selftest exists because a compiled binary can fail in ways the source never does: a dependency that resolves an asset relative to its own module URL finds the virtual filesystem after --compile, so a broken asset is invisible from source and silently degrades the binary. The checks are:

• tree-sitter AST. Loads a grammar and parses a snippet. The hardest asset to keep working in a compiled exe.
• bundled skills. The srcwalk / verify / variant skills resolve and load.
• web dashboard assets. The HTML and JS for locac web are embedded.
• srt-win helper (Windows only). The sandbox broker was extracted under LOCAC_HOME. If this fails, the Windows sandbox silently never engages.
• apply-seccomp helper (Linux only). The seccomp installer was extracted under LOCAC_HOME and is executable, since bwrap execs that path. This check needs to exist more than the Windows one does: a missing broker drops the mode to direct, which the run header shouts about, while a missing seccomp filter leaves the mode reading os and quietly removes the AF_UNIX layer.

The last line is a note, not a check: it reports which sandbox mode this host actually gets (os or direct) and why, proven by running a no-op command through the sandbox. An unprovisioned sandbox is a fact about the host, not a broken build, so it never affects the exit code.

Exit code: 0 on OK, 1 on FAILED.

Put it on your PATH

The installers deliberately do not do this for you, and neither does the build. Pick where it goes.

On macOS and Linux, either add the install directory:

export PATH="$HOME/.locac/bin:$PATH"    # add to your shell profile to persist

or copy a source build somewhere already on it:

sudo install -m 755 dist/locac /usr/local/bin/locac
locac --help

On Windows, from PowerShell:

[Environment]::SetEnvironmentVariable(
  "Path", [Environment]::GetEnvironmentVariable('Path','User') + ";$HOME\.locac\bin", "User")

That reads and writes the User PATH specifically. Composing the new value from $env:Path instead would flatten the machine-wide entries into your user variable, so a later system change would stop reaching you. Open a new terminal afterwards: the change does not reach shells that are already running.

Sandbox prerequisites

Tool execution is confined by an OS-level sandbox. When the sandbox is unavailable the run falls back to direct mode, where commands still run but unconfined. Pass --require-sandbox to refuse to start in that case.

Linux needs all three of bwrap, socat and rg. Missing any one drops the host to direct:

sudo apt install bubblewrap socat ripgrep

macOS needs nothing installed: confinement uses the built-in sandbox-exec.

Windows needs a one-time provisioning step that creates the low-privilege sandbox account:

npx sandbox-runtime windows-install

On Ubuntu 24.04 and newer, unprivileged user namespaces are restricted by default, which can block the nested namespace bubblewrap needs. locac selftest reports the exact reason on the OS sandbox line, and that line is the authority rather than this page.

Windows notes

Windows is a first-class target, with two host-specific requirements:

1. A bash-compatible shell. Install Git for Windows and point locac at it, either per run or globally:

locac run "audit this repo" --shell-path "C:\Program Files\Git\bin\bash.exe"

Or set the LOCAC_SHELL environment variable, or the shellPath field in ~/.locac/config.json. locac auto-discovers a bash if one is on PATH; --shell-path is for when it is not.

2. The one-time sandbox install shown above. Under the Windows sandbox, target commands run as another user, a low-privilege account provisioned by that installer.

Running without building

For development you can skip the compile step entirely:

bun run src/cli/main.ts --help
bun run src/cli/main.ts run "audit this repo" --cwd /path/to/target

This is the same entry point, so behaviour is identical, but it resolves assets from the source tree rather than the embedded VFS, which is precisely the difference selftest exists to catch. Verify against the compiled binary before you trust a build.

Repository scripts

Next

Head to the Quickstart to configure a provider and run a first audit.