modal

Use Modal for GPU/CPU remote compute beyond what the modal_run tool covers — Volumes, Secrets, Queues, deployed apps/endpoints.

SKILL.md

GitHub

modal

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 credentials modal_run uses.

  • The modal CLI (ships with the modal Python 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 --version
    

    uvx modal ... needs no install step at all (fetches and runs on demand) — reach for uv tool install modal only if a task will call modal many times and the per-call uvx overhead actually matters.

  • Modal is cloud-only — there is no local dev mode; every modal CLI 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_run loads the modal npm SDK from the profile when present. Otherwise it installs a pinned copy into $DSH_HOME/modal-sdk on first use and loads it immediately — do not add the SDK to the profile or restart dsh just to make modal_run work.
  • ACADEMIC_HARNESS_MODAL_SKIP_INSTALL=1 disables 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_BUILDS for cbor-extract and protobufjs (optional native deps). Academic Harness already writes allowBuilds: {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's pnpm-workspace.yaml. Do not put allowBuilds in academic-harness/package.json — pnpm ignores dependency-level build policy for supply-chain safety.
  • Prefer denying those builds (false); cbor-x has a JS fallback and Modal works without them. Avoid pnpm 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 use runpod_run/vastai_run or 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): the modal CLI 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.