FAQ

Frequently asked questions about running your PicoCluster Claw cluster. 26 questions across getting started, models, tools, operations, and privacy. If you don’t find your answer here, check access-guide.md for connection details, mcp-tools.md for tool reference, or examples.md for things to try.

Getting started

1. How do I open the control panel?

The control panel lives on clusterclaw itself and is reachable over plain HTTP on your LAN:

http://clusterclaw/

If your computer can’t resolve the hostname, add this to your /etc/hosts:

10.1.10.220  clusterclaw
10.1.10.221  clustercrush

Or just use the IP: http://10.1.10.220/.

The control panel shows live status, cluster controls (restart/shutdown), LED control, installed models, MCP tools, access methods, this FAQ, and example prompts.

2. How do I start chatting with ThreadWeaver?

ThreadWeaver is served over HTTPS through an SSH tunnel. Open a terminal on your computer and run:

ssh -L 5174:localhost:5174 -L 18790:localhost:18790 picocluster@clusterclaw

Leave that terminal open. Then in your browser, visit:

https://localhost:5174

You’ll see a “self-signed certificate” warning the first time — accept it. (The cert is generated by Caddy running on clusterclaw, and the tunnel is already encrypted by SSH, so the warning is cosmetic.)

Pro tip: add this to ~/.ssh/config on your computer so you can just type ssh clusterclaw:

Host clusterclaw
    HostName 10.1.10.220
    User picocluster
    LocalForward 5174 localhost:5174
    LocalForward 18790 localhost:18790

3. Why do I need an SSH tunnel?

For security. ThreadWeaver and OpenClaw are only bound to the clusterclaw loopback interface (127.0.0.1), so nothing on your local network can reach them directly without authenticating via SSH first.

The tunnel forwards two local ports to clusterclaw’s loopback:

5174 → ThreadWeaver (HTTPS, via Caddy reverse proxy)
18790 → OpenClaw Dashboard (HTTPS, via Caddy reverse proxy)

Caddy handles TLS termination using a self-signed “localhost” certificate, which is why you must connect via https://localhost:... and not the LAN IP. The cert only matches the localhost hostname.

4. My browser says the certificate is invalid — is that safe?

Yes, for this specific setup. Here’s why:

Caddy on clusterclaw uses a locally-issued certificate for localhost, not one signed by a public CA (Let’s Encrypt etc.). Public CAs won’t issue certificates for localhost.
Your traffic is already encrypted twice: once by SSH (the tunnel) and once by TLS (Caddy). The “invalid” warning is only about the browser not trusting the issuer, not about the connection being unencrypted or intercepted.
You can safely click “Advanced → Proceed to localhost (unsafe)” or “Accept the risk” on Firefox.

If you want to make the warning go away permanently, you can add Caddy’s root certificate to your system trust store. Caddy stores it at /data/caddy/pki/authorities/local/root.crt inside the Caddy container — see Caddy’s docs for how to install it.

5. Can I access PicoCluster Claw from outside my home network?

Not by default — PicoCluster Claw is designed for home LAN use with a strict firewall. For remote access, install Tailscale on clusterclaw and your remote devices:

# On clusterclaw
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Then use the Tailscale IP instead of 10.1.10.220:

ssh -L 5174:localhost:5174 -L 18790:localhost:18790 picocluster@<tailscale-ip>

Tailscale wraps everything in a WireGuard VPN and handles NAT traversal automatically. It’s the recommended way to get PicoCluster Claw from your phone or laptop while away from home.

Models and LLMs

6. What’s installed on PicoCluster Claw and why those models?

PicoCluster Claw ships with 9 Ollama models (~27 GB total) that cover general chat, reasoning, code, and vision. See the Installed Models table on the control panel for the full list with sizes. The set was chosen to give you one or two strong models in each major category without overwhelming the Jetson’s storage or memory.

Quick guide:

Use for	Best model	Why
Tool use / agent	`granite4.1:8b`	Default. 10/10 on tool-call benchmark. Most reliable.
Natural language	`qwen2.5:7b`	Best at interpreting ambiguous requests
Fast + capable	`nemotron-3-nano:4b`	9/10 T1–T4, faster than 8B models
Reasoning / math	`deepseek-r1:7b`	Strong chain-of-thought, shows its work
Web research	`qwen3.5:4b`	Good at web tasks
Vision (images)	`llava:7b`	Best vision quality at this size

7. Which model should I use for what?

Switch models from the ThreadWeaver settings panel (top right). A good rule of thumb:

Tool-heavy tasks — granite4.1:8b ← default local model
Natural-language requests — qwen2.5:7b (best at interpreting ambiguous commands)
Fast + capable — nemotron-3-nano:4b (4B but 9/10 on tool benchmark)
“Think step by step” problems — deepseek-r1:7b
Image understanding — llava:7b

Why granite4.1:8b is the default: it scored 10/10 on our T1–T4 tool-call ladder — the only model to do so. It’s the most reliable at structured tool invocation, which matters for MCP workflows. For conversational use where you want more natural phrasing, qwen2.5:7b is the better pick. See the benchmark results for full numbers.

For absolute best tool use, switch the provider to an external LLM (Claude, GPT-4, Gemini) — see question 9.

8. Can I use Claude, GPT, Gemini, or Grok instead of the local models?

Yes. ThreadWeaver supports five providers out of the box:

local — Ollama on clustercrush (default, private)
anthropic — Claude models
openai — GPT models
gemini — Google Gemini
grok — xAI Grok

Open ThreadWeaver → Settings → paste your API key for the provider you want to use → pick a model → chat as normal. You can switch providers mid-conversation or on a per-conversation basis.

Your API keys are stored on clusterclaw in a JSON file inside the ThreadWeaver container; they never leave the box except when ThreadWeaver makes API calls to that provider.

9. If I use an external LLM, can it still use the local MCP tools?

Yes, fully. This is one of the coolest properties of ThreadWeaver’s MCP architecture.

The tool execution always happens on clusterclaw. The external LLM only sees tool schemas (names, descriptions, parameter shapes) and decides when to call them. The flow is:

You ask the LLM “make the LEDs purple”.
ThreadWeaver sends your message plus the 28 tool schemas to the external API.
The LLM replies with a tool call: {"tool": "set_led_color", "args": {"color": "purple"}}.
ThreadWeaver executes the tool locally on clusterclaw (the LED API gets a POST to port 7777, Blinkt! turns purple).
The tool result ({"status": "ok"}) goes back to the LLM.
The LLM writes its final reply: “Done! The LEDs are now purple.”

The external LLM never touches your hardware directly — it just describes what it wants, and clusterclaw acts as the trusted executor. All 28 tools work with every provider: LEDs, temperatures, files, models, time, everything.

In practice, external models (Claude, GPT-4) tend to be better at multi-step tool workflows than the smaller local models. If you want to see what tool use really looks like, try a complex request with Claude or GPT-4 as the provider.

10. What gets sent to external LLM providers?

When you use an external provider, the entire conversation flows through that provider’s API, including:

Your prompts and the LLM’s replies
All 28 tool schemas (names, descriptions, parameters) — sent on every request
Tool call results (e.g. CPU temp readings, file contents from the sandbox, installed model lists)
Any images or attachments you include

What does not get sent:

Your API keys (they’re used only to authenticate the request to that specific provider)
Files outside the sandbox
Anything on your LAN that the tools don’t explicitly fetch
Other conversations you’ve had on ThreadWeaver
Raw inference from the local models

If you need strict privacy, stick with the local provider. Everything stays on clusterclaw/clustercrush. The only network traffic is between clusterclaw and clustercrush on the LAN (Ollama API), plus whatever your browser needs to render the UI.

11. How do I add a new model from the Ollama library?

Run pc-pull from inside an SSH session on clustercrush:

ssh picocluster@clustercrush
pc-pull qwen3-coder:30b-a3b-q4_K_M

Or browse ollama.com/library, find a model you want, and pass the exact tag. The model will download and be usable in ThreadWeaver the next time you open the model picker.

You can also ask the LLM to do it for you (one of the clustercrush MCP tools is pull_ollama_model):

“Pull the moondream model from the Ollama library”

Models are stored on the Jetson’s NVMe. Check free space first with pc-status — 7 GB free is a reasonable minimum for a new mid-size model.

12. How do I remove a model I don’t need?

On clustercrush:

ssh picocluster@clustercrush
ollama rm <model-name>

For example, ollama rm llava:7b frees about 4.7 GB. There’s no pc-rm wrapper on purpose — deleting models is destructive, so we kept it as a deliberate Ollama command rather than a one-liner.

Tools and capabilities

13. What can the LLM actually do with the 28 MCP tools?

Lots. Full reference in mcp-tools.md, but the short version:

LEDs (5 tools) — set color, run animations, show progress bars, success/error pulses
System (6 tools) — CPU temp, memory, disk, uptime, network, load
Picocrush (4 tools) — list/pull Ollama models, check GPU memory, see what’s loaded
Time (4 tools) — current time, day of week, durations, countdowns
Files (5 tools) — sandboxed read/write/list/delete in /tmp/clusterclaw-sandbox
Built-in (4 tools) — ThreadWeaver’s built-in file/directory/command tools

See examples.md for 30+ concrete prompts to try.

14. Can the LLM read files on my computer or clusterclaw’s filesystem?

No. The files MCP server is sandboxed to /tmp/clusterclaw-sandbox inside the ThreadWeaver container. Python’s Path.resolve() + relative_to() checks reject any path that escapes the sandbox, so attempts like ../../../etc/passwd fail loudly.

The built-in read_file and write_file tools (4 tools from ThreadWeaver itself) are slightly broader — they can read inside the ThreadWeaver container’s filesystem — but still can’t reach your computer or the host system.

Your computer’s filesystem is never exposed to the LLM. The LLM talks to tools on clusterclaw; clusterclaw talks to its own sandbox. There’s no path from the LLM to your laptop’s files unless you explicitly paste the contents into the chat.

15. Can I add my own MCP tools?

Yes. See the Adding Your Own MCP Server section of mcp-tools.md — there’s a ~20-line Python template. You drop a new file in /opt/clusterclaw/mcp/, add one line to threadweaver/start.sh to auto-connect it, and rebuild the ThreadWeaver container:

cd /opt/clusterclaw
sudo docker compose build threadweaver
sudo docker compose up -d threadweaver

ThreadWeaver also supports connecting to any stdio-based MCP server dynamically via its API. You don’t have to rebuild to add a third-party server — you can connect one at runtime.

16. Which models support tool calling?

ThreadWeaver sends MCP tool schemas with every chat request. Some Ollama models don’t accept tool schemas, and ThreadWeaver auto-detects this and falls back to chat-only mode for those models, showing you a notice like:

Model gemma3:4b doesn’t support tool calling. Responding without tools.

You’ll still get a reply — you just won’t get tool calls in that conversation.

Known models that support tools (full MCP tool calling):

granite4.1:8b ← default local model — 10/10 T1–T4, most reliable
qwen2.5:7b — best natural language + tools, 9/10 T1–T4
nemotron-3-nano:4b — fast 4B with 9/10 T1–T4
qwen3.5:4b — 8/10 T1–T4, good web tasks
llama3.1:8b — 6/10 T1–T4, general baseline
deepseek-r1:7b — strong reasoning, shows its work

Known models that don’t support tools (chat-only with auto-fallback):

llava:7b — vision model (use it for image understanding instead)
moondream:1.8b — tiny vision model

For vision tasks, use llava:7b or moondream:1.8b and attach an image. For tool-heavy workflows (running commands, controlling LEDs, reading files), use granite4.1:8b. See the benchmark results for full scores.

If you want excellent tool use AND a smarter conversation, switch the provider to Claude, GPT-4, or Gemini in Settings. External LLMs use the same MCP tools just like local ones (see FAQ #9).

17. Why don’t smaller models use tools as well as larger ones?

Tool use is a form of structured output — the model has to produce valid JSON in a specific schema, decide when to use a tool versus answer directly, and chain multiple tool calls when a question requires several steps. Bigger models with more parameters generally handle this better because they’ve seen more examples of structured tool calling during training.

Expected behavior on PicoCluster Claw:

granite4.1:8b ← default — 10/10 T1–T4, most reliable multi-turn tool use
qwen2.5:7b — 9/10 T1–T4, best natural-language interpretation
nemotron-3-nano:4b — 9/10 T1–T4, fast, good reasoning about tool output
qwen3.5:4b — 8/10 T1–T4, good for web + single-step tasks
llama3.1:8b — 6/10 T1–T4, general baseline
llama3.2:3b — 5/10 T1–T4, degrades after 1-2 calls (see below)
llava:7b, moondream:1.8b — no tool support (ThreadWeaver auto-falls back to chat-only)

The multi-turn degradation pattern (seen specifically with llama3.2:3b and other small models):

First 1-2 tool calls work perfectly — model emits structured tool_calls in the response
By the third or fourth request in the same conversation, the model starts printing tool calls as text in the content field instead of emitting them as structured output:
```
```json
{"name": "system__get_temperature", "parameters": {...}}
```
Result: The current CPU temperature is not available.
Because it’s text and not a real tool call, ThreadWeaver never executes the tool — and worse, the model often hallucinates a plausible-looking result immediately after, so the reply reads like a real answer when nothing actually happened.

This is a known weakness of 3B-parameter models under long tool-use contexts. It’s not a ThreadWeaver bug or an Ollama bug — the model’s learned “mimicry” competes with its structured-output discipline once the context gets crowded with tool call history.

How to recognize it: if the response contains ```json blocks in the plain text instead of the expected 🔧 Tool call: markers, the model is hallucinating. The physical side-effects (LEDs, file writes) won’t happen either — check the LEDs or the sandbox to confirm.

Fix: switch to granite4.1:8b for that conversation (Settings → Local → Model). It’s the default for a reason — it won’t hallucinate tool calls.

For tool-heavy tasks, either use granite4.1:8b or switch to an external provider (Claude/GPT-4/Gemini — see FAQ #9).

Cluster operations

18. How do I shut down or restart the cluster?

Three ways, pick your favorite:

From the control panel (easiest) — open http://clusterclaw/ and click “Restart Cluster” or “Shutdown Cluster” in the Cluster Control section.

From the terminal on clusterclaw:

ssh picocluster@clusterclaw
pc-restart         # restart both nodes
pc-shutdown        # shut down both nodes
pc-restart clusterclaw    # restart just this node
pc-restart clustercrush   # restart just the Jetson

Via API (useful in scripts):

curl -X POST http://clusterclaw:8888/restart \
  -H "Content-Type: application/json" \
  -d '{"token":"picocluster-shutdown","target":"all"}'

Whichever method you use, the Blinkt! LEDs show a blue pulse sequence before the node goes down so you get visual confirmation.

19. How do I update ThreadWeaver or OpenClaw to newer versions?

Use the built-in update scripts:

ssh picocluster@clusterclaw
pc-update-threadweaver    # rebuild ThreadWeaver container from latest ThreadWeaver main
pc-update-openclaw        # rebuild OpenClaw container with latest openclaw npm package
pc-update                 # update everything (clusterclaw containers + portal + clustercrush models)

To update the Ollama models on clustercrush to their latest versions:

pc-update-models

These scripts git pull the PicoCluster Claw repo first, then run whatever update is needed for each component. They’re safe to run on a live cluster — the containers restart individually with a brief downtime.

20. What do the LED colors and animations mean?

The Blinkt! strip on clusterclaw shows cluster status at a glance:

Pattern	Meaning
Teal scanner (slow sweep)	Idle, everything healthy
Purple pulse	Agent is thinking
Cyan flash	Agent is using a tool
Green burst	Operation succeeded
Red flash	Operation failed or error
Blue progress bar	File transfer / long operation in progress
Amber solid	Warning condition (high temp, service degraded)
Blue pulse then fade	System shutting down

The LED API is reachable at http://clusterclaw:7777/ — you can drive it from your own scripts or the control panel’s LED buttons. The pc-led command wraps it for easy use from the terminal.

21. How do I check if everything is healthy?

On clusterclaw:

ssh picocluster@clusterclaw
pc-status

That shows Docker container status, systemd services (LED daemon, shutdown API), health checks for all 6 endpoints, disk usage, and load average.

On clustercrush:

ssh picocluster@clustercrush
pc-status

Shows Ollama service state, health, unified memory usage, currently-loaded models, installed models, disk, and load.

The control panel (http://clusterclaw/) also pulls some of this data live.

22. One of the services isn’t responding — what do I do?

First, check pc-status on both nodes to see which service is actually down. Then:

Container is stopped or unhealthy:

cd /opt/clusterclaw
sudo docker compose ps            # see state
sudo docker compose logs threadweaver    # or openclaw, portal, caddy
sudo docker compose restart threadweaver

Systemd service is inactive:

sudo systemctl status clusterclaw-leds shutdown-api
sudo systemctl restart clusterclaw-leds

Ollama on clustercrush is unreachable:

ssh picocluster@clustercrush
sudo systemctl status ollama
sudo systemctl restart ollama
ollama list               # verify it comes back

Nuclear option — full cluster restart from clusterclaw:

pc-restart all

If all else fails, pull the power to both nodes, wait 10 seconds, and boot them back up. The install is idempotent and everything starts automatically on boot.

Privacy and security

23. Is my data private when I use the local LLM?

Yes. The local provider runs inference on clustercrush (Jetson Orin Nano) using Ollama, and the data path is entirely inside your LAN:

Your browser → SSH tunnel → clusterclaw:ThreadWeaver → clustercrush:Ollama
                                ↓
                            MCP tools on clusterclaw

Nothing leaves your network. The model weights are stored locally on clustercrush’s NVMe. Conversations are stored in ThreadWeaver’s database on clusterclaw. API calls to external services only happen if you explicitly switch to an external provider (Claude, GPT, etc.) or if an MCP tool fetches something over the network — and we don’t ship any such tools by default.

24. What’s the difference between ThreadWeaver and OpenClaw?

They’re both agents, but different styles:

ThreadWeaver is a chat-first interface. You have conversations, branch them, save them, search across them, switch models mid-thread. It’s the most natural entry point if you just want to chat with your local LLM and occasionally use tools.

OpenClaw is an agent framework. You give it a goal and it autonomously plans, uses tools, browses the web, and reports back. Think of ThreadWeaver as the place you talk to the model, and OpenClaw as the place you delegate tasks to the model. OpenClaw also has messaging channel integrations (Telegram, Discord, Slack) for mobile access.

Both run simultaneously on clusterclaw, both talk to the same Ollama backend on clustercrush, and both can use the same MCP tools.

25. How do I change the default password and tokens?

SSH password (do this first — the default picocluster / picocluster is well-known):

ssh picocluster@clusterclaw
passwd
# enter old password, then a new one twice

ssh picocluster@clustercrush
passwd

OpenClaw gateway token (the token that protects the /__openclaw__/canvas/ dashboard):

ssh picocluster@clusterclaw
openclaw config set gateway.auth.token "a-long-random-string-here"
sudo docker restart openclaw

Shutdown API token (the token that protects pc-restart / pc-shutdown):

Edit /etc/systemd/system/shutdown-api.service.d/override.conf (create it if missing) and set Environment=SHUTDOWN_TOKEN=your-new-token, then:

sudo systemctl daemon-reload
sudo systemctl restart shutdown-api

Update the pc-restart / pc-shutdown wrapper scripts to pass the new token, or set SHUTDOWN_TOKEN=your-new-token in your shell environment.

26. Can I expose PicoCluster Claw to the internet safely?

Not directly. PicoCluster Claw’s default firewall only accepts connections from your LAN, and the ThreadWeaver/OpenClaw dashboards require an SSH tunnel from a trusted machine.

If you need remote access, use one of:

Tailscale (recommended) — zero-config WireGuard VPN. Install on clusterclaw and your remote devices, connect through Tailscale IPs instead of LAN IPs.
Cloudflare Tunnel — if you specifically want a public hostname and are willing to authenticate via Cloudflare Access.
SSH from a jump host — forward clusterclaw’s SSH through a public-facing bastion.

Do not:

Port-forward clusterclaw’s SSH directly to the public internet without fail2ban and a rate-limited public key setup.
Expose port 80 (the portal) or 5174/18790 (the HTTPS services) to the public internet — the portal has no authentication and the HTTPS certs are localhost-only.
Expose clustercrush (Ollama) to the internet at all. It has no authentication.

Anything else?

If your question isn’t covered here, check:

access-guide.md — connection methods, credentials, port reference
mcp-tools.md — complete MCP tool reference
examples.md — 30+ example prompts to try
pc-status on either node — live health dashboard
sudo docker compose logs -f in /opt/clusterclaw/ on clusterclaw — live container logs

Or open an issue at github.com/picocluster/PicoCluster-Claw.