het-agi/collideragent/magnus

Magnus CLI

Magnus executes blueprints on remote GPU/CPU clusters. The CLI is self-documenting — use --help at each level to discover what's available:

magnus --help                          # top-level commands and shortcuts
magnus run --help                      # CLI options for blueprint execution
magnus job --help                      # job inspection and management
magnus blueprint schema <blueprint-id> # parameter schema for a specific blueprint

Setup

pip install "magnus-sdk>=0.6.0"
magnus config                  # check current connection — skip setup if already configured

If not configured, run magnus login (saves to ~/.magnus/config.json, all shells pick up immediately):

magnus login                                      # interactive
magnus login <site> -a <address> -t <token>        # non-interactive (for scripts and agents)

Config resolution order

Do not use environment variables for interactive work. Inline MAGNUS_ADDRESS=... magnus run ... is non-portable and not persisted. If magnus config shows an env-override warning, remove the export lines from your shell profile (.bashrc, .zshrc, or system environment variables on Windows) to let magnus login take effect.

Core Workflow

Run magnus config first to verify your connection. If not configured, use magnus login once — credentials persist across all shells and subsequent commands. Do not inline MAGNUS_ADDRESS/MAGNUS_TOKEN environment variables before each command.

magnus list                           # discover available blueprints
magnus blueprint schema <id>          # inspect parameters, types, defaults
magnus run <id> [--] --key value ...  # execute and wait for result

The -- separator

Divides CLI options (left) from blueprint arguments (right). Optional — without it, all arguments route to the blueprint and CLI options use defaults. See magnus run --help for available CLI options.

FileSecret — automatic file upload

When a blueprint parameter is typed FileSecret, passing a local file path triggers automatic upload. Files and directories both work. Check magnus blueprint schema <id> to see which parameters accept file paths.

Output download (MAGNUS_ACTION)

Blueprints that produce output files write a magnus receive command to MAGNUS_ACTION. With --execute-action true (default), magnus run auto-executes this receive command.

Job Management

magnus job result <job-id>    # structured result (same as magnus run output)
magnus logs <job-id>          # stdout + stderr from cloud execution
magnus status <job-id>        # job status
magnus kill <job-id>          # terminate a running job
magnus jobs                   # list recent jobs with IDs

<job-id> is the absolute job ID printed by magnus run (e.g. abc123). Negative indices also work as a shorthand (-1 = most recent, -2 = second most recent), but they are scoped to your account, not your session — if another agent or session submits a job under the same account, the indices shift. In multi-step pipelines, prefer capturing the job ID from magnus run output and passing it explicitly.

Blueprint results typically contain at minimum success (bool) and message (str).

Error Handling

If magnus run returns a non-success result:

1. magnus job result <job-id> — structured error details
2. magnus logs <job-id> — full execution output
3. Fix and re-run

Jobs continue server-side even if your client disconnects — interrupting magnus run (Ctrl-C) or a network drop only detaches the local client, the job keeps running. Do not re-submit — instead, reconnect:

1. magnus status <job-id> (or sleep 30 && magnus status <job-id> to wait out a transient outage)
2. Once the job shows completed, magnus job result <job-id> to read MAGNUS_RESULT
3. Run the magnus receive command from MAGNUS_ACTION to download outputs

Use magnus kill <job-id> to terminate a job that was submitted with wrong parameters to free up cluster resources.