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"}. The configured checkpoint and GPU memory determine
how long startup takes.
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. Install the agent package in the export environment as well, 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.ButtonPressPreset1 \
--config-path ./config.yaml --nb-env 1 --nb-branch 1 \
--no-coaching --no-judge --no-randomized
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.
Export the saved run
After generation finishes, from the workspace with the same environment active:
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.
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 |
Next: Inspect the run in the viewer, then read the exported data.