execlaw

Self-hosted Rust agent framework with persistent memory, hook-based plugins, tools, and skills. Bare metal best metal. All inference runs on operator hardware.

Documentation

What ships today

• Control plane (Rust binary): event log + scheduler + plugin host + container manager + outbox relay + axum server + SQLCipher vault.
• Per-conversation runner containers: stateless against the log, stateless OpenAI-compatible client to local inference (vLLM / OpenArc / Whisper / Kokoro).
• Trust ladder + Rule of Two: Controller / Delegated / KnownTrusted / KnownLimited / UnknownPending / Blocked with cold-contact escalation, signed approval-token JWTs, sideband HITL.
• HMAC-chained event log: every committed row is tamper-evident; replay rebuilds state deterministically.
• Outbox + idempotency: framework-minted (conversation_id, turn_seq, tool_call_ordinal) keys, retries with backoff, dead-letter queue.
• Plugin framework (12 in-tree plugins — see Plugins shipped): script-tier (Rhai) + subprocess-tier (JSON-RPC), full manifest schema (tools / transports / identity providers / OAuth / sidecars / admin routes / webhook routes / UI panels / skills).
• Five shipped transports: Signal (signal-cli sidecar), WhatsApp (wuzapi sidecar), Slack (multi-workspace Socket Mode OAuth), Discord (multi-guild Gateway WebSocket), SMS (Android-gateway WebSocket).
• HTTP integrations: Google Apps (Gmail/Calendar/Contacts/Tasks/Drive in one OAuth), Google Places, Open-Meteo (key-less weather), Yahoo Finance (market data), Pushover.
• Research subsystem: deep-research plan/gather/synthesize pipeline with retention and per-phase event flow.
• SPA: chat-first sidebar, pinned Control thread (every controller-channel message collapses here), token streaming, approval queue, per-plugin admin panels, settings. i18n out of the box — 8 languages (EN / ES / FR / DE / IT / NL / PL / PT), browser-locale auto-detection on first run, language switcher in the setup wizard and persisted to localStorage. See Internationalisation (i18n) below.
• Native desktop bundles for all three desktops — .app/.dmg on macOS (Apple Silicon, SMAppService LaunchAgent), NSIS .exe on Windows (SCM service), .deb on Linux (systemd --user unit). Each ships a tray icon, the bundled control plane, and the same SPA on 127.0.0.1:3031. See Desktop installations below and docs/desktop-installations.md for the full cross-OS reference.

See docs/architecture.md §18 for the full milestone breakdown.

Plugins shipped

All 12 in-tree plugins ship as ZIPs under dist/ and install via the SPA's Settings → Plugins page (or POST /api/admin/plugins/install). Source under plugins/.

Tools, host-side built-ins, and the manifest schema are documented in docs/plugins.md. Chart rendering (chart.render) is a host-side built-in as of 2026-05-15 — it was previously inside open-meteo.

---

Internationalisation (i18n)

The SPA ships with eight languages built in:

How language gets picked. On first load the SPA checks localStorage["execlaw.preferred-language"]; if absent it falls back to navigator.language (when that's one of the supported codes) and finally to English. The setup wizard renders a compact globe-icon language switcher in the top-right corner so the operator can flip languages before they've committed to anything — the choice is persisted to localStorage and applied to every subsequent visit.

How translations work in the code. English defaults live inline in the React source via t("namespace.key", "English default string") — the same pattern as the upstream business website. Other locale bundles (web/src/locales/<lang>.json) are lazily code-split: only the active language's JSON is fetched. When a key is missing from a non-English bundle, t() silently falls back to the English default, so a partial translation can ship without surfacing empty UI strings. {{var}}-style interpolation works the same on the English path and the translated path.

Implementation reference. Core: web/src/i18n/index.ts (i18next bootstrap, lazy-loader registry, t() helper, useT() / useCurrentLanguage() React hooks). UI: web/src/i18n/LanguageSwitcher.tsx. Locale bundles: web/src/locales/.

Adding a new language. Add the ISO code to SUPPORTED_LANGUAGES in web/src/i18n/index.ts, register a lazy-loader entry in localeLoaders, add an OPTIONS row in web/src/i18n/LanguageSwitcher.tsx, and drop a web/src/locales/<code>.json keyed by the same namespace.key strings the JSX passes to t().

Not yet i18n-ized. Server-side strings (CLI output, log lines, plugin-author-facing error messages) are English-only. The translation surface is the operator-facing SPA UI; the operator talks to the agent in whatever language they want — the LLM handles that end on its own.

---

Minimum requirements

execlaw is self-hosted by design — there is no SaaS tier, no cloud fallback, and no plan for one. Inference happens on the operator's own hardware against a local OpenAI-compatible endpoint. The hardware floor is set by the LLM you choose to run, not by execlaw itself.

Operating system

The CLI path uses the service-manager crate. For desktop installs the recommended path is the OS-native bundle — .app on Apple Silicon, NSIS .exe on Windows, .deb on Debian-family Linux — each registers the background service through that OS's native API (SMAppService / SCM / systemd --user) so install + uninstall stay self-contained. See Desktop installations. CLI install still works on headless servers (and is the only path on non-Debian Linux and Intel Macs).

GPU / inference acceleration

You need a GPU capable of running the LLM you intend to use. The in-tree default is Qwen3.5-27B-AWQ (~14 GB VRAM for weights + a working KV cache budget for ~8K-token contexts). Two acceleration paths are supported out-of-the-box:

CPU-only inference is technically possible via llama.cpp or similar sidecars, but at 27B-AWQ the latency makes the agent loop unusable. Smaller models (Qwen2.5-7B-AWQ at ~5 GB VRAM) work on consumer 8 GB cards if you accept the quality drop — operators swap the model spec in Settings → Backends.

The voice subsystem (Whisper STT, Kokoro TTS) runs alongside the LLM — add ~1-2 GB VRAM headroom if you want both on the same card. Operators with a second GPU (typical Intel-Arc-for-voice + NVIDIA-for-LLM split) can pin each backend per-card via Settings → Runners.

Memory + disk

Required runtime dependencies

• Docker — required for per-conversation runner containers, plugin sidecars (signal-cli, wuzapi, …), and managed-mode inference backends. The control plane talks to the local Docker daemon via the standard socket (/var/run/docker.sock on Linux/macOS, \\.\pipe\docker_engine on Windows). Docker Desktop is fine on macOS/Windows; Docker Engine or Podman-with-the-docker-socket-shim works on Linux. Without Docker the agent loop runs text-only with the runner in-process; sidecars and managed inference are unavailable — usable for plain chat but not for the bridged-transport plugins. Apple Silicon exception: Docker Desktop on a Mac runs Linux in a microVM with no Metal access, so containerised inference on M-series GPUs falls back to CPU and is unusable. execlaw spawns Ollama as a native subprocess on Apple Silicon instead — see docs/setup-mac.md. Docker is still needed for the bridged-transport sidecars (signal-cli, wuzapi). Cross-OS Ollama support: the native-subprocess path also works on Linux and Windows when ollama is installed on the host. The setup wizard discovers it automatically and offers it as an alternative serving method alongside vLLM / OpenVINO. See docs/ollama.md for when to pick which.
• An NVIDIA or Intel GPU driver stack matching the inference path you choose — CUDA 12+ runtime for NVIDIA, the OpenVINO drivers for Intel. Both are normally installed alongside the GPU; execlaw doctor prints what's missing.
• An OS keyring backend for vault master-key storage — Keychain on macOS, Credential Manager on Windows, Secret Service / KWallet on Linux. The vault falls back to ~/.execlaw/master.key if the keyring is unavailable; the file fallback is also the durable sink on Windows where Credential Manager has documented drift issues (see docs/security.md §5).

Build-from-source dependencies

Only required if you're compiling rather than installing a release binary:

• Rust 1.85+ (edition 2024). MSRV documented at the workspace root; CI runs against current stable.
• Node.js 20+ for the SPA build (web/).
• A C toolchain for the SQLite bundling: gcc/clang on Linux/macOS, MSVC on Windows.
• Strawberry Perl 5.32+ on Windows only if you build the production sqlcipher feature (vendored OpenSSL needs Perl). Not required for default bundled-sqlite-plain dev builds.

execlaw doctor runs preflight checks for all of the above and prints remediation pointers per platform.

---

Quick start (production)

execlaw's control plane runs as a host service on bare metal — systemd on Linux, launchd on macOS, the Service Control Manager on Windows. The control plane itself is a single native binary; Docker is required only for the things the control plane spawns out (per- conversation runner containers, plugin sidecars like signal-cli / wuzapi, managed-mode inference backends). On a host without Docker the agent loop still works text-only with the runner running in-process; sidecars and managed inference are unavailable.

One-shot install

cargo install --path crates/cli   # or `cargo build --release` and copy the binary
execlaw install                   # migrate DB → register service → start it
curl http://127.0.0.1:3031/api/health    # → {"status":"ok"}
open  http://127.0.0.1:3031/api/docs     # Swagger + AsyncAPI

execlaw install registers a per-user service by default. Add --system for a system-wide install (root / Administrator). On Windows the Service Control Manager always runs system-level, so --system is implied.

Desktop installations

For desktop hosts the recommended path is the OS-native bundle. Each one ships a tray / menu-bar icon plus the same bundled control plane, and each registers the background service through that OS's native API so install + uninstall stay self-contained. Full cross-OS reference: docs/desktop-installations.md.

macOS (Apple Silicon) — menu bar .app

Registers a LaunchAgent through Apple's modern SMAppService API, so dragging the .app to the Trash automatically removes the background service — no leftover plist in ~/Library/LaunchAgents/.

1. Download execlaw_<version>_aarch64.dmg from Releases.
2. Open .dmg → drag execlaw to /Applications.
3. First launch: right-click execlaw → Open (the build is unsigned, so a plain double-click hits Gatekeeper). macOS remembers the exception.
4. macOS surfaces Background Items Added the first time — that's SMAppService registering the LaunchAgent. Approve in System Settings → General → Login Items & Extensions if prompted (the tray's status row links you there).
5. Menu bar icon → Open execlaw → SPA loads on http://127.0.0.1:3031/. First-run wizard takes it from there.

The menu bar also exposes Restart service, Open data folder, View logs (log stream)…, and Uninstall execlaw… (the latter deregisters the LaunchAgent and optionally wipes ~/.execlaw/ before you drag the .app to Trash).

Windows 10 / 11 — NSIS .exe installer

Registers a Service Control Manager service running as LocalSystem so the control plane starts at boot.

1. Download execlaw_<version>_x64-setup.exe from Releases.
2. Run the installer; UAC fires (the SCM service install needs admin). NSIS's post-install hook calls execlaw.exe service install --system + service start --system.
3. SmartScreen warns "Windows protected your PC" on first run (unsigned installer) → More info → Run anyway.
4. Notification-area icon appears. Open execlaw opens a WebView2 window on http://127.0.0.1:3031/.

Uninstall via Settings → Apps → execlaw → Uninstall (NSIS's pre-uninstall hook stops + deregisters the service) or from the tray's Uninstall execlaw… (UAC → service uninstall).

Linux (Debian / Ubuntu / Mint / Pop_OS!) — .deb

Registers a systemd --user unit on first tray-app launch. No service registration happens at apt install time — apt's postinst runs as root, but systemd --user units must live in the operator's HOME to start under their UID.

1. Download execlaw_<version>_amd64.deb from Releases.
2. sudo apt install ./execlaw_<version>_amd64.deb.
3. Launch execlaw-tray from the application menu (or /usr/bin/execlaw-tray from a shell). The tray calls execlaw service install --user then service start --user.
4. SNI tray icon appears (Just Works on KDE Plasma, XFCE, MATE, Cinnamon, elementary OS; vanilla GNOME needs the AppIndicator and KStatusNotifierItem Support extension — Ubuntu bundles it since 22.04).
5. Open execlaw → webkit2gtk-4.1 window on http://127.0.0.1:3031/.

For boot-time start without an interactive login, run loginctl enable-linger $USER once. To uninstall cleanly: tray Uninstall execlaw… first (deregisters the user unit), then sudo apt remove execlaw for the program files.

Building from source

See docs/desktop-installations.md for the cross-OS architecture reference, docs/architecture.md for the broader desktop-wrapper design, and CONTRIBUTING.md → Cutting a release for the tag → GitHub Release flow.

Service lifecycle

cargo bootstrap, cargo start, cargo stop, cargo restart, cargo svc-status, and cargo doctor are convenience aliases that forward to the equivalent execlaw … invocations (see .cargo/config.toml).

Live logs

execlaw service status prints the right command for your platform.

First-run setup

curl -X POST http://127.0.0.1:3031/api/setup \
  -H 'content-type: application/json' \
  -d '{"admin_password":"pick-something-longer"}'

The SPA at http://127.0.0.1:3031/ will guide you through the rest (backend wizard, plugin install, personality, etc.).

---

Dev mode (hot-reload, full stack)

Two long-running processes give you a restart-free edit cycle for both the Rust server and the SPA.

One-time setup

# Rust file-watcher.
cargo install cargo-watch --locked

# SPA dependencies.
cd web && npm install

Run both terminals

# Terminal 1 — Rust hot-reload. cargo-watch rebuilds + restarts the
# binary on every .rs save. Wraps `cargo run -p execlaw -- serve`.
bash scripts/dev-server.sh         # POSIX / WSL / Git Bash on Windows
# or:
pwsh scripts/dev-server.ps1        # Windows PowerShell
# or, from inside web/:
cd web && npm run dev:server       # alias for the bash script

# Terminal 2 — SPA hot-reload. Vite HMR; proxies /api → :3031.
cd web && npm run dev

Open http://127.0.0.1:5173/ — the SPA hits the Vite dev server, which proxies API calls to the cargo-watch'd Rust binary on :3031. Editing a .tsx file triggers a Vite HMR push; editing a .rs file triggers a cargo build + binary restart and the next API call hits the new code (typically <5s for incremental edits).

The dev server, the installed production service, and the Vite proxy all default to 127.0.0.1:3031 — there's no port-swizzling between modes. Override for one-off testing:

EXECLAW_DEV_BIND=127.0.0.1:9000 bash scripts/dev-server.sh
VITE_API_TARGET=http://127.0.0.1:9000 npm run dev

Useful npm scripts (in web/)

Rust dev cheatsheet

# Plaintext SQLite path (fast; skips OpenSSL vendoring).
cargo test --workspace
cargo run -p execlaw -- doctor

# Full SQLCipher path (production build).
cargo test --workspace --no-default-features -F execlaw-core/sqlcipher

# Replay a turn — reconstructs the exact prompt, capability set,
# policy decision, and committed events for one conversation/seq.
cargo run -p execlaw -- replay <conversation_id> --at <seq>

Requires Rust 1.85+ (edition 2024). Bare-metal targets: x86_64-unknown-linux-gnu, x86_64-pc-windows-msvc, aarch64-apple-darwin. Intel Macs (x86_64-apple-darwin) are explicitly not supported — the only macOS-specific code path that matters is Metal-accelerated inference via Ollama, which lives on Apple Silicon. Service registration on each supported target is handled by the service-manager crate.

Disk-space note

The Rust workspace's target/ directory grows quickly (40+ GB on a warm dev box). If cargo-watch rebuilds start failing with No space left on device, run cargo clean to reclaim.

---

Workspace layout

License

Apache License, Version 2.0 — see LICENSE and NOTICE.

Copyright (c) 2026 Justin Long.