Quickstart

This needs Node 20.10 or newer and nothing else. Docker, an API key and an account all make Husk better; none of them make it work.

You are going to do four things: find out what your machine can do, create a computer, drive it, and throw it away. If step one tells you something is missing, keep going — every capability in Husk degrades to something that still runs, and husk doctor always tells you which version of the product you are currently using.

One thing to read before you start: on the local provider Husk gives you process guardrails, not containment. What that means precisely is on the Security page. It is worth four minutes if anything sensitive lives on this machine.

1. Find out what this machine can do

npx -y @husk-ai/cli doctor

On a Windows laptop with Docker installed but not running, Ollama up, and no API keys, that prints:

Docker being down is a row in the table, not an error. Husk keeps going with the local provider and says so twice: once in the SELECTION block and once in WARNINGS. Reading the doctor report goes through it line by line.

2. Create a computer

npx -y @husk-ai/cli up scratch

The orientation block prints once per ~/.husk and never again. Delete that directory and it comes back.

Nothing is actually running inside the machine yet. up allocates the workspace and writes the record; the shell starts on the first exec.

3. Drive it

husk exec scratch -- 'uname -sr; echo hi > /work/a.txt; cat /work/a.txt; pwd'

husk exec streams stdout and stderr live and exits with the command's own exit code, so this behaves the way you expect:

husk exec scratch -- test -f /work/a.txt && echo present

Everything after -- belongs to the command, flags included.

4. Throw it away

husk rm scratch --yes

Then: a whole agent, for zero dollars

If husk doctor found an Ollama model, you can run a complete agent loop without an API key. Write a husk.yaml:

name: filecheck
description: Writes a file and reads it back.
model: local
persona: |
  You have a Linux computer. Use the shell to check things rather than guessing.
  Answer in one sentence.
tools: [computer, files]
limits:
  maxSteps: 6
  maxCostUsd: 0

husk run husk.yaml "Create /work/hi.txt containing the word banana, then tell me what it contains."

That transcript is unedited, and it shows two real things worth knowing before you build on this.

The loop runs up to four tool calls in parallel, in the order the model emitted them but not necessarily in that completion order. Here a 1.5B model asked to write and read the same file in one turn, and the read lost the race. A larger model sequences the two turns; a small one does not. The agent loop covers the concurrency rule.

The run cost nothing, and the footer says free rather than $0.0000, because the router knows a local model has no price.

Next

• Install — global install, the npx path, and what lands on disk.
• husk doctor — every line of that report.
• MCP — the one line that gives Claude Code the same machine.