Building and Troubleshooting

Achilles is a technical preview and fully open source, so building it yourself is a supported path, not an escape hatch. This page collects prerequisites, build commands, and the troubleshooting drill.

Installers

Download desktop installers at achilles.sh or from GitHub Releases. The floating stable tag always tracks the latest build:

Platform	Artifact
Windows x64	AchillesSetup.exe (CUDA variant: AchillesSetup-cuda.exe)
macOS Apple Silicon	Achilles-arm64.dmg
macOS Intel	Achilles-intel.dmg
Linux	.deb, .rpm, .flatpak

Installers are built on GitHub-hosted runners and are unsigned. Windows SmartScreen and macOS Gatekeeper will warn, which is expected for a technical preview. If you would rather not bypass those prompts, build from source (below) or configure your own signing.

Build from source

Prerequisites

• Rust (see the rust-version key in the root Cargo.toml)
• C/C++ toolchain (MSVC Build Tools on Windows)
• Node.js + pnpm (Hermit can provide these)
• Git

Quick path: start-desktop

From the repo root (Git Bash on Windows):

./start-desktop.sh

Or double-click start-desktop.cmd on Windows. The first run compiles the CLI, which takes several minutes. Later runs reuse the built binary unless you pass --rebuild. --help lists --debug, --skip-build, and --full.

When the window opens: pick a model if onboarding asks, then Findings - Choose workspace - pick a folder (or examples/achilles-scan-fixture) - Scan.

Hermit and the CLI

Hermit (recommended) activates the pinned toolchains:

source ./bin/activate-hermit
cargo build --release

Just recipes

With just installed:

just run-ui        # release CLI, then Electron
just run-ui-only   # UI only, CLI binary already in place

Desktop directly

cd ui/desktop
pnpm install
pnpm run start-gui

The desktop shell launches the bundled CLI binary over ACP.

Python-oriented install guidance lives in requirement-guidance.html in the repo root.

Tests

The repo's own verification commands, and a good check for your environment after building:

cargo test
cargo fmt
cargo clippy --all-targets -- -D warnings
cd ui/desktop && pnpm run typecheck && pnpm test

App will not start

Check these before filing an issue:

1. Confirm the CLI binary was built: cargo build --release.
2. On Windows, use Git Bash for Hermit / start-desktop.sh, and make sure MSVC Build Tools are installed for Rust.
3. Your pnpm version must match the engines field in ui/desktop/package.json.

Keychain and secrets

If configure cannot store API keys, your OS keyring is probably unavailable (headless machines, some Linux desktops). Set provider keys as environment variables instead - for example OPENAI_API_KEY, ANTHROPIC_API_KEY - and run configure again. To keep two environments isolated while testing, use the app's config-root environment variable to redirect the config directory.

Diagnostics

In an active chat, use the diagnostics control in the toolbar. It downloads a JSON bundle (diagnostics_<session_id>.json) containing OS, app version, enabled extensions, provider/model, and recent logs.

CLI equivalent:

achilles session diagnostics --session-id <session_id>

Report a bug

Use Settings - App - Help and feedback, or the diagnostics' file-an-issue shortcut. When opening an issue in kineticquant/achilles-harness, include:

• OS and version
• Achilles version
• Enabled extensions and provider/model
• The diagnostics JSON bundle

Command-line quickstart

Skip the desktop entirely on a compute box:

git clone https://github.com/kineticquant/achilles-harness
cd achilles-harness
./start-desktop.sh --skip-build   # or: cargo build --release
./target/release/achilles appsec scan --path examples/achilles-scan-fixture
./target/release/achilles appsec query --path examples/achilles-scan-fixture

Then wire the findings rail or MCP tools into your editor as described on the MCP, Skills, and Recipes page.