The release is a prebuilt binary with the UI inside it, so there is nothing to compile. What you need is a machine that can reach an OpenAI-compatible endpoint — a local gateway, a hosted API, or a model server you already run.

Prerequisites

Linux, x86_64 — the target the release is built for.
curl and sh — the installer is a POSIX shell script.
systemd for the service install. Without it, use --no-systemd and run the binary yourself.
No Rust and no Node. Those are only needed to build from source, which is a contributor workflow, not an install path.

That is the whole list. There is no cloud account, no signup and no telemetry: the binary talks to the endpoint you give it and to nothing else.

Install

Download the installer, then run it. It fetches the release tarball, verifies it against the release’s SHA256SUMS, and only then unpacks and installs — nothing is piped from the network into a shell.

shell


        
        curl -fsSLO https://raw.githubusercontent.com/karutoil/karucode/main/packaging/install.sh
      
        
        sudo sh install.sh --workspace /srv/karucode/workspace

It installs /usr/local/bin/karucode, writes a hardened systemd unit plus a drop-in with this machine’s paths, enables it at boot, starts it, and waits until /api/health answers before reporting success. The previous binary is kept as karucode.old; a failed start restores it. --dry-run prints the whole plan without changing anything.

No root? Same script.

sh install.sh --prefix "$HOME/.local" --no-systemd puts the binary in ~/.local/bin and leaves the service alone. Run it in the foreground with karucode --workspace /path/to/project.

First run

Open http://127.0.0.1:8787. The first-run wizard takes the rest in six steps: the model endpoint (with a live “Test connection”), appearance, approval mode, and a password or passkey.

The endpoint is a prefix, not a full URL: karucode appends /chat/completions to it. Point it at the /v1 root of your gateway, not at a single endpoint. The same three values can be set from the environment instead — KARUCODE_BASE_URL, KARUCODE_API_KEY (it falls back to OPENAI_API_KEY) and KARUCODE_MODEL — which is what a sealed deployment does.

The default approval mode is ask: shell commands and file writes wait for you. You can answer allow-once, allow-for-session or deny, and every decision is recorded. A password or passkey is optional on loopback, and required before you expose the UI.

Installer flags

Every flag is optional except that the systemd path needs root and a prefix it can write. sh install.sh --help prints the full list.

Flag	Meaning
--workspace DIR	Create this directory and use it as the first project.
--version VER	Release to install instead of the latest, e.g. 0.1.0.
--prefix DIR	Install the binary to DIR/bin. Default /usr/local.
--no-systemd	Binary only: no unit, no service user, no root needed.
--data-dir DIR	SQLite database and plugin data. Default ~/.local/share/karucode.
--port N	Listen port. Default 8787.
--dry-run	Print every action and change nothing. Works without root.

Try it on a real bug

Point it at a project you already have — a checkout with a failing test is the honest first task. In the UI, add the project, start a session and describe the bug. If you want a known case, examples/demo-app in the repository is a dependency-free Node project with a planted bug: add() subtracts instead of adding, so two of its five tests fail.

shell


        $
        karucode --workspace examples/demo-app

Then give it this prompt:

Run the tests, find the failing cases, fix the bug in src/math.js, and re-run the tests to prove it passes.

Watch what it does: it runs the tests, reads the failures, opens the file, edits one function, and runs the tests again. You will be asked before the first command and before the write. That loop — run, read, change, prove — is the whole product.

Providers that work

Anything that speaks the OpenAI chat-completions API with streaming tool calls. These are the shapes people point it at most often:

Provider	KARUCODE_BASE_URL
LiteLLM proxy	`http://127.0.0.1:4000/v1`
vLLM	`http://127.0.0.1:8000/v1`
Ollama	`http://127.0.0.1:11434/v1`
llama.cpp server	`http://127.0.0.1:8080/v1`
OpenRouter	`https://openrouter.ai/api/v1`

With Ollama, tool calling depends on the model you pull — a model that cannot emit tool calls cannot drive the agent. Provider profiles are install-wide; a session can pin its own model, provider and reasoning effort. See Configuration.

Upgrades

Re-running the installer is the upgrade — it fetches the latest release and restarts the service:

shell


        $
        sudo sh install.sh

Your workspace, service user, port and data directory live in a drop-in (/etc/systemd/system/karucode.service.d/10-install.conf) that every run rewrites from what it finds, so an upgrade cannot lose the paths the service needs. Pin a version with --version 0.1.0, or leave it on latest.

Exposing it

Not for a public interface as-is

karucode binds to 127.0.0.1 by default and refuses a non-loopback bind unless KARUCODE_AUTH_TOKEN is set (16+ characters) or sign-in is enabled with a password or passkey. Sign-in is strongly recommended before the UI leaves loopback. There is no TLS in the binary: put a reverse proxy in front of it for remote access.

Shell commands run as the server user and are not sandboxed. If the workspace is untrusted, run the whole thing inside a container or a VM. Security is the full version of this page.