# Tools

> Quick start:

- Skill: `meta-pytorch/tools` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add meta-pytorch/tools`
- Raw SKILL.md: https://api.skillmd.com/api/skills/meta-pytorch/tools/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: meta-pytorch (https://skillmd.com/u/meta-pytorch)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/meta-pytorch/tools

---

Quick start:

  # Create a job config file (e.g. myjob.py)
  from monarch._src.job.process import ProcessJob
  job = ProcessJob({"hosts": 2})
  job.remote_mount("/path/to/src", mntpoint="/path/to/mnt")
  job.gather_mount("/worker/output", "/local/gathered")

  # Apply (provision) the job — argument is module.attribute import path
  monarch apply myjob.job

  # Run a command on rank 0 (streams output)
  monarch exec python train.py

  # Run on all ranks (output goes to per-rank log files)
  monarch exec --all python train.py

  # Spawn 4 GPU processes per host and run on all of them
  monarch exec --all --per-host gpu=4 python train.py

  # Run a bash script
  monarch exec --script run.sh

  # Open an interactive shell on rank 0
  monarch shell

  # Collect Perfetto traces of actor activity for the next 10 seconds
  monarch profile

  # Collect from an existing MAST job
  monarch profile mast <mast-job-id>

  # Collect from a mesh-admin URL directly
  monarch profile https://<mesh-admin-host>:8265

  # Kill the job when done
  monarch kill

Commands:

  apply   Provision workers from a job config Python file
  exec    Run a command on workers
  shell   Open an interactive shell on one worker
  kill    Kill the active job
  profile Collect job wide perfetto traces of RPC invocations
  context Manage named job contexts
  debug   Connect to the debug server

Job reuse:
  Worker allocation is slow (minutes). Use "monarch exec" to reuse workers
  across runs. Only run "monarch apply" when you need a new allocation.
  Use "--kill" only when you are done with the workers entirely.

exec options:

  Targeting (mutually exclusive; default is --one):
    (default)         Run on rank 0 of the first mesh, stream output
    --all             Run on all meshes and all ranks; output → files
    --mesh NAME       Run on all ranks of the named mesh; output → files
    --point DIM=N,..  Run on a specific coordinate (e.g. host=4,gpu=3), stream output

  --per-host DIM=N    Spawn N processes per host along dimension DIM before
                      executing (e.g. --per-host gpu=4). The environment
                      variables MONARCH_RANK_<DIM> and MONARCH_SIZE_<DIM>
                      are set for each dimension of the actor's rank.

  -e KEY=VALUE        Extra environment variable (repeatable)
  --workdir DIR       Working directory on workers
  --script FILE       Read bash script from FILE (use '-' for stdin)
  --kill              Kill the job after the command finishes

shell options:

  --mesh NAME       Select a mesh (default: first mesh)
  --point DIM=N,..  Select a host coordinate (default: flat rank 0)
  -e KEY=VALUE      Extra environment variable (repeatable)
  --workdir DIR     Working directory on the worker
  --kill            Kill the job after the shell exits