Microduck Studio

A local control room for developing, simulating, and validating Microduck.

English · 简体中文

AI coding ready: Codex · Claude Code · Cursor Agent · GitHub Copilot CLI

AI startup · Quick start · Monitor · Architecture · Troubleshooting

Microduck Studio brings Microduck simulation, live monitoring, and robot controls into one browser workspace. It connects the existing microduck runtime and microduck_rl simulator.

Open the microduck-dev workspace in a local AI coding agent with repository, terminal, and Docker access, then use this prompt:

Start all Microduck Studio services. First read AGENTS.md and microduck-studio/README.md. Check the
three sibling repositories, Docker, uv, and ports 7801 and 8090. Then run
./scripts/dev-stack.sh from microduck-studio. Wait for "contract probe passed" before reporting the
Studio URL and the status of Studio, robotd, tofd, and MuJoCo. Do not start a training job, and do not
switch or modify the working branches of the sibling repositories.

Use a local session on the development machine so the agent can reach its Docker services.

• Docker with Docker Compose
• git and curl
• Python 3 and uv
• macOS for the default native mode; Linux users should select Docker mode below

The one-command stack uses Docker for robotd, tofd, and Studio. On macOS, Docker Desktop or another compatible Docker runtime must already be running.

Keep the repositories beside one another:

microduck-dev/
├── microduck/          # robot runtime
├── microduck_rl/       # MuJoCo simulation and training
└── microduck-studio/   # browser workspace and service startup

mkdir -p ~/microduck-dev
cd ~/microduck-dev

git clone https://github.com/microai-lab/microduck.git
git clone --branch develop https://github.com/microai-lab/microduck_rl.git
git clone https://github.com/microai-lab/microduck-studio.git

These development forks include the features used by Studio. If the repositories already exist, check their directory layout and keep microduck on a compatible main and microduck_rl on a compatible develop. The launcher does not switch their working branches.

For native macOS background rendering or the desktop Viewer:

cd ~/microduck-dev/microduck_rl
uv sync --extra visualization

Docker mode prepares its rendering environment inside the container instead.

cd ~/microduck-dev/microduck-studio
./scripts/dev-stack.sh

On Linux or for a fully containerized environment, use ./scripts/dev-stack.sh --sim-mode docker --gpu none instead.

Open http://127.0.0.1:8090. In the default native mode, MuJoCo runs in the macOS background and the desktop Viewer stays closed. The first launch downloads the official v8 policies and builds the containers. Wait for the startup check to report:

contract probe passed: runtime source, policies, subscription, movement ... m, stop, disconnect

The startup check includes a brief simulated movement and stop test. Add --skip-control-probe when you want to start without that movement test.

Hold a movement button to move and release it to stop. Directions follow the duck's orientation. Hiding or disconnecting the page also requests a stop. Movement quality, including sideways travel, depends on the selected policy.

The monitor shows missing sensor values as — and displays runtime refusal or disconnection messages. A picked-up robot is marked paused.

Run these commands from microduck-studio:

The robotd and MuJoCo cards show Start or Restart according to their current status. Restarting MuJoCo also reconnects the robot service. If Studio itself is unavailable, restart it from the terminal with ./scripts/dev-stack.sh.

Only --viewer opens a desktop window. Closing that window stops MuJoCo. The default background mode continues running until ./scripts/dev-stack.sh stop; --headless explicitly selects the same background behavior.

In native background mode, --stop-on-browser-close stops only MuJoCo after the last scene page has been disconnected for 10 seconds. Refreshing or reconnecting during that grace period cancels the shutdown.

GPU selection is explicit in the startup arguments. These Linux GPU interfaces are configurable; performance must be checked on the target host. Docker Desktop on macOS cannot use these Linux GPU paths. --gpu applies only to Docker mode; --viewer and --stop-on-browser-close are native options.

XML physics remains the default. To try the optional BAM/backlash scene, use ./scripts/dev-stack.sh --actuator-model bam --scene scene_velstand.xml; this selection is available with either native or Docker rendering.

Choose a scene and click Apply to restart MuJoCo with it. Click Scene beside the selector to copy the selected .xml filename.

Available scenes depend on the local RL repository.

Use the language switch at the top of the page for Chinese or English. The scene card provides these image profiles:

The scene shows the actual received video FPS, image resolution, and simulation time. Image quality, scene complexity, and host load affect frame rate. The default startup target is 1280×720 at 24 FPS; this is a requested target, rather than a fixed output rate.

Open the live visual monitor in the current terminal:

./scripts/dev-stack.sh monitor

Or run it directly with Compose:

docker compose run --rm --no-deps --build robotctl monitor

The stack must already be running.

The 3D view needs a terminal at least 110 columns wide; status and joint tables work in a narrower terminal.

• microduck provides the robot runtime, policies, and safety controls.
• microduck_rl provides MuJoCo simulation and training.
• microduck-studio provides the browser controls, monitoring, and service startup.

1. Run ./scripts/dev-stack.sh status and confirm Studio, robotd, and MuJoCo are ready.
2. Click Enable RL, then try holding a movement control.
3. Use the robotd or MuJoCo card's Start/Restart action if either service is disconnected.
4. If the page is unavailable, run ./scripts/dev-stack.sh again and wait for the startup check.

For service diagnostics:

docker compose ps
docker compose logs -f studio robotd tofd
docker compose run --rm --no-deps robotctl health

./scripts/dev-stack.sh stop
cd ../microduck_rl
uv run --extra visualization mjpython -m mjlab_microduck.sim.body_server --keyframe HOME --port 7801 --render

uv sync --extra dev
cp .env.example .env
uv run microduck-studio

Training jobs are disabled by default. For the optional 64-environment, 5-iteration smoke test, run Studio directly on the host with:

MICRODUCK_STUDIO_ENABLE_JOBS=true uv run microduck-studio

Then use the training smoke-test card on the page.

uv sync --extra dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
node --test tests/test_frontend.mjs

Studio has no authentication. Keep it on 127.0.0.1 or a trusted LAN. Robot safety and motor control remain the responsibility of robotd.

MIT