NanoClaw

NanoClaw: Install and first job

This page installs NanoClaw on a Mac or on Windows 11, turns on its safety switches, connects a model, and gives the agent one small job. It follows Pick it and plan, so have your API key and its spend limit ready before you start.

Install on a Mac

1. Open Terminal and check Git

Press Command + Space, type Terminal, and press Return to open the Terminal app. Git is the tool that downloads NanoClaw, so check that you have it by typing this and pressing Return:

git --version

If your Mac offers to install developer tools, say yes, then run the command again.

What you should see a line that starts with git version. The number after it can be different.

2. Download NanoClaw and start setup

Run these four lines one at a time, and wait for each to finish before you type the next:

cd ~
git clone https://github.com/nanocoai/nanoclaw.git
cd nanoclaw
bash nanoclaw.sh

The script checks your computer, then installs what is missing. On a Mac that can include Homebrew (a tool installer), Node, pnpm, and Docker Desktop. It asks before installing Homebrew, which can pull in Apple's developer tools and take 5 to 10 minutes on a new Mac, and you may be asked for your Mac password.

Do not run this as an administrator or with sudo; use your everyday account.

When the menu appears, use the arrow keys and Return to choose Standard setup, then Fresh agent.

What you should see the setup menu, then Standard setup and Fresh agent chosen.

3. Choose where the container comes from

Setup now prepares the agent's sealed-off workspace, which NanoClaw calls a sandbox. The official pages describe this question in different words:

Either answer works:

The pages also disagree about which answer is the default. The README says building here is the default, while the install page and the Echo page say fetching is the recommended default. Read the screen and pick the one you want, and note that if you plan to use OpenCode instead of Claude, setup builds here anyway.

If you fetch, a browser opens. Sign in or sign up, then check that the code on the page matches the code in Terminal.

What you should see either a browser confirmation screen, or a local build that runs for several minutes. Keep Terminal open until setup moves on to your AI account.

4. Connect your model

Setup installs OneCLI first. OneCLI is a vault, a locked box on your computer that keeps your key out of the agent's container.

Then setup asks which AI service to use. Follow Connect a model below, and do not paste your key into a chat.

What you should see Terminal prints Done. after your key is saved in the vault.

5. Let setup finish the access rules and background service

Terminal says Setting your assistant's access rules…. These rules decide which of your folders the agent may see, and on a new install that list starts empty, so leave it empty.

Wait for Access rules set. Then let NanoClaw start its background service. A service is a program that keeps running after you close the window, and on a Mac it starts again when you log in. When it asks, type the name you want the agent to call you.

What you should see Access rules set. (or Access rules already set.), then a question asking your name.

6. Say hello from Terminal

Setup sends a test message first, and the first reply can take 30 to 60 seconds while the container starts.

Choose Pause here and chat with your agent from the terminal, then type something harmless:

Hi! Give me three ideas for a relaxing weekend at home.

Press Return. To finish, leave the next message empty and press Return, and answer the time zone question if one appears.

What you should see the agent's reply under your message.

7. Skip chat apps for now

At the channel question, choose Skip for now. A channel is a chat app the agent can answer in, and that comes later.

What you should see Terminal ends with You're ready! Chat with pnpm run chat hi.

Now go to Turn on the safety switches first.

Install on Windows 11 (through WSL2)

1. Install WSL2

Click Start, type PowerShell, right-click Windows PowerShell, and choose Run as administrator. This is the only step that needs an administrator. Type:

wsl --install

This turns on WSL and installs Ubuntu, a common kind of Linux. Restart your computer when it finishes; new installs use WSL2 by default.

After the restart, open Ubuntu from the Start menu. The first time, it unpacks files and then asks you to make a Linux username and password. Write the password down, because Linux asks for it when it installs things.

What you should see an Ubuntu window with a line ending in $, after you made your Linux username and password.

2. Check Git inside Ubuntu

Do every step from here on inside the Ubuntu window, not in PowerShell. Type:

git --version

If Git is missing, install it with sudo apt-get install git, then run the check again.

What you should see a line that starts with git version.

3. Download NanoClaw and start setup

Run these four lines one at a time, in Ubuntu:

cd ~
git clone https://github.com/nanocoai/nanoclaw.git
cd nanoclaw
bash nanoclaw.sh

The installer notices WSL and treats it like Linux, and it installs Node and pnpm if they are missing. The install page says that on Linux and WSL it also installs Docker inside Linux and starts it, so it may ask for your Linux password.

The README lists Docker Desktop for Windows, and this guide could not confirm which one NanoClaw expects if Docker Desktop is already on your PC. If setup stops at Docker, follow the message it shows.

Do not run setup as root, which the installer warns about. Choose Standard setup, then Fresh agent.

What you should see the setup menu, then Standard setup and Fresh agent chosen.

4. Finish the same wizard as the Mac

The rest is the same as the Mac steps 3 through 7 above:

  1. Choose where the container comes from.
  2. Connect your model, using Connect a model.
  3. Wait for Access rules set. and leave the folder list empty.
  4. Say hello from the terminal.
  5. Choose Skip for now at the channel question.

What you should see Terminal ends with You're ready! Chat with pnpm run chat hi.

5. Check whether the background service was set up

On WSL, setup can only make a real background service if a Linux feature called systemd is on. If it is off, setup writes a start script called start-nanoclaw.sh instead.

If setup told you it wrote start-nanoclaw.sh, start NanoClaw yourself with:

bash start-nanoclaw.sh

To get a real service instead, the install page says to turn on systemd. Add [boot] and systemd=true to the file /etc/wsl.conf, then run wsl --shutdown in PowerShell, open Ubuntu again, and run:

cd ~/nanoclaw
pnpm run setup -- --step service

This guide could not confirm whether NanoClaw keeps running after you close the Ubuntu window.

What you should see either the start script running, or the service step finishing without an error.

Now go to Turn on the safety switches first.

Turn on the safety switches first

Do this before you give the agent any real job.

What is already on. NanoClaw runs each agent inside a Docker container. The security page says every container drops all extra powers (--cap-drop=ALL) and cannot gain new ones (no-new-privileges). It does not get your home folder, your .ssh keys, or Docker's controls, and your API key stays in the vault, outside the container.

What does not ask. Inside the container, ordinary commands run without asking you first. The agent asks a person only for a few things:

What is off. Egress lockdown is off by default. Egress means traffic going out, and with lockdown off, the container can reach the whole internet directly, which gives a tricked agent a way to send your data somewhere.

The security page is honest about the gap: a tricked agent can still read or delete its own workspace, message anyone it is connected to, and spend through the keys it was given.

1. Turn on egress lockdown

This forces the agent's traffic through the vault. In Terminal (Mac) or Ubuntu (Windows), run:

cd ~/nanoclaw
echo 'NANOCLAW_EGRESS_LOCKDOWN=true' >> .env
grep EGRESS .env

Then restart NanoClaw so it reads the change.

On a Mac, find the service name, then restart it, putting the name you found where it says <label>:

launchctl list | grep nanoclaw
launchctl kickstart -k gui/$(id -u)/<label>

On Windows with systemd on, find the name, then restart it, putting the name you found where it says <unit>:

systemctl --user list-units 'nanoclaw-v2-*'
systemctl --user restart <unit>

On Windows with the start script, run bash start-nanoclaw.sh again.

The docs say lockdown breaks any tool that does not go through the vault. If lockdown is on but cannot be set up, NanoClaw refuses to start the agent instead of running it unlocked. This guide could not confirm which of the agent's web tools still work with lockdown on, so if your first web job fails, this is the likely reason.

What you should see NANOCLAW_EGRESS_LOCKDOWN=true printed by the grep line, and no error after the restart.

2. Keep the folder list empty

The list of your folders the agent may see lives in ~/.config/nanoclaw/mount-allowlist.json, and if that file does not exist, no extra folders are shared. Setup said the list starts empty, so leave it that way for now. Do not share your home folder, Documents, or Desktop.

What you should see no extra folders shared. Setup said Access rules set. with nothing added.

3. Optional limits the docs offer

These are extra, not required. Add them to .env the same way as step 1, then restart:

What you should see the new lines in .env, and no error after the restart.

4. Allow only yourself in any chat app

You skipped chat apps during setup, so keep it that way for your first job. When you add one later, allow only yourself; the steps are in Later: chat apps and schedules. Never set a chat to public, because that lets anyone talk to your agent.

What you should see no chat app connected yet.

Connect a model

Setup asks which AI service should power the agent. You pick it once during install, and you can change it later.

Claude with an API key (what setup is built around). Choose Claude, then Paste an Anthropic API key, and get the key from the Claude Console. The credentials page says to make a key for one workspace only, because a key that covers several workspaces fails every request. You pay Anthropic for each use, so set the spend limit first.

Another company's key, through OpenCode. Choose OpenCode at the AI service step. The providers page says OpenCode takes a key for OpenRouter, DeepSeek, OpenAI, Google, or Anthropic, and it can also use a local model server that speaks the OpenAI format. With OpenCode, setup builds the container image on your machine, with no NanoClaw account. This guide could not confirm that a free Google AI Studio key works through OpenCode inside NanoClaw.

OpenAI through Codex. Setup also offers Codex, which takes an OpenAI API key or a ChatGPT sign-in. See the ChatGPT row in Pick your model and budget.

A model on your own computer. The README lists an Ollama add-on for local models, but the providers page says that add-on targets an older setup and is not a supported drop-in on current code, so do not count on it. The supported local path is OpenCode pointed at a local OpenAI-format server.

Claude chat plan sign-in. Setup offers it, and the official quick start uses it, but this guide does not. See the unofficial-route notes for why.

To add OpenCode after install, the providers page gives this command:

cd ~/nanoclaw
pnpm exec tsx setup/index.ts --step provider-auth opencode

Your key goes into the vault during these steps, so never paste a key into a chat message.

What you should see Terminal prints Done. after the key is saved, and the agent answers your hello.

Or use a local model

NanoClaw's Ollama add-on targets an older setup, so do not use it for the main model. The providers page names OpenCode as the way to use a local OpenAI-format server, and setup's OpenCode step writes the OPENCODE_BASE_URL setting for you. This guide could not confirm which address reaches Ollama from inside NanoClaw's container, or whether egress lockdown allows it, so it has no tested steps for this yet.

Your first safe job

Chat from Terminal (Mac) or Ubuntu (Windows). Each pnpm run chat sends one message and prints the reply. Keep the window open until the reply arrives, because a reply that comes after you close it is not shown again.

cd ~/nanoclaw
pnpm run chat "Look up three current facts about a topic you choose. Save a short comparison as a file in your own workspace. Do not install anything. Do not ask for any of my folders."

The agent works inside its container. Its workspace is a folder under ~/nanoclaw/groups/ on your computer, so you can look at what it saved.

If the agent says it wants to install a program, add a tool, or reach one of your folders, tell it no. This guide could not confirm how approval cards show up when you only chat from Terminal, but the security page says that if no approver can be reached, the request is denied.

If the web part fails with egress lockdown on, that is the trade-off from the safety step. You can ask for a job that needs no web instead, such as writing a checklist into a file.

What you should see the agent's reply in the window, then a new file in a folder under ~/nanoclaw/groups/. Nothing appears anywhere else on your computer.

Sources

Opened 14 November 2026.

NanoClaw:

Windows:

This guide's own notes:

Next

Continue to Files, the browser, and memory.

Checked 14 November 2026 · prices, limits, and versions change