modal
Use Modal for GPU/CPU remote compute beyond what the modal_run tool covers — Volumes, Secrets, Queues, deployed apps/endpoints.
SKILL.mdskills/modal/SKILL.md
GitHubmodal
Load this before any Modal task that is more than "run one command remotely and get the result back" — that narrower case is already covered by the built-in modal_run tool (upload inputs, run command on a remote CPU/GPU instance, download outputs, always terminates the instance; pass volume_name to mount a persistent Modal Volume at /workspace).
Reach beyond modal_run — via the bash tool and the modal CLI — for anything it doesn't do: deploying a persistent app or web endpoint, managing a modal.Volume/modal.Secret/modal.Queue/modal.Dict directly, hot-reloading a Modal app during development, or inspecting logs/billing for an existing deployment.
Modal also ships official agent skills and reference docs through the CLI (modal skills install --claude -g -y, modal skills show); install them only if a task needs the full upstream guide, since this brief plus the bundled modal-usage catalogue skill already cover the common paths.
Prerequisites
MODAL_TOKEN_ID/MODAL_TOKEN_SECRET(Settings -> Academic Harness API keys, or env) — same credentialsmodal_runuses.The
modalCLI (ships with themodalPython package). Install it yourself if it's missing — don't ask the user to do it:if ! command -v modal >/dev/null 2>&1; then uvx modal --version # run ad hoc per call, no persistent install needed # or, for a persistent CLI across a long session: uv tool install modal fi modal --versionuvx modal ...needs no install step at all (fetches and runs on demand) — reach foruv tool install modalonly if a task will callmodalmany times and the per-calluvxoverhead actually matters.Modal is cloud-only — there is no local dev mode; every
modalCLI call needs network access and a configured token.
Working with the CLI
The CLI surface moves faster than any static doc — run modal --help / modal <command> --help and trust that over anything below, and check modal changelog --since <date> if something looks newer than expected:
modal --version # confirm the SDK/CLI version in use
modal run <file>::<fn> # run a Modal function or local entrypoint once
modal deploy <file> # deploy a persistent app
modal serve <file> # hot-reload dev server for web endpoints
modal shell <file> # interactive shell inside a Modal container
modal volume list / get / put # manage a modal.Volume (persistent storage across runs)
modal secret list / create # manage modal.Secret objects
modal app list / logs <app> # inspect deployed/running apps
modal billing # workspace billing info
Async Python against the SDK should use Modal's .aio() interface (e.g. await modal.Function.remote.aio(...)) rather than wrapping sync calls.
Troubleshooting modal_run and its SDK
modal_runloads themodalnpm SDK from the profile when present. Otherwise it installs a pinned copy into$DSH_HOME/modal-sdkon first use and loads it immediately — do not add the SDK to the profile or restart dsh just to makemodal_runwork.ACADEMIC_HARNESS_MODAL_SKIP_INSTALL=1disables that managed install. Then the SDK must be installed into the profile explicitly (dsh plugin --profile <profile> add modal) and dsh restarted.- Under pnpm 11, installing the SDK can exit nonzero with
ERR_PNPM_IGNORED_BUILDSforcbor-extractandprotobufjs(optional native deps). Academic Harness already writesallowBuilds: {cbor-extract: false, protobufjs: false}into every profile that depends on it. If a profile still reports the error, add those two keys to that profile'spnpm-workspace.yaml. Do not putallowBuildsinacademic-harness/package.json— pnpm ignores dependency-level build policy for supply-chain safety. - Prefer denying those builds (
false);cbor-xhas a JS fallback and Modal works without them. Avoidpnpm approve-builds --all, which would approve every pending script rather than these two. - A failed managed install surfaces as
sdk_install_failed; report it and userunpod_run/vastai_runor the manual install path rather than retrying in a loop.
Choosing a lane
- One-shot command on remote compute, with the plugin handling upload/download/cleanup:
modal_run. - Persistent storage across multiple calls, a deployed endpoint, or anything CLI/SDK-native (Volumes, Secrets, Queues, Dicts,
deploy/serve): themodalCLI directly.
Always terminate/clean up what you created for a one-off task; leave deployed apps running only when the user actually wants a persistent endpoint.