husk

Husk gives AI agents disposable Linux computers — a shell, a filesystem, network, ports — that they can drive and you can throw away. It also turns any AI chat transcript into a reusable bot you can read, edit, and run as a service.

Interactive architecture diagram — open locally, no server needed. Pan, zoom, dark mode, PNG/SVG export.

Free. Runs on your hardware. No account required.

Quick start

npx @husk/cli doctor            # what's available on this machine
npx @husk/cli up dev            # spin up a Linux computer
npx @husk/cli exec dev -- 'uname -sr && python3 -V'
npx @husk/cli rm dev            # tear it down

No Docker? It still works — see what each provider gives you.

Give Claude Code a computer

claude mcp add husk -- npx -y @husk/mcp

One command. Claude Code gets shell, read_file, write_file, list_dir and expose_port against a real Linux machine — sandboxed away from your repo, filesystem persisting across the conversation. Works with Cursor, Zed, or anything that speaks MCP.

Turn a chat into a bot

husk import                      # finds Claude Code / ChatGPT transcripts
husk distill 3 --out triage.yaml # conversation → agent spec
husk run triage.yaml "check the build"

What comes out is a YAML file you can read and version:

name: triage
model: sonnet
persona: |
  You triage CI failures for a TypeScript monorepo.
  Always read the failing job log before guessing.
tools: [computer, files]
computer:
  flavor: node
  network: { mode: egress, allow: ['*.github.com'] }
limits: { maxSteps: 24, maxCostUsd: 0.25 }

Related MCP server: linux-harness-mcp

Features

• 5 computer providers — Docker, Podman, local (WSL2/POSIX), SSH, Fly

• 10+ model providers — Ollama, Anthropic, OpenAI, Google, Groq, DeepSeek, Mistral, Together, LM Studio, and more

• MCP server — expose a computer as a tool for any MCP-compatible client

• Chat-to-bot pipeline — import transcripts, distill to husk.yaml, run or serve

• Adapters — Discord, Slack, Telegram, webhook out of the box

• Browser automation — Chromium lifecycle, CDP, screenshots, click/type/scroll

• Zero config path — no Docker, no API key, no account: everything still runs

• No telemetry — not "off by default" — absent. No analytics, no crash reporter, no phone-home

• No native modules — npm install is clean on Windows without a C++ toolchain

Models

Bring whatever you have. Aliases resolve across providers so the same husk runs on Opus or on a local Gemma.

Isolation

This is the part most tools are vague about, so here it is plainly.

The local provider is not a sandbox. It stops accidents, not adversaries. husk doctor reports isolated: false for it. See SECURITY.md for the full model.

Install

npm i -g @husk/cli      # or: npx @husk/cli

Node 20.10+. No native modules. Docker optional. API key optional.

Packages

packages/
  core         contracts, husk.yaml schema, primitives
  runtime      computer providers: docker, podman, local, ssh, fly
  models       one surface over ten model providers
  sessions     transcript importers + the distiller
  browser      Chromium lifecycle and CDP automation
  agent        tool-calling loop and built-in tools
  adapters     Discord, Slack, Telegram, webhook
  mcp          MCP server (stdio + streamable HTTP)
  server       control-plane API + bot host
  sdk          typed client for the control plane
  cli          the husk command
apps/
  console      dashboard: live terminal, files, browser
  docs         documentation site (Next.js + MDX)
  web          marketing site (Next.js + Three.js)

Documentation

• Architecture — why it is shaped this way

• API reference — the control-plane HTTP contract

• Build contract — conventions every package obeys

• Security model — what is isolated and what is not

• Examples — six ready-to-run husk.yaml recipes

• Diagrams — 16 interactive architecture, dataflow and design diagrams (open the .html files locally)

Development

git clone https://github.com/Hotragn/husk.git && cd husk
npm install
npm run build
npm test

See CONTRIBUTING.md for conventions, test philosophy, and how to add a provider or model.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a PR — it covers the build contract, test requirements, and the values that show up in code review.

License

Apache-2.0