Getting started

jsclaw runs Claude AI agents in isolated containers and gives you a gateway to talk to them — webchat, WebSocket API, schedules, memory. Pure JavaScript, zero npm dependencies, AGPL. From nothing to a conversation in about five minutes.

1Install

You need Node.js 20+ and a container runtime (Docker or Podman) — or no container runtime at all if you use the local process route in step 3.

npm install jsclaw

2Onboard

The wizard checks your environment, walks you through provider and model selection, scaffolds your first agent, and writes jsclaw.json:

npx jsclaw onboard

Providers supported out of the box: Anthropic (direct), GLM (Z.ai), Kimi (Moonshot), AWS Bedrock, Google Vertex, or any Anthropic-compatible endpoint. Secrets are stored as ${ENV_VAR} references, never literals.

3Pick an agent runner

Each message to your agent runs inside a container image. Two options:

	default runner	agent-micro
Harness	Claude Code	jsclaw-agent-micro — ~1,000 lines you can read
Image size	~1.5 GB	~150 MB
License	partially proprietary	AGPL, top to bottom

# default runner
docker build -t jsclaw-agent:latest -f node_modules/jsclaw/container/Dockerfile node_modules/jsclaw/container/

# or agent-micro
git clone https://github.com/jsclaw/agent-micro && cd agent-micro
docker build -t jsclaw-agent-micro:latest -f container/Dockerfile .
npx jsclaw config set containerImage jsclaw-agent-micro:latest

No Docker? Set "sandboxMode": "off" and point localRunner at agent-microNo Docker? agent-micro also runs standalone as a plain node process — see its README for the stdin/stdout contract.#x27;s runner.js — the agent runs as a plain node process. No isolation: the agent acts as your user, so trusted workloads only.

4Run the gateway

export ANTHROPIC_API_KEY=sk-ant-...   # or your provider's key from step 2
npx jsclaw gateway

Open the printed http://127.0.0.1:18789/chat?token=… URL and say hello. The gateway wires everything: task scheduler, heartbeat, IPC watcher, and a WebSocket API.

5Make it yours

Your agent's personality and standing instructions live as plain markdown in the agent folder:

File	Purpose
`agents/main/SOUL.md`	Who the agent is — loaded into every system prompt
`agents/main/HEARTBEAT.md`	What to do when woken periodically
`agents/main/memory/*.md`	Persistent memory the agent reads and writes

From there: schedule tasks with cron, add skills (SKILL.md), wire MCP servers, or route channels like Nostr. The README covers the full API.

Next steps

The handbook — everything jsclaw does · jsclaw README · agent-micro · improve these docs