Quickstart — your first hotl session
From nothing installed to a completed agent task. Every command is copy-runnable and paired with the output you should see; the why behind things lives in permissions-and-sandbox.md and configuration.md.
Preconditions:
- macOS, Linux, or Windows; a terminal; and
git. - On Windows,
gitis doubly worth having: Git for Windows ships the POSIXsh.exethat hotl’sbashtool runs commands in, and hotl finds it automatically. Without one,bashdrops out of the tool list and says so — the file tools keep working. - A model to talk to — one of: a local Ollama server, or an API key for any OpenAI-compatible endpoint. You do not need an Anthropic key for this tutorial.
mutates: this installs the hotl binary, creates config files under ~/.config/hotl/ and a session log under ~/.local/share/hotl/, and (in the last step) makes one approved edit in a git repo of your choosing. On Windows read those two paths as %LOCALAPPDATA%\hotl\config\ and %LOCALAPPDATA%\hotl\data\ throughout this page.
1. Install the binary
Section titled “1. Install the binary”Prebuilt, no toolchain needed:
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nrakochy/hotl/releases/latest/download/hotl-installer.sh | shOn Windows, from PowerShell:
irm https://github.com/nrakochy/hotl/releases/latest/download/hotl-installer.ps1 | iex(Or, with a Rust toolchain ≥ 1.88: cargo install hotl. Building from a checkout — cargo build --release -p hotl — works too; then substitute your target/release/hotl path for hotl below.)
(Or with Nix, flakes enabled: nix profile install github:nrakochy/hotl installs it, or nix run github:nrakochy/hotl runs it without installing — then substitute nix run github:nrakochy/hotl -- for hotl below. Nix builds from source, so the first build compiles the whole dependency tree; the prebuilt installer above is the fast path.)
Expected: the installer reports where it put hotl (usually ~/.cargo/bin). Open a fresh shell if needed, then confirm:
hotl --version2. Point it at a model
Section titled “2. Point it at a model”Pick the lines that match what you have, and run them in this shell:
# Local Ollama (nothing leaves your machine):export HOTL_MODEL=openai/llama3.1export HOTL_OPENAI_BASE_URL=http://localhost:11434/v1
# — or — a hosted OpenAI-compatible API:export HOTL_MODEL=openai/gpt-5export OPENAI_API_KEY=sk-your-key-hereThe value of HOTL_MODEL is always provider/model. openai/… covers every OpenAI-compatible endpoint, local or hosted.
Then, for this tutorial only, turn on per-action prompts so you see every decision the agent wants to make:
export HOTL_PERMISSIONS=ask(The out-of-the-box default is bypass: ordinary tool calls run without asking, under the sandbox floor. ask makes the gate visible, which is the point of a first session.)
3. Confirm the setup
Section titled “3. Confirm the setup”hotl doctorExpected — the provider line reads ok, and the sandbox line names a mechanism:
hotl 0.2.0 — doctor ok provider: llama3.1 selected (keys present) ok sandbox: enforced (seatbelt) ok config: none at /Users/you/.config/hotl/config.toml (defaults; run `hotl setup`) ok allow rules: none (every gated tool call asks) ok sessions: /Users/you/.local/share/hotl/sessions (writable) ok memory: none (create /Users/you/.config/hotl/memory/MEMORY.md to enable) ok secrets audit: no current secret values found in stored logsIf the provider line says FAIL, your HOTL_MODEL/key env vars aren’t set — redo step 2 in this same shell. Do not continue past a FAIL provider line.
4. Run one task
Section titled “4. Run one task”cd into any git repository — git diff is how you’ll check the edit — and start the agent:
hotlYou’ll see a banner and a ❯ prompt. Ask for something small and concrete — a typo fix, a comment, a rename:
fix the typo in README.mdThe agent reads freely, then asks before it edits — you’ll see a line like:
allow edit README.md? [y/N]Type y and enter. It applies the edit and reports what it changed. Confirm with git diff.
You’ve now seen the whole loop
Section titled “You’ve now seen the whole loop”Type a request → the agent reads freely → it asks before changing anything (in ask mode) → you approve per step. Reversing an edit is your own VCS’s job: git diff shows exactly what the agent touched, and git checkout puts it back. When you drop the HOTL_PERMISSIONS=ask from step 2, the default bypass mode silences the ordinary prompts but keeps everything else: the kernel sandbox floor on bash, always-ask protection on execute-later paths (git hooks, shell rc, Makefiles, agent-instruction files), and the full transcript of every auto-allowed call.
Next:
- Staying in
askmode but tired of approving trusted commands every time? → allow-rules in configuration.md. - Want to know exactly what the gate and sandbox protect (and what they don’t)? → permissions-and-sandbox.md.
- Running it in a script instead of interactively? → headless mode in configuration.md.
- Want
: fix the testsstraight from your shell prompt? → shell.md.
Not covered here: connecting MCP tool servers and the post-edit hooks feature (see configuration.md, stubs noted there).