Jobs

Back to the MCP tool reference.

run_job

Start a policy-authorized job; direct secret values are forbidden. Mount item schemas, included here for MCP clients that do not expand JSON Schema references: - storage_volumes: {storage, container_path, read_only=false} - disk_volumes: {disk, container_path, read_only=false} - secret_files: {secret, container_path} storage and disk accept short references or exact same-context URIs. secret must be a secret: reference. secret_env maps an environment variable name to a secret: reference; env accepts non-sensitive literal values only.

Operation type: Write

Annotations: read-only false, destructive false, idempotent false, open-world true

Input schema:

{
  "$defs": {
    "DiskVolumeInput": {
      "properties": {
        "container_path": {
          "title": "Container Path",
          "type": "string"
        },
        "disk": {
          "description": "Disk URI/reference",
          "title": "Disk",
          "type": "string"
        },
        "read_only": {
          "default": false,
          "title": "Read Only",
          "type": "boolean"
        }
      },
      "required": [
        "disk",
        "container_path"
      ],
      "title": "DiskVolumeInput",
      "type": "object"
    },
    "SecretFileInput": {
      "properties": {
        "container_path": {
          "title": "Container Path",
          "type": "string"
        },
        "secret": {
          "description": "secret: reference only; never a secret value",
          "title": "Secret",
          "type": "string"
        }
      },
      "required": [
        "secret",
        "container_path"
      ],
      "title": "SecretFileInput",
      "type": "object"
    },
    "StorageVolumeInput": {
      "properties": {
        "container_path": {
          "title": "Container Path",
          "type": "string"
        },
        "read_only": {
          "default": false,
          "title": "Read Only",
          "type": "boolean"
        },
        "storage": {
          "description": "Storage URI/reference, never a credential",
          "title": "Storage",
          "type": "string"
        }
      },
      "required": [
        "storage",
        "container_path"
      ],
      "title": "StorageVolumeInput",
      "type": "object"
    }
  },
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "command": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Command"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Description"
    },
    "disk_volumes": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/DiskVolumeInput"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Disk Volumes"
    },
    "energy_schedule": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Energy Schedule"
    },
    "entrypoint": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Entrypoint"
    },
    "env": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Env"
    },
    "http_auth": {
      "default": true,
      "title": "Http Auth",
      "type": "boolean"
    },
    "http_port": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Http Port"
    },
    "image": {
      "title": "Image",
      "type": "string"
    },
    "life_span_seconds": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Life Span Seconds"
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Name"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "preset": {
      "title": "Preset",
      "type": "string"
    },
    "priority": {
      "anyOf": [
        {
          "enum": [
            "low",
            "normal",
            "high"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Priority"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "restart_policy": {
      "default": "never",
      "enum": [
        "never",
        "on-failure",
        "always"
      ],
      "title": "Restart Policy",
      "type": "string"
    },
    "schedule_timeout_seconds": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Schedule Timeout Seconds"
    },
    "scheduler_enabled": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Scheduler Enabled"
    },
    "secret_env": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Secret Env"
    },
    "secret_files": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/SecretFileInput"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Secret Files"
    },
    "storage_volumes": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/StorageVolumeInput"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Storage Volumes"
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tags"
    },
    "wait_for_jobs_quota": {
      "default": false,
      "title": "Wait For Jobs Quota",
      "type": "boolean"
    },
    "workdir": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Workdir"
    }
  },
  "required": [
    "image",
    "preset"
  ],
  "title": "run_jobArguments",
  "type": "object"
}

Output schema:

{
  "additionalProperties": true,
  "title": "run_jobDictOutput",
  "type": "object"
}

list_jobs

List jobs using context and bounded status/name/tag/owner/time filters.

Operation type: Read-only

Annotations: read-only true, destructive false, idempotent true, open-world true

Input schema:

{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "limit": {
      "default": 20,
      "title": "Limit",
      "type": "integer"
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Name"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "owners": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Owners"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "since": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Since"
    },
    "statuses": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Statuses"
    },
    "tags": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tags"
    },
    "until": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Until"
    }
  },
  "title": "list_jobsArguments",
  "type": "object"
}

Output schema:

{
  "additionalProperties": true,
  "title": "list_jobsDictOutput",
  "type": "object"
}

get_job

Get one job and its resolved context.

Operation type: Read-only

Annotations: read-only true, destructive false, idempotent true, open-world true

Input schema:

{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "get_jobArguments",
  "type": "object"
}

Output schema:

{
  "additionalProperties": true,
  "title": "get_jobDictOutput",
  "type": "object"
}

exec_job

Execute one non-interactive command in an owned running job. The executable and argument list are shell-quoted separately; no stdin or TTY is exposed. Output is duration/byte bounded and credential-redacted. Use mounted secrets or secret environment references instead of command arguments for credentials.

Operation type: Write

Annotations: read-only false, destructive false, idempotent false, open-world true

Input schema:

{
  "properties": {
    "arguments": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Arguments"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "executable": {
      "title": "Executable",
      "type": "string"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "max_output_bytes": {
      "default": 100000,
      "title": "Max Output Bytes",
      "type": "integer"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "timeout_seconds": {
      "default": 60,
      "title": "Timeout Seconds",
      "type": "number"
    }
  },
  "required": [
    "job_id",
    "executable"
  ],
  "title": "exec_jobArguments",
  "type": "object"
}

Output schema:

{
  "additionalProperties": true,
  "title": "exec_jobDictOutput",
  "type": "object"
}

start_job_port_forward

Start a loopback-only background forward to one running owned job. Forwarded bytes never enter MCP results. The listener remains active until stop_job_port_forward is called or the MCP server exits.

Operation type: Write

Annotations: read-only false, destructive false, idempotent false, open-world true

Input schema:

{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "local_port": {
      "title": "Local Port",
      "type": "integer"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "remote_port": {
      "title": "Remote Port",
      "type": "integer"
    }
  },
  "required": [
    "job_id",
    "local_port",
    "remote_port"
  ],
  "title": "start_job_port_forwardArguments",
  "type": "object"
}

Output schema:

{
  "additionalProperties": true,
  "title": "start_job_port_forwardDictOutput",
  "type": "object"
}

list_job_port_forwards

List active forwards owned by this MCP process and exact context.

Operation type: Read-only

Annotations: read-only true, destructive false, idempotent true, open-world true

Input schema:

{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "title": "list_job_port_forwardsArguments",
  "type": "object"
}

Output schema:

{
  "additionalProperties": true,
  "title": "list_job_port_forwardsDictOutput",
  "type": "object"
}

stop_job_port_forward

Stop one exact background forward owned by this MCP process.

Operation type: Write

Annotations: read-only false, destructive false, idempotent false, open-world true

Input schema:

{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "forwarding_id": {
      "title": "Forwarding Id",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "forwarding_id"
  ],
  "title": "stop_job_port_forwardArguments",
  "type": "object"
}

Output schema:

{
  "additionalProperties": true,
  "title": "stop_job_port_forwardDictOutput",
  "type": "object"
}

wait_for_job

Poll until terminal state, always bounded by timeout_seconds.

Operation type: Read-only

Annotations: read-only true, destructive false, idempotent true, open-world true

Input schema:

{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "poll_interval_seconds": {
      "default": 2,
      "title": "Poll Interval Seconds",
      "type": "number"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "timeout_seconds": {
      "default": 300,
      "title": "Timeout Seconds",
      "type": "number"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "wait_for_jobArguments",
  "type": "object"
}

Output schema:

{
  "additionalProperties": true,
  "title": "wait_for_jobDictOutput",
  "type": "object"
}

get_job_logs

Read a bounded log prefix with explicit timeout and truncation metadata.

Operation type: Read-only

Annotations: read-only true, destructive false, idempotent true, open-world true

Input schema:

{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "max_bytes": {
      "default": 32768,
      "title": "Max Bytes",
      "type": "integer"
    },
    "max_lines": {
      "default": 1000,
      "title": "Max Lines",
      "type": "integer"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "timeout_seconds": {
      "default": 30,
      "title": "Timeout Seconds",
      "type": "number"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "get_job_logsArguments",
  "type": "object"
}

Output schema:

{
  "additionalProperties": true,
  "title": "get_job_logsDictOutput",
  "type": "object"
}

get_job_telemetry

Collect a bounded telemetry summary and optionally bounded raw samples.

Operation type: Read-only

Annotations: read-only true, destructive false, idempotent true, open-world true

Input schema:

{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "include_raw": {
      "default": false,
      "title": "Include Raw",
      "type": "boolean"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "max_samples": {
      "default": 10,
      "title": "Max Samples",
      "type": "integer"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "timeout_seconds": {
      "default": 10,
      "title": "Timeout Seconds",
      "type": "number"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "get_job_telemetryArguments",
  "type": "object"
}

Output schema:

{
  "additionalProperties": true,
  "title": "get_job_telemetryDictOutput",
  "type": "object"
}

bump_job_life_span

Extend a job lifespan under full or owned managed policy.

Operation type: Write

Annotations: read-only false, destructive false, idempotent false, open-world true

Input schema:

{
  "properties": {
    "additional_seconds": {
      "title": "Additional Seconds",
      "type": "number"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "job_id",
    "additional_seconds"
  ],
  "title": "bump_job_life_spanArguments",
  "type": "object"
}

Output schema:

{
  "additionalProperties": true,
  "title": "bump_job_life_spanDictOutput",
  "type": "object"
}

send_job_signal

Send the SDK's graceful signal under full or owned managed policy.

Operation type: Write

Annotations: read-only false, destructive false, idempotent false, open-world true

Input schema:

{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "send_job_signalArguments",
  "type": "object"
}

Output schema:

{
  "additionalProperties": true,
  "title": "send_job_signalDictOutput",
  "type": "object"
}

save_job_image

Save an owned job filesystem to a policy-authorized image target.

Operation type: Write

Annotations: read-only false, destructive false, idempotent false, open-world true

Input schema:

{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "image": {
      "title": "Image",
      "type": "string"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "job_id",
    "image"
  ],
  "title": "save_job_imageArguments",
  "type": "object"
}

Output schema:

{
  "additionalProperties": true,
  "title": "save_job_imageDictOutput",
  "type": "object"
}

kill_job

Kill a job under full or owned managed policy.

Operation type: Destructive write

Annotations: read-only false, destructive true, idempotent true, open-world true

Input schema:

{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "job_id": {
      "title": "Job Id",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "job_id"
  ],
  "title": "kill_jobArguments",
  "type": "object"
}

Output schema:

{
  "additionalProperties": true,
  "title": "kill_jobDictOutput",
  "type": "object"
}