HLVM Guide

HLVM is a local AI runtime. It gives you a shell, a one-shot agent command, managed local models, MCP tools, browser bridge tools, and the HQL language in one install.

Install

macOS and Linux:

curl -fsSL https://hlvm.dev/install.sh | sh
hlvm --version

Windows users should use the Windows installer from the Download menu, then open a new terminal and run hlvm --version.

See Install for verification and repair steps.

First Run

Ask one question through the real runtime path:

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

The first AI call may prepare the managed local runtime and download the selected local model. The local AI endpoint is owned by HLVM on 127.0.0.1:11439. Clients and GUI surfaces talk to the runtime host on 127.0.0.1:11435.

If the first run fails:

hlvm doctor
hlvm repair
hlvm ask --verbose "hello"

Interactive Shell

hlvm

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

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 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, pull, and set models:

hlvm model list
hlvm model pull ollama/gemma4:12b
hlvm model set ollama/gemma4:12b

Cloud providers use keys:

hlvm model key list
hlvm model key set openai

The default local model tier map is source-owned. The current map selects gemma4:12b for hosts with at least 16 GiB RAM and gemma4:e2b below that.

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 ships with HLVM:

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

Use HQL for Lisp-shaped code that compiles to JavaScript and TypeScript.

See the HQL docs.

Common Mistakes

• Starting system Ollama on 11434 to bypass a local model issue. Fix the managed runtime path instead.
• 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

• Install
• First Run
• Ask
• CLI Reference