HLVM Guide

HLVM is a vendor-neutral AI runtime. It gives you one continuous assistant, a shell, one-shot agent commands, automatic model/engine routing, optional user-managed local models, MCP and browser tools, and HQL in one runtime.

Build the current pre-release

No public binary release or installer is published yet. Authorized contributors can build from source:

mkdir hlvm-dev && cd hlvm-dev
git clone https://github.com/hlvm-dev/hql.git
git clone https://github.com/hlvm-dev/hlvm.git
cd hlvm
make build
./hlvm --version

See Build and the full build guide for details. The examples below assume hlvm is on PATH; otherwise invoke the local build as ./hlvm.

First Run

Ask one question through the real runtime path:

hlvm ask "summarize the main points of REST in five bullets"

A fresh configuration starts at auto. HLVM resolves one usable route before the turn from the models and external engines that are installed, authenticated, and allowed by policy. Starting HLVM does not install or start a local model. If no route is ready, inspect hlvm model list, sign in to a native engine or cloud provider. An existing Ollama installation is also discovered when available. hlvm model set auto restores automatic selection. Clients and GUI surfaces always talk to the HLVM runtime host on 127.0.0.1:11435 regardless of which route runs the turn.

If the first run fails:

hlvm doctor
hlvm model list
hlvm ask --verbose "hello"

Use the focused next action printed by doctor; HLVM has no broad repair step.

Interactive Shell

hlvm

By default, HLVM works from the current directory, like Codex and Claude Code. Use hlvm -C <dir> (or hlvm --cd <dir>) to start in another project, and use hlvm --global when you want the explicit global assistant.

The shell routes input by shape:

Examples:

hlvm> (+ 1 2)
3
hlvm> (map inc [1 2 3])
(2 3 4)
hlvm> explain this directory structure

The footer shows the active working directory. Use /path to inspect it, /path <dir> to change it for future turns, or /path --global to return to global scope.

Use hlvm --debug when you need internal trace rows.

One-Shot Agent Tasks

Use hlvm ask when you want a result from the shell without entering the REPL.

hlvm ask "find any .ts file in the current dir that uses XMLHttpRequest"
hlvm -C ~/dev/my-project ask "find any .ts file that uses XMLHttpRequest"
hlvm ask --permission-mode readOnly "audit this repo for broken docs links"
hlvm ask --attach ./screenshot.png "explain the UI issue"

Useful options:

See Ask and CLI Reference.

Models

List routes and keep automatic selection enabled:

hlvm model list
hlvm model set auto

To pin one exact route, copy its current ID from hlvm model list:

hlvm model set '<exact-ready-route>'

An existing Ollama installation remains an optional route:

hlvm model pull ollama/qwen3:8b
hlvm model set ollama/qwen3:8b

Cloud providers use keys:

hlvm model key list
hlvm model key set openai

HLVM never bundles, installs, starts, or repairs Ollama and does not inject a local model as an Auto fallback.

See Models.

Agents

Agents are named profiles for repeated work.

hlvm agent list
hlvm agent add reviewer
hlvm agent identity reviewer --emoji R --color "#8A3FFC"
hlvm ask --agent reviewer "review the current diff"

Keep agent descriptions specific and tool permissions narrow when possible.

See Agents.

MCP Tools

Add tools through Model Context Protocol servers:

hlvm mcp add github -- npx -y @modelcontextprotocol/server-github
hlvm mcp add docs https://example.com/mcp --transport http
hlvm mcp list

Remote OAuth servers use:

hlvm mcp login docs

See MCP.

Browser Bridge

Install the native browser bridge when you want browser-backed tools:

hlvm browser setup
hlvm browser status
hlvm browser verify

Restart Chrome after setup if it was already open. See Browser Bridge.

Runtime Server

Start the local runtime server for GUI clients or local integrations:

hlvm serve

Default runtime host:

http://127.0.0.1:11435

Core API entry point:

curl -X POST http://127.0.0.1:11435/api/chat \
  -H "Content-Type: application/json" \
  -d '{"mode":"eval","messages":[{"role":"user","content":"(+ 1 2)"}]}'

See Runtime Server.

HQL Language Tools

HQL is a separate language toolchain:

echo '(print "hello")' > hello.hql
hql run hello.hql

Use HQL for Lisp-shaped code that compiles to JavaScript and TypeScript. Install the standalone toolchain from the HQL project; it is not installed by the HLVM source build.

See the HQL docs.

Common Mistakes

• Expecting HLVM to install Ollama or a model. Ollama is optional BYO software; model pulls are explicit.
• Using hlvm ask without --verbose when diagnosing startup or routing failures. Verbose mode gives the actionable trace.
• Treating named agents as magic. They are editable profiles; inspect the file and permissions.
• Forgetting to run hlvm browser status after browser setup.
• Using raw .hql files directly in Node or the browser without compiling or using a HQL-aware toolchain.

Next Steps

• Build
• First Run
• Ask
• CLI Reference