Run compute on Modal
Modal runs code in the cloud on demand (CPU/GPU), billed to the user's own
Modal account. Like the HPC/Slurm path, the app never handles credentials — you
use the user's installed modal CLI and their token. Prefer local execution or
Slurm first; reach for Modal when the job needs cloud GPUs or elastic scale and
no cluster is available.
1 · Check Modal is ready
Modal must be installed and authenticated (the Settings Cloud compute (Modal)
card shows this). Verify before writing code:
modal --version # installed?
test -f ~/.modal.toml && echo "authenticated" || echo "run: modal token new"
If it is not installed, tell the user to pip install modal; if not
authenticated, ask them to run modal token new in their terminal (it opens a
browser). Do not attempt to create or store tokens yourself.
2 · Write the Modal function into the workspace
Put the script in the workspace so provenance records it. Pin dependencies in
the image so the run is reproducible, and fix any random seed.
# compute.py — run with: modal run compute.py
import modal
app = modal.App("open-science-job")
image = modal.Image.debian_slim().pip_install("numpy==1.26.4", "scipy==1.13.1")
@app.function(image=image, gpu=None, timeout=1800) # set gpu="A10G" etc. if needed
def run(n: int = 1_000_000):
import numpy as np
rng = np.random.default_rng(0) # fixed seed → reproducible
x = rng.standard_normal(n)
return {"n": n, "mean": float(x.mean()), "std": float(x.std())}
@app.local_entrypoint()
def main():
result = run.remote()
print(result) # printed locally; capture it below
3 · Run it and capture the result
modal run executes remotely and streams logs + the local entrypoint's stdout
back. Write the result into a fresh, immutable result directory so it becomes a
traceable artifact and does not overwrite a previous run:
RESULT=results/<job-name>/<YYYYmmdd-HHMMSS>
mkdir -p "$RESULT"
modal run compute.py | tee "$RESULT"/modal_result.txt
For large outputs, have the function write to a Modal Volume and download with
modal volume get, rather than returning big objects. Download every run into
its own RESULT directory; never reuse a recorded output path.
4 · Record the run (reproducibility) — REQUIRED, every time
Modal runs on remote cloud hardware the app can't see, so this call is the ONLY
thing that makes the run exist in Runs. Do it after every completed run —
including quick re-runs. Skipping it loses the run entirely (it shows in neither
the global Runs view nor the session). Record it after it completes (from the
workspace root):
Record it completely: --code once per script that ran, and --output once
per file you captured or downloaded (the streamed result and any
modal volume get files) — not just the summary. Output paths must be under the
fresh RESULT directory; the helper refuses to record paths used by earlier
runs.
python "$XDG_CONFIG_HOME/opencode/skills/modal-run/record_run.py" \
--surface modal --command "modal run compute.py" \
--status <ok|failed> --host "modal:<app-name>" \
--hardware "<the gpu= from @app.function, e.g. A10G — or 'CPU'>" \
--code compute.py --output "$RESULT"/modal_result.txt \
--output "$RESULT"/<each downloaded file> \
--session-id "$(cat .openscience/session.txt 2>/dev/null)"
--session-id attaches the run to this session (empty-safe if the marker's absent).
The environment is reproduced by the modal.Image definition in compute.py
(pinned pip_install + base image — already versioned in the workspace), so
record the GPU/hardware string, not a package list, and no --env-file is
needed. Use --status failed if the run errored.
Rules
- User's account only. Never handle, print, or store Modal tokens.
- Reproducible. Pin image packages and fix seeds; record the script + result
in the workspace (provenance captures them).
- Cost-aware. Modal bills the user — keep
timeout bounded, don't request a
GPU unless the work needs one, and say what you're about to run before a large
job.