Compute Instances

Use moi-cli compute to inspect compute specs, worker images, instance configurations, and worker runtime replicas, run instance lifecycle operations (create, update, suspend, resume, retry, preflight-delete, delete), or execute cross-workspace administrative actions when authorized. Complete Configuration and Authentication before running commands; omit --workspace-id when a default workspace is already saved in your local configuration.

Manage workspace compute instance lifecycle

List available compute specs, worker images, and workspace instances first, then read an instance’s configuration and per-worker runtime replica state:

# List available specs, worker images, and workspace compute instances
moi-cli -auth pat -o compute specs --workspace-id "$WORKSPACE_ID"
moi-cli -auth pat -o compute worker-images --workspace-id "$WORKSPACE_ID"
moi-cli -auth pat -o compute list --workspace-id "$WORKSPACE_ID"

# Read instance details (--id) and worker runtime replicas (--compute-resource-id)
moi-cli -auth pat -o compute get --workspace-id "$WORKSPACE_ID" --id "$COMPUTE_RESOURCE_ID"
moi-cli -auth pat -o compute runtime \
  --workspace-id "$WORKSPACE_ID" \
  --compute-resource-id "$COMPUTE_RESOURCE_ID"

Workspace lifecycle subcommands and required flags:

Scenario

Subcommands

Key flags and behavior

Create or update an instance

create, update

create takes --name, --spec-id, --cpu, --memory-gi-b, plus optional replica counts, worker image flags, and --auto-suspend-minutes; update takes --id and submits only explicitly supplied flags (check --help on each subcommand).

Inspect workers and Python dependency limits

runtime, workers, py-deps-limits

Both runtime and workers require --compute-resource-id and report live worker replica states separately from the parent instance status.

Suspend, resume, and retry errors

suspend, resume, retry

Each takes --id. resume requires the instance to be SUSPENDED and retry requires ERROR; upon success the instance resets to IDLE, while actual worker startup is verified separately via runtime.

Preflight check and delete

preflight-delete, delete

Run preflight-delete --id "$COMPUTE_RESOURCE_ID" first to inspect active tasks and workflow bindings before calling delete --id "$COMPUTE_RESOURCE_ID".

# Check active tasks and workflow bindings before deleting an instance
moi-cli -auth pat -o compute preflight-delete \
  --workspace-id "$WORKSPACE_ID" \
  --id "$COMPUTE_RESOURCE_ID"

Warning

In earlier 0.1.0 offline client packages, responses containing non-empty py_requirements_txt or py_requirements_sha Python dependency fields fail strict client model decoding even when server-side suspend, resume, or retry has already taken effect. If this decoding error occurs, inspect actual instance and worker state via the Product HTTP API or obtain a deployment-matched installer from your deployment administrator before re-issuing the command.

Manage compute specs

Identities granted deployment-level compute spec management permissions can inspect and toggle specs with the following subcommands:

# Check whether the current identity holds compute spec management permissions
moi-cli -auth pat -o compute spec-management-permission --workspace-id "$WORKSPACE_ID"

# Enable or disable a compute spec
moi-cli -auth pat -o compute set-spec-enabled \
  --workspace-id "$WORKSPACE_ID" \
  --spec-id "$SPEC_ID" \
  --enabled=true

Create or modify specs with compute create-spec and compute update-spec (both accept --node-placement-file for JSON node placement rules; check --help for full flag lists).

Cross-workspace administrative operations

The admin-* subcommands require the caller identity to be configured as a deployment compute spec administrator (workspace Owner or Genesis admin roles alone do not grant this permission). Here --workspace-id specifies an authenticating workspace accessible to the administrator, while the target instance is selected by its resource ID:

# List compute instances across workspaces in the admin directory (first 50 by default)
moi-cli -auth pat -o compute admin-list --workspace-id "$AUTH_WORKSPACE_ID"

# Inspect worker runtime state as an administrator
moi-cli -auth pat -o compute admin-runtime \
  --workspace-id "$AUTH_WORKSPACE_ID" \
  --compute-resource-id "$COMPUTE_RESOURCE_ID"

# Run preflight deletion checks and submit administrative deletion
moi-cli -auth pat -o compute admin-preflight-delete \
  --workspace-id "$AUTH_WORKSPACE_ID" \
  --id "$COMPUTE_RESOURCE_ID"

moi-cli -auth pat -o compute admin-delete \
  --workspace-id "$AUTH_WORKSPACE_ID" \
  --id "$COMPUTE_RESOURCE_ID"

Admin subcommand

Key flags and behavior

admin-list

Returns the first 50 non-DELETED instances by default. Deployment-matched builds accept repeatable --query-param flags for pagination and target workspace or status filtering; earlier 0.1.0 offline packages expose --workspace-id only—upgrade the client or call the administrative HTTP API in Compute resources when filtering or paginating.

admin-runtime

Pass --workspace-id "$AUTH_WORKSPACE_ID" and --compute-resource-id "$COMPUTE_RESOURCE_ID" to inspect worker replicas.

admin-update

Pass --id and at least one update flag; submits only explicitly provided fields.

admin-suspend, admin-resume, admin-retry

Pass --id; admin-resume requires SUSPENDED and admin-retry requires ERROR, and worker readiness after returning IDLE should be verified via admin-runtime.

admin-preflight-delete, admin-delete

Run admin-preflight-delete --id to verify no active workflow or task bindings remain before calling admin-delete --id.

Warning

compute admin-delete: ok means the server accepted the deletion intent with HTTP 202 while background cleanup continues asynchronously. The CLI has no standalone administrative get subcommand, and admin-list excludes DELETED instances—disappearance from admin-list or a 404 response alone does not confirm physical resource release. Coordinate with platform operators to verify the cleanup pipeline when terminal confirmation is required.

Adopt legacy instance ownership

compute adopt-legacy-ownership records canonical workspace ownership on legacy compute instances through an audited remediation operation restricted to authorized super-administrators:

moi-cli -auth pat -o compute adopt-legacy-ownership \
  --workspace-id "$WORKSPACE_ID" \
  --id "$COMPUTE_RESOURCE_ID"

Because this command mutates instance ownership directly, inspect the instance via get, runtime, or admin-list and confirm a migration window with active workloads beforehand, then re-query instance details and runtime state afterward.

Limitations and notes

  • Creating, scaling, resuming, or retrying compute instances provisions underlying resources and can incur usage charges; suspending or deleting an instance affects active workloads bound to that instance.

  • Top-level instance status (IDLE, RUNNING, SUSPENDED, ERROR) is tracked separately from per-worker replica readiness—check both get and runtime when diagnosing execution issues.

Last updated on