Gpu Submit
gpu_submitSubmit and run a script on a free cloud GPU for training, fine-tuning, or evals; it packages the project, installs dependencies remotely, and keeps the job running.
Instructions
Run a script on a free cloud GPU (or this Mac for smoke tests). gpu-router packages the project (git-tracked and untracked-but-not-ignored files, plus include; credential files never ship), installs requirements.txt / pyproject.toml deps remotely, picks the provider and returns at once; the job keeps running when this call returns. bundle.left_out lists git-ignored paths that did not ship (with bundle.hint): add code with include, datasets with data.
Use it for training, fine-tuning, evals or anything that needs a CUDA GPU or would take long on the laptop. Do NOT use it for quick CPU work that runs fine locally in seconds.
gpu.yaml in the project root is read first; these arguments override it. Give hours (an honest wall-clock estimate): an agent job with no hours or over 1 hour waits for the user's approval, as does reading Keychain secrets or using over half a provider's remaining quota, and a job still running well past its hours is stopped for approval. Then the result says guidance.needs_approval=true with guidance.tell_user: relay it to the user word for word and end your turn; do not approve, resubmit or switch providers yourself.
Safe to retry: calling it again with the same arguments while that job is still active returns it (submitted=false) instead of starting a second copy; request_id makes that explicit. Returns {"job": {...}, "guidance": {...}, "submitted": true, "bundle": {files, bytes, left_out?, hint?, warnings?}}. job.short_id is the ref for the other tools. States: queued -> routing -> (awaiting_approval) -> provisioning -> running (<-> checkpointing, -> migrating when a session ends and it resumes elsewhere) -> done | failed | cancelled | denied. Outputs the script writes to gpu.output_dir() land in /runs// (job.outputs_dir). Follow guidance.follow (see gpu_status).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | Non-secret environment variables for the job. Secret-looking names or values are refused: secrets go in the Keychain (`gpu secrets set NAME`) and are listed under `secrets:` in gpu.yaml. | |
| gpu | No | GPU type constraint, e.g. T4. Usually omit. | |
| args | No | Arguments passed to the script, e.g. ["--epochs", "10"]. | |
| data | No | Datasets as [NAME=]PATH (relative to project_dir, or absolute) or hf://datasets/... URIs. Uploaded once, cached by content, readable at gpu.data_dir()/NAME on the GPU. | |
| name | No | Short job name for humans. | |
| hours | No | Honest expected wall-clock runtime in hours (e.g. 0.25 for 15 minutes). Agent jobs with no hours or over 1 hour wait for approval, and a job still running well past its hours is stopped for approval. | |
| smoke | No | A quick smoke test: prefers this Mac (MPS) and runs in minutes. | |
| script | No | Script to run, relative to project_dir (e.g. train.py or scripts/train.py). Omit to use gpu.yaml's `script`. A non-.py value runs as a command line, split like a shell would, e.g. `bash jobs/run.sh`. Paths in it and in args are relative to project_dir and must ship (see bundle.warnings). | |
| wait_s | No | Seconds to wait for the job to be placed or to need approval before returning (default 10). | |
| include | No | Paths or globs relative to project_dir that ship even if git ignores them, e.g. ["third_party/", "data/crops/*.png", "experiments/**/out"] (a directory ships whole; nested git repos too). Added to gpu.yaml `include:`. For code and small files; pass datasets as data. Credential files never ship. | |
| verbose | No | Return the full documents (null fields, every event) instead of the trimmed ones. | |
| vram_gb | No | GB of GPU memory the job needs (a hard filter). | |
| provider | No | Pin one provider (kaggle, colab, local, ...). local = this Mac through gpu-router's queue, one job at a time. Usually omit and let gpu-router choose. | |
| request_id | No | Optional id of this submission (e.g. train-yolo-3): calling again with the same request_id returns the same job. Without it, an identical job that is still active is returned instead of a duplicate; a new request_id starts another copy on purpose. | |
| project_dir | Yes | Absolute path of the project directory on this Mac (where the script and gpu.yaml live; inside a git repo the whole repo ships). Example: /Users/me/code/yolo |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||