Hardware components | ||||||
 |
| × | 1 | |||
Software apps and online services | ||||||
| ||||||
Until now, getting QClaw running meant cloning a repo, building a Go binary, downloading model weights, and wiring up a systemd unit, a multi-step terminal workflow well-suited to confident Linux users but a steep barrier for everyone else. QClaw App Lab Edition changes that. It delivers the same complete local agentic AI environment as a single-click Arduino App Lab application, making the entire experience accessible from the moment you open the App Lab UI.
What Is QClaw?If you haven't yet read the original QClaw project article, here's the core idea:
QClaw is the agentic system that fully exploits the Arduino Uno Q split-silicon architecture. QClaw lives on the MPU (Qualcomm QRB2210, four Cortex-A53 cores, 4 GB LPDDR4X) and controls its MCU (STM32). QClaw holds the MCU in reset and reprogram its flash directly via GPIO-connected SWD using the linuxgpiod driver. No USB cable, no probe, no second machine.
You talk to QClaw through a chat interface. You ask it to do something like "read the temperature from the Modulino Thermo and log it every ten seconds" and QClaw does it. End to end. It generates sketches, compiles them with arduino-cli, picks up the binary, and pipes it through OpenOCD over the GPIO SWD bridge to the MCU's flash. The MCU executes the firmware. The entire cycle happens on the board, offline, in one conversational turn.
The original QClaw was a terminal-first project. You installed it by cloning a repository, running make qclaw-install, manually downloading model weights from Hugging Face, and starting sessions with make qclaw-agentic or make qclaw-direct. That flow works well for developers comfortable on the command line, but it's a significant barrier for the broader Arduino community.
QClaw App Lab Edition repackages QClaw entirely as an arduino:app, a first-class citizen of the App Lab ecosystem. Everything the original terminal flow did manually, the App Lab handles automatically on first launch:
- Downloading Qwen3.5-0.8B-Q4_0 model weights (~537 MB).
- Starting
llama-serverat127.0.0.1:8083. - Serving the WebUI chat interface as an
arduino:web_uiBrick athttp://<uno-q-ip>:7000. - Exposing the entire agent tree;
SOUL.md,IDENTITY.md,AGENTS.md,USER.md,memory/,skills/,sketches/,python/,underagent/via host bind-mount, so App Lab's file editor can open and modify any of them.
The result is that getting a fully autonomous AI sketch-writer running on your Uno Q now takes about as long as it takes the model weights to download.
Now With Local and Cloud API CapabilitiesThe App Lab Edition also introduces configurable cloud AI routing from the WebUI settings panel. You can switch between:
- yzma (on-device): The local
llama-serverrunning Qwen3.5-0.8B Q4_0; fully offline, no API keys, always available, or - Cloud API: Use OpenRouter, OpenAI, or Anthropic's Claude Opus 4.7, Sonnet 4.6, or Haiku 4.5; provides higher capability models for complex tasks, routed through the same agent loop, tools, and skill workspace as the local engine.
The agent loop is identical regardless of which engine is active. You can start a session on the local model, switch to Claude for a complex multi-file project, and switch back. The 15 skills, 8 tools, and workspace state are continuous across both.
How QClaw Utilizes the Full App Lab ArchitectureQClaw App isn't just packaged as an App Lab app, it's designed to exploit every layer of the App Lab stack:
arduino:web_ui Brick: The chat interface is served directly as an App Lab web UI Brick on port 7000. App Lab manages its lifecycle, restarts, and port mapping.
Editable agent tree via bind-mount: The entire agent/ directory is exposed to the host filesystem, meaning App Lab's built-in file editor lets you modify SOUL.md (the system prompt), IDENTITY.md (the agent's persona), individual SKILL.md files, and the Python scripts that implement tools, all without leaving the App Lab environment.
Bridge-compatible arduino tool: The arduino tool's compile-and-flash path is designed to coexist with App Lab's own Bridge daemon, so QClaw-generated sketches don't conflict with App Lab's MCU sketch management.
Custom Brick pathway: With App Lab 0.7's Custom Bricks feature, individual QClaw tools and skills can be refactored into standalone reusable Bricks, making it easy to incorporate QClaw's sensor skills or network tools into entirely different App Lab projects.
The QClaw SandboxApp Lab starts QClaw by running docker compose up against a generated compose file. The image is ghcr.io/arduino/app-bricks/python-apps-base:0.8.0,a small Python 3.13 base. The user inside the container is app (uid 1000-ish), with no extra capabilities and no privileged mode. The container's /app is bind-mounted from the host repo at ~/ArduinoApps/qclaw/. Network namespace is private but port 7000 is published to 0.0.0.0:7000 on the host, so anything on the LAN can reach the WebUI. There is no --network=host, no --device, no --cap-add. It's a stock Docker workload, with the default Docker Engine seccomp profile.
That's what the container is. Everything that follows is about how QClaw's design uses, doesn't use, or has to work around that boundary.
The trust mapPicture the Uno Q as four square zones, and which zone an agent invocation can reach is the whole game:
Container is 2. Host is 3. The agent runs in zone 2. Two of its tools, by design, cross from 2 → 3. The arduino then crosses from 3 → 1.
Standard Docker concerns apply. The QClaw container doesn't use --privileged, doesn't --cap-add, doesn't --pid=host, doesn't --network=host. The image is small, the workload is a Python script and a Go binary, and the kernel surface area exposed via syscalls is whatever default seccomp permits. The same kernel CVEs that would let any untrusted Docker workload escape would apply here, keep your Linux 6.16 patched.
The agent doesn't make this materially worse. It also doesn't make it better. Container escape on QClaw is the same problem as container escape on any Python app, with the added incentive that the host has a daemon willing to flash microcontrollers.
Optional arduino-cli DaemonFor the full compile-and-flash workflow, install the optional systemd user unit on the Uno Q to enable the background arduino-cli daemon. The chat interface and all tools except arduino work without it. You can still have full sensor conversations, LED control, camera capture, and network queries while the daemon is set up in the background.
QClaw is built around a local llama-server instance running Qwen3.5-0.8B Q4_0 (537 MB), a compact quantized language model that fits comfortably on the Uno Q alongside the rest of the system. The full agent occupies about 1.3 GB of RAM and decodes at roughly 8 tokens per second, slow compared to a desktop GPU, fast enough for real edge AIoT workflows.
On top of the inference engine sits an eight-tool agentic surface:
- arduino: Compiles sketches with arduino-cli and flashes the MCU via OpenOCD over GPIO SWD
- camera: Captures single frames via V4L2/GStreamer
- sysfs_led: Controls the MPU-side RGB LEDs at /sys/class/leds/
- network: Reports hostname, interfaces, and default gateway (read-only)
- i2cdetect: Lists and scans Linux I²C buses to discover Modulino and other peripherals
- read_file: Reads files in the agent workspace
- write_file: Writes files in the agent workspace
- list_dir: Lists workspace directories
No general shell execution needed. No arbitrary exec. Every tool validates arguments against an allow-list. The total tool schema fits in about 3.4 KB, leaving ample room in the 12K context window for the system prompt and conversation history.
Powering efficient behavior at 0.8B scale is QClaw's pre-router: a flat table of 23 keyword-matching rules that map incoming prompts to 15 skill documents. When you send a message, the pre-router finds the matching skills and inlines their SKILL.md files directly into the system prompt before the LLM call. The model doesn't need to issue a read_file call to retrieve knowledge, it's already there. Since a read_file on a 0.8B model costs a full LLM iteration (potentially 10-20 minutes of cold prefill and decode at this scale), the pre-router eliminates that overhead entirely.
The 15 skills cover:
- Sketch fundamentals: blink, button, potentiometer, servo, breathe, CAN bus, DAC, OPAMP
- The 13×8 LED matrix with Arduino_LED_Matrix templates
- Uno Q hardware: pin tables, voltage rules, connectors, power domains
- Dual-chip workflow: Bridge RPC, App Lab integration, Bricks configuration
- Linux-side capabilities: Wi-Fi, Bluetooth, camera, OpenCV, microphone, sysfs LEDs
- Plug-and-play Modulino sensors
Adding new skills is deliberately simple, write a SKILL.md in the agent/skills/<name>/ directory, add one regex rule to the router, and QClaw knows it.
QClaw ships two runtimes on top of the same inference backend:
Agentic mode (High mode) runs the full Go gateway with the multi-iteration agent loop, all eight tools, and the pre-router. This is the mode you want for anything involving sketches, sensors, or hardware. It's also the only mode that can actually compile and flash.
Direct mode (Medium mode) is a thin Python REPL that POSTs directly to llama-server after running the pre-router in Python. No tool loop, no multi-turn orchestration. About 33% lower latency on pure factual queries, useful when you just want to ask which Uno Q pins support PWM or what the Modulino Thermo I²C address is.
This is the fastest path. No terminal required beyond what App Lab provides.
What you need:
- An Arduino Uno Q connected to your local network
- Arduino App Lab installed on your PC (download at arduino.cc/en/software)
- The QClaw v1.0.2 zip from github.com/laurenvil/Uno-QClaw/releases
Steps:
- Download the
QClaw.zipasset from the v1.0.2 release page - Open Arduino App Lab and connect to your Uno Q
- Go to My Apps in the left sidebar
- Click Create New App, then choose Import App
- Select your downloaded QClaw.zip, the App card appears with the 🦞 icon
- Click the QClaw App Card, then click Run
- Open
http://<uno-q-ip>:7000in your browser, on first launch, QClaw downloads the model weights and brings up the chat interface automatically
Once the chat surface appears, you're talking directly to a local language model running on the Uno Q's QRB2210 processor.
The Terminal Path (For Those Who Prefer It)If you'd rather work from the command line, the terminal install is still supported:
# Download
curl -L -o QClaw.zip https://github.com/laurenvil/Uno-QClaw/releases/download/v1.0.2/QClaw.zip
# Import into Arduino App Lab
arduino-app-cli app import QClaw.zip
# Start
arduino-app-cli app start ~/ArduinoApps/qclawThen open http://<uno-q-ip>:7000 and start chatting.
QClaw App is a direct evolution of the original project released in May 2026. The agentic loop, the pre-router, the eight tools, and the fifteen skills are unchanged from the terminal edition, the App Lab packaging is a new delivery mechanism, not a rewrite. If you built on the original version, your custom skills, modified SOUL.md, and any sketch templates in workspace/sketches/ carry forward directly.
The repository's main-applab branch holds the App Lab Edition source. The original terminal-first main branch remains available and supported under QClaw-v1 and Qclaw-v2 branches.
The QClaw project roadmap points toward deeper App Lab integration: Modulino-specific Bricks that surface sensor data alongside the chat interface, expanded sketch templates for common IoT patterns (MQTT publishing, BLE peripheral, USB HID), and tighter coupling with App Lab's IoT Remote App integration for cloud monitoring of locally-running agent sessions.
Community contributions are welcome at github.com/laurenvil/Uno-QClaw. If you have a Modulino module that QClaw doesn't yet know about, add it. A new skill is as simple as a SKILL.md file and a single regex rule away.
Comments