# quackd — give your small robot a brain

> quackd is an open-source Python program that gives a small robot an LLM brain. You state a
> goal in plain language and the model picks one of the robot's own skills at a time until the
> goal is met or is clearly impossible. This page is the community site for the project and for
> the $QUACKD community token.

Source of truth: https://github.com/rokbenko/quackd
Last generated: 2026-09-05

## Status

Nothing here has run on a real robot yet, on any of the five adapters. What works today is the simulator, the mocks, and everything in between.

## How it works

The LLM decides what. A steering loop decides how to get there. The robot's own controllers do
the moving.

- **Reflexes** (the body's own, 50 Hz on both ducks) — The robot's own controllers. Balance, gait and standing up are learned policies running on the robot itself. quackd writes none of this control code.
- **Steering** (10 Hz, quackd process) — Plain Python over the camera. go_to closes the approach loop from what the camera sees, ten times a second, without asking the model. The LLM says “go to the ball”, never “turn 4° left”.
- **Deliberation** (0.2 – 1 Hz, the LLM) — Claude, GPT, Gemini, Grok or a local model. Reads a frame and the robot state, then returns exactly one verb the manifest allows — not a plan. A slow or confused model degrades the task, never the balance.

## Robots supported

- **Microduck** (--robot microduck:sim2d) — A 25 cm, 800 g biped from Pollen Robotics. Simulator + mock; Simulator and mock; 15 verbs. The real one over robotd is verified names only, never run on a duck. Early pre-orders land around Christmas 2026.
- **Open Duck Mini v2** (--robot open_duck:bridge) — A 42 cm 3D-printed biped you can build yourself. Daemon, over loopback; Protocol runs against the real on-robot daemon; 11 verbs. quackd ships this duck’s own daemon, and the protocol is exercised against it over loopback in CI — so everything except the duck is tested. No kick, so it scouts instead.
- **Reachy Mini** (--robot reachy_mini:sim2d) — A stationary expressive head, no legs. Simulator + mock; Simulator and mock; 9 verbs. Never offered kick or go_to — a head can only look, so search_scan sweeps the neck. The real SDK path is verified names only, never run on a head.
- **LeRobot arm** (--robot lerobot:mock) — An SO-101 class desktop arm. Mock only; Offline mock; 7 verbs. pick is one intent the arm’s own learned policy executes, and appears only when a policy is loaded. The real backend is verified names only, never run on an arm.
- **Any ROS base** (--robot rosbridge:mock) — Any wheeled base that takes a Twist. Mock only; Offline mock; 7 verbs. Camera verbs appear only when the address names an image topic. The real backend is verified names only, never run against a bridge.

## Verbs

- **Core**: observe, report_state, stop, say, move, go_to, search_scan, approach_and — Offered only when a body’s manifest has what they need — a camera, a twist intent, a sound intent.
- **Microduck**: sit, stand, stand_up, kick, grab, gaze, quack — One per behaviour the robot already ships with, each an intent its own controllers execute.
- **Reachy Mini**: gaze, express, play_sound, wake_up — wake_up moves every joint, so it is gated behind a human yes.
- **LeRobot arm**: move_joints, gripper, place, pick — Confirm-gated, and present only when a policy is loaded.

## Safety

- **Allowlist** — A verb outside the robot’s manifest does not exist. The model never sees it.
- **Budgets** — Max steps, max minutes, max model calls. The run stops when they run out.
- **Confirm gates** — Named verbs stop and wait for a human yes before the body moves.
- **Heartbeat & kill switch** — Ctrl+C or q. stop always means stop, never collapse — quackd never sends a relax or torque-off command to a biped that is standing up.

## Model providers

- Claude (--provider anthropic)
- OpenAI (--provider openai)
- Gemini (--provider gemini)
- Grok (--provider grok)
- Ollama (--provider ollama) — runs locally, no API key
- vLLM (--provider vllm) — runs locally, no API key
- llama.cpp (--provider llamacpp) — runs locally, no API key
- LM Studio (--provider lmstudio) — runs locally, no API key
- Any OpenAI-compatible (--provider local) — runs locally, no API key
- Scripted (--provider fake) — runs locally, no API key

## Try it

### No API key needed

```bash
uvx quackd run find-and-kick --provider fake
```

The bundled 2D simulator and the scripted pilot. Writes a GIF and a full transcript.

### Drive it from Claude

```bash
claude mcp add quackd -- uvx quackd serve-mcp --robot microduck:sim2d
```

Then just chat: “find the ball and kick it”. Same rules as the command line.

### A duck you can build

```bash
uvx quackd run open-duck-scout --provider fake
```

An Open Duck Mini v2 finds the ball and walks up to it. It has no kick.

### Your own model, no key

```bash
uvx --from "quackd[openai]" quackd run find-and-kick --provider ollama --model qwen3:8b
```

Local models through Ollama, vLLM, llama.cpp or LM Studio.

## A .duck task file

```markdown
---
duck: 0
name: find-and-kick
description: Search the area for a ball, walk to it, kick it.
verbs:
  allow: [search_scan, walk_to, kick, quack, get_frame, stop]
  confirm: []                 # verbs that ask a human y/N first
budgets: {max_steps: 40, max_minutes: 5, max_llm_calls: 40}
success:
  - Ball displaced more than 0.3 m in sim, or human confirms.
abort_when: [Battery below 15%, Same verb fails 3 times in a row]
persona: Determined and cheerful. Quack once when you succeed.
---
# Task
Find the ball and kick it.
```

## Limitations

- **Nothing has run on a real robot.** Not one of the five adapters, not once. microduck:jsonrpc, open_duck:bridge, reachy_mini:sdk, lerobot:real and rosbridge:ws spell every upstream name from upstream source at a pinned commit, and have only ever talked to fakes.
- **Three starters have never been finished by any pilot.** patrol-and-quack runs to its budget on every seed from 0 to 9. follow-me and fetch have no scripted strategy at all — the pilot declares success after two steps without attempting the task — and no model run has been recorded for either.
- **The simulator is a cartoon on purpose.** It tests the agent loop, not physics. It will not tell you whether a gait works.
- **The hero run is the scripted pilot, not a model.** The repository was built without an API key. The four cloud code paths are implemented and tested against stubbed SDK clients.
- **Memory is a file, not a learning system.** Each robot keeps the notes a pilot saved and one line per earlier run. No embeddings, no search, no sharing between bodies, and nothing the executor ever trusts.
- **Learned verbs are v2.** The registry hook exists today. The training loop does not.
- **Flock mode is simulator-only.** Two choreographies, exactly two roles (spotter and kicker), and an Open Duck cannot join one yet.
- **Success is the model’s own claim on a solo run.** In the simulator the tests also check ground truth, and a flock’s success needs a member’s report and the world to agree. On hardware, you check.
- **Local model quality is unmeasured.** One contributor has run this against a local server — Qwen 2.5 Coder 14B on LM Studio, two seeds — and no transcript from it is in the repository.

## FAQ

### What is quackd?

quackd is an open-source Python program that gives a small robot an LLM brain. You state a goal in plain language and the model picks one of the robot’s own skills at a time — look around, walk to something, kick it — until the goal is met or is clearly impossible. It works with Claude, OpenAI, Gemini, Grok, or a local model through Ollama, vLLM, llama.cpp or LM Studio.

### Do I need a robot to try quackd?

No. A 2D simulator ships with the package and runs on any laptop. Install uv and Python 3.11 or newer, then run: uvx quackd run find-and-kick --provider fake. That uses a scripted pilot, so it needs no API key, and it writes a GIF and a full transcript of every run.

### Which robots does quackd support?

Five adapters ship today: the Microduck from Pollen Robotics, the Open Duck Mini v2 you can 3D print and build yourself, the Reachy Mini head, an SO-101 class arm through LeRobot, and any wheeled base that accepts a Twist over rosbridge. Each robot declares a manifest, and the model is only ever offered the verbs that manifest declares.

### Has quackd run on a real robot?

Not yet, on any of the five adapters. What works today is the bundled simulator and offline mocks. The Open Duck Mini v2 is the closest to a first real run, because quackd ships that robot’s own daemon and the protocol is exercised against it over loopback in CI — so everything except the duck itself is tested.

### Can I control a robot from Claude?

Yes. quackd includes an MCP server, so Claude Code or Claude Desktop can drive one robot or a fleet interactively under the same safety rules as the command line. Add it with: claude mcp add quackd -- uvx quackd serve-mcp --robot microduck:sim2d.

### What is a .duck file?

A .duck file is a task written as a contract plus instructions, shaped like a SKILL.md. The YAML frontmatter is enforced by quackd — which verbs are allowed, which need a human to confirm, step and time budgets, success criteria and abort rules. The Markdown body is what the model reads. Ten of them ship with the package.

### How does quackd stop the model doing something dangerous?

A safety executor outside the prompt enforces the contract: an allowlist, parameter validation, confirmation gates, step and time budgets, abort rules, preconditions and a heartbeat with a kill switch. A verb that is not in the robot’s manifest does not exist, so the model cannot invent one, and stop always means stop rather than going limp.

### Is quackd free and open source?

Yes. quackd is licensed Apache-2.0 and published on PyPI. It has no paid tier and no token requirement, and it never needs $QUACKD to run.

### What is the $QUACKD token, and does it fund quackd?

It is a community token on Solana with no utility. It does not fund development, and it is not issued by or endorsed by the open-source quackd project. It grants no ownership, no revenue, no governance and no claim on the software. Tokens like this are extremely volatile and illiquid, so assume it can go to zero. Nothing on this page is financial advice.

### Where does the $QUACKD price on this page come from, and where can I trade it?

The token trades on PumpSwap and is listed on pump.fun and DexScreener; both are linked from the token section. The price here is fetched live from the public DexScreener API in your browser and refreshes about once a second. It is not stored or snapshotted, so if the feed is unavailable the page shows nothing rather than an old number. Prices move fast and can be wrong the moment you read them — always verify the contract address independently.

## The $QUACKD token

Contract (Solana): GMogeMjrWFaEceasCPathoibjAh8qwhTC3Chw4Bfpump
Coin page: https://pump.fun/coin/GMogeMjrWFaEceasCPathoibjAh8qwhTC3Chw4Bfpump
Chart and live pair: https://dexscreener.com/solana/3uq3pghifukwoscavukwkn96luzlq31kle2zwzafwk7l

$QUACKD is a community token on Solana with no utility. It is not issued by, affiliated with, or endorsed by the open-source quackd project, Pollen Robotics, Hugging Face or the Open Duck Mini project. It is not a security and nothing here is an offer of one. It grants no ownership, no revenue, no governance, and no claim on the software, its name or its roadmap, and it does not fund development. Tokens like this are extremely volatile and illiquid: assume it can go to zero. Nothing here is financial advice. Prices shown on this page are fetched live from a third party and may be wrong or out of date. Verify the contract address yourself — never from a reply or a DM — and do your own research.

## Links

- Repository: https://github.com/rokbenko/quackd
- Documentation: https://github.com/rokbenko/quackd#readme
- Releases: https://github.com/rokbenko/quackd/releases
- PyPI: https://pypi.org/project/quackd/
- Robot status matrix: https://github.com/rokbenko/quackd/blob/main/docs/adapter-status.md
- Contributing: https://github.com/rokbenko/quackd/blob/main/CONTRIBUTING.md