Microduck StudioIndependent project

Train your first duck on a Mac

A Mac cannot run Pollen's trainer itself, so the training runs on a graphics card you rent from Hugging Face, and everything around it runs on your Mac. There are two ways in: Microduck Studio, with no terminal, or Pollen's own workshop, which enters the Arena. You do not need a robot, and you do not need to code. On another machine?

The trainer, the challenges and the Arena are Pollen Robotics', built on mjlab and MuJoCo, and Microduck Studio is ours, an independent app. This page is an independent owner's route to both on a Mac, so if a step goes wrong for you, tell us which one.

What you need

Why the card is rented

Why can a Mac not run Pollen's trainer itself? Pollen trains the Microduck with mjlab, which needs an NVIDIA graphics card to train: its README says macOS is supported for evaluation only.

So both routes below send the training to Hugging Face Jobs and do the rest on the Mac: choosing what to train, judging what comes back, watching it walk and publishing it.

With Microduck Studio

This route needs no terminal and no files: Studio is a Mac app, and the same app runs on iPhone and iPad.

  1. Install Apple's free TestFlight app, then join the Microduck Studio beta on your Mac. There is no App Store release yet.
  2. Open Learn and work through it. Its last lesson, Show every tool, turns on the training tools; Settings, then Detail, does the same.
  3. In Studio, under Train and measure: Tune it on this Mac and Search its weights on this Mac improve a network on the Mac itself, with nothing sent anywhere, and Train a network on Hugging Face rents the card and runs Pollen's trainer with a reward you set. Compare, under Make, is where you judge what comes back.

The iPhone and iPad guide takes each of these step by step, the rented training above all; on a Mac they have the same names, with Mac in place of phone.

Studio's training starts from a smaller network distilled from Pollen's own walking network, and fine-tunes that. To train a gait from nothing, or to race in Pollen's Arena, use the workshop.

With Pollen's workshop: git and uv

Pollen's tools run in Terminal, which is in Applications, in Utilities. Start with Apple's command line tools, which include git: a window asks to install them, so choose Install and wait until it says the software was installed.

xcode-select --install

Then your name and email for git, and uv, which installs the right Python and everything the tools need:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
curl -LsSf https://astral.sh/uv/install.sh | sh

Put your own name and email in the git config lines, since git puts them on every change it records and the workshop commits each change before it trains. Then close the Terminal window and open a new one so that it finds uv, and check that uv --version prints a version number.

Open the workshop

Pollen's Microduck Arena races policies against a clock, and every challenge on it has a Train my own robot line. Start with the 2 m Sprint, which asks the duck to walk down a lane as fast as it can without falling. It is one of the Arena's events, and Race in Pollen's Arena says what each one tests. In Terminal:

cd ~
uv run https://pollen-robotics-microduck-arena.hf.space/workshop.py sprint-2m

The first time, it copies Pollen's challenges into ~/microduck-challenges and installs everything, which is a big download but only once. Then it prints a line that starts Microduck workshop: http://127.0.0.1 and opens it in your browser; if no browser opens, open that address yourself.

Leave this Terminal window open: the workshop runs in it until you press Ctrl-C there, so open a new window for anything else.

The workshop's home has a list, Ready to train?, that ticks what is set up: Hugging Face Jobs billing, your fork of the challenges on GitHub, and an NVIDIA card. On a Mac the list has no NVIDIA line, so the billing line is the one that matters, and it and the fork line say how to set them up.

Log in to Hugging Face with the button at the top right. Run the same line on another day and it reopens the same work.

The fork line's Push sends your commits to your fork, so a policy you publish links to the code that trained it. Without it, publishing still works and the link is missing.

To push, git has to be signed in to GitHub, and GitHub's own tool does that: install Homebrew as its page says, then install the tool and log in, choosing HTTPS, and yes when it asks to authenticate Git with your GitHub credentials.

brew install gh
gh auth login

Your first training

  1. On the challenge's page, choose New training, and Hugging Face Jobs. This machine is not an option: the workshop says there is no NVIDIA card here. Leave the knobs (Follow the speed order, Stay upright, Lift your feet) where Pollen set them for your first run.
  2. If you changed a knob, the workshop commits that change first, and then it sends the training to Hugging Face and gives it a ticket. The recipe runs 3000 iterations and saves a checkpoint every 250, and Pollen's notes put it at about 1 to 2.5 hours on the L4, at $0.80 per hour.
  3. Every two minutes the workshop brings the new checkpoints back to your Mac, and scores each one with the Arena's own rules; the training's page replays any of them. Pick 5/5 finishes first, then the lowest time. The best checkpoint is often not the last.
  4. When one is good enough, Publish and compete puts it on your Hugging Face account, in public, and enters it on the Arena, which races it and opens its result.

The time on your Mac is a guide. Pollen's notes say simulations on different processors drift apart after a few seconds, and the Arena times every entry on its own machines.

Closing the workshop does not stop a training on Hugging Face: it runs, and bills, until it ends or reaches its 12-hour limit, $9.60 at the L4's price. To end one sooner, open the workshop again and press Stop on its ticket, or cancel it on your Jobs page at Hugging Face, but a stopped job cannot be resumed.

The bar to beat. Pollen's reference policy scores 4.886 s on the Arena's sprint board and finishes every run.

Claude beside you

Claude Code is Claude working in your terminal: it reads the files, runs commands and explains errors, and in its normal mode it asks before it changes a file or runs anything that could. It comes with Claude Pro and higher, and you install it in a new Terminal window:

curl -fsSL https://claude.ai/install.sh | bash

Close that window and open another, then start Claude Code in the challenges folder:

cd ~/microduck-challenges
claude

The first time, it asks you to log in to your Claude account in your browser.

Pollen wrote the challenges with this in mind: every challenge folder has an AGENTS.md that tells a coding agent which files to change, how to run and judge a training, and the challenge's rules. The 2 m Sprint's tells it never to start a paid job, publish or enter the Arena without your yes, and on a Mac every training is a paid job, so expect it to ask each time. Things to say:

Read what it proposes before you say yes. You decide the goal, the budget and what gets published, and it does the mechanics: that split is Pollen's rule, in the same file.

When something goes wrong

The first install says a package has no wheel for this platform
The Mac has an Intel processor, or a macOS older than 14, and Pollen's tools need Apple silicon and macOS 14 or later.
xcode-select says the tools are already installed
Nothing to do: git is there already.
uv: command not found
The installer adds uv for new windows, so close the Terminal window and open a new one.
The first install stops with a timeout
It downloads a lot at once, so give it longer with export UV_HTTP_TIMEOUT=600 and run the line again. Pollen's README suggests the same setting for its own first install.
Git says "Author identity unknown"
Run the git config lines from git and uv, with your own name and email.
Hugging Face answers 403 when a job starts
The token can log in but not start Jobs, so make a Write one at huggingface.co/settings/tokens, or tick the Jobs permissions on a fine-grained one, then log in with it: uv run hf auth login --force.
Hugging Face Jobs will not start
The account needs a card on file and credit on it, which you add in your billing settings. The workshop's Ready to train? list shows whether billing is set up.

Going further

The challenges train for the Arena's courses. So what about the skills a real Microduck runs, its walk, its stand and its tricks? Those you train in Pollen's microduck_rl, and on a Mac you send each training to Hugging Face with --hf-jobs.

In a new Terminal window, fetch it and log in to Hugging Face. The login says you are in already if you used the workshop's button, and if not, it asks for an access token: make a Write one at huggingface.co/settings/tokens.

cd ~
git clone https://github.com/pollen-robotics/microduck_rl
cd microduck_rl
uv run hf auth login

Then send the walking task to Hugging Face:

uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 4096 --agent.max-iterations 4000 --agent.logger tensorboard --hf-jobs --no-wandb

If you belong to a Hugging Face organization, it first asks which account to bill, so choose yours. Pollen's notes say a gait needs 4000 iterations or more.

It prints the address of a private repository on your account where the checkpoints land, then follows the job's log. Ctrl-C stops following and leaves the job running; the job stops itself after 12 hours at most, $9.60 at the L4's price, and you can cancel it sooner on its page at Hugging Face.

Bring the checkpoints back, with that repository's name in place of <you>/<repo>:

uv run hf download <you>/<repo> --local-dir logs/rsl_rl
ls logs/rsl_rl/velocity/*/

The checkpoints are in a folder under logs/rsl_rl/velocity/ named for the date and time and ending in _velocity. In the commands below, put that folder's name in place of <run> and a checkpoint's number in place of <N>, without the angle brackets.

Watching and exporting run on the Mac itself. To watch a checkpoint in your browser, run play, which prints an address to open and runs until you press Ctrl-C:

uv run play Mjlab-Velocity-Flat-MicroDuck --viewer viser --checkpoint-file logs/rsl_rl/velocity/<run>/model_<N>.pt

Then export it. export.py writes output.onnx, the one safe way from a checkpoint to a robot, because it bakes in the normalizer the policy expects:

uv run scripts/export.py Mjlab-Velocity-Flat-MicroDuck --checkpoint-file logs/rsl_rl/velocity/<run>/model_<N>.pt

To share it, with your Hugging Face username in place of <you>:

uv run publish --onnx output.onnx --repo <you>/microduck-my-walk --kind perpetual --slot walk --no-private

An owner installs it on their robot with sudo robotctl policy load walk and the repository's name, with the robot on its stand the first time, and sudo robotctl policy reset walk puts Pollen's walk back (Pollen's cheat sheet). A clip of it walking at media/preview.mp4 in the repository is what robotctl policy search links beside it (the policy manifest). Studio opens the same output.onnx and shows what is inside it.

Then

The books explain what is happening while it trains. Stuck on a step, or found a better way? Tell us, and say which step.