Launch Your First Generation
Start after installation and
configuration. Use four terminals so service logs remain
visible. The commands assume the venv setup; with Conda, use conda activate magma
instead of source .venv/bin/activate.
Terminal 1 — planner
cd ~/magma-workspace/magma-planner-mplib
bash scripts/launch_planner.bash -p 8000
Wait for Uvicorn to report startup. The script builds and starts the container; keep it running. If you chose the native planner installation, use its launch command instead. Start only one planner on port 8000.
Terminal 2 — agent
cd ~/magma-workspace
source .venv/bin/activate
full-history-agent --config ./agent.json
Wait for model loading to finish. In another terminal, check readiness:
curl --fail http://localhost:8888/health
Expect {"status":"ready"}. With the quickstart configuration, this loads Starter
MAGMA through the magma client. The first launch downloads its tokenizer and
weights; later launches reuse the cache. Download speed and GPU memory affect
startup time.
If you chose another provided agent,
use its launch command here and keep magma_agent_address pointed at that server.
You can run the agent server on another machine or in a container if your local GPU has insufficient memory. Set magma_agent_address to a URL reachable from GEN. To export a full-history run, also install its package in the export environment so its local exporter is available.
Terminal 3 — viewer
cd ~/magma-workspace
source .venv/bin/activate
magma-gen viewer --output-dir ./output
Open http://127.0.0.1:8900. Start the viewer before generation for live updates. The viewer and generator must use the same output directory.
Terminal 4 — generation
cd ~/magma-workspace
source .venv/bin/activate
magma-gen run first_run --preset press_button.ButtonPressOrdered \
--config-path ./config.yaml --nb-env 1 --nb-branch 1 \
--no-coaching --no-judge --no-randomized \
--sequence_of_buttons sw0,sw1 --instruction "Press sw0 then sw1."
Use a new run name each time: an existing target directory can be cleared by the
launcher. Data is saved under ~/magma-workspace/output/first_run. Select the run
in the viewer to inspect decisions and tool results. The --gui option, if used,
opens the simulation window; it is separate from the graph viewer.
This first run checks the service connections and simulation. It has no semantic answer judge or coaching backend, and a completed run does not guarantee a successful task. For data collection with these features, follow backend configuration.
The preset parameters request sw0 followed by sw1, then a completion
message. List-valued preset arguments use comma-separated values, as in
--sequence_of_buttons sw0,sw1. To submit a correction yourself, follow
Coach mode in the viewer on a new run with
coaching enabled.
Export the saved run
For a full-history run, after generation finishes, use the same environment:
magma-gen export output/first_run --agent full-history-agent
The local exporter selects eligible examples from the saved graph. A failed or short run may contain no eligible examples. It does not require the agent server to remain running. See export for output files and selection rules. Other agents need their own matching exporter; GPT and Gemini currently provide inference only.
Stop and troubleshoot
Stop the agent and viewer with Ctrl+C in their terminals. Stop the planner with
docker stop magma_mplib from another terminal.
| Problem | Check |
|---|---|
| Agent connection refused | Model loading completed; /health succeeds; port matches config |
| Planner connection refused | Docker container is running on port 8000 |
| MPLib dependency conflict | Planner was installed in the generation environment; use Docker or a separate environment |
| CUDA/Vulkan or model memory error | Drivers, checkpoint size, and GPU memory remaining for simulation |
| Exporter not found | full-history-agent was installed in the same environment as MAGMA-GEN |
| Viewer is empty | Same workspace/output path; viewer started before the run; refresh after completion |
| Coach mode is unavailable | Active run, updated full-history agent with correction support, coaching enabled, neither --no-judge nor --no-coaching |
| Agent metadata is incompatible | Upgrade Core and the agent together, then restart the agent server |
Next: Inspect the run in the viewer, then read the exported data.