Skip to main content
On the cluster manage page, Help & Docs opens this guide. The Actions menu lets you add nodes or delete the cluster. Launch Slurm on your reserved GPU nodes, connect over SSH, and submit a GPU job. Ornn prepares the selected workers and runs the scheduler and login service. Your reservation remains in Nodes; manage the cluster from Orchestration (/controllers). Submit work from the login node with sbatch and srun. Old /compute/slurm bookmarks now open Orchestration (/controllers), where you create and manage clusters.

Before you start

  • Sign in to an approved organization that owns the reservation.
  • The reservation must be active and have available, eligible nodes.
  • Register an active SSH public key and keep its matching private key on your computer.
  • Install an SSH client. You run Slurm commands after connecting; you do not need Slurm installed on your laptop.
  • Choose Public or Private networking. Private access requires WireGuard. Choose Private if you need a shared filesystem.
  • Save local data before selecting nodes that already have an environment. Review any cleanup confirmation before launch.
Nodes allocated to another cluster cannot be selected. For distributed training, confirm the hosts’ GPU type and interconnect meet your workload requirements; membership alone does not guarantee RDMA performance.
  • Spot VMs cannot join a cluster.
  • Running VMs on your reservation can join as workers, alone or alongside nodes. While a VM is in a cluster, its SSH keys are set aside and its open SSH sessions end; its disk and data stay. The keys come back when the VM leaves the cluster, including any key changes you made in the meantime. Connect through the cluster’s SSH login instead.
  • In a Public cluster, every worker needs its own network address. A VM whose address another worker already uses cannot join; choose a different VM or use Private networking.

Launch the cluster

1

Open Orchestration

Open Orchestration and start a new cluster. Select Slurm.
2

Select nodes and networking

Open Choose available nodes to cluster, select your reservation group, and select the hosts or VMs in the same dropdown. A node count is a worker count, not a GPU count. Only running VMs that are not in another cluster appear.Public exposes the SSH login endpoint over the internet, with SSH key authentication. Private requires the selected organization’s WireGuard network. Configure WireGuard in the launch dialog or the cluster’s Network tab.If the picker is empty, check reservation timing and node availability. Launch On-Demand, when shown, opens a separate VM purchase flow.
3

Launch and wait for access

Check SSH keys attached, or use Add new account key to register a key. Review the selected nodes and any cleanup warning, then click Create cluster. The manage page reports progress while Ornn prepares hosts, joins workers, starts the scheduler, and issues access.Wait for SSH login, Connect, and Host key to appear. A submitted launch or a healthy host alone does not mean the scheduler is ready.
Interactive CLI equivalent:
Replace placeholders with your values. Interactive launch asks you to review exact nodes. Add running VMs with --vms <vm-id>,<vm-id>; use --nodes 0 for a cluster of VMs only. Automation requires complete inputs, explicit consent, and an idempotency key; see ornn help launch.

Launch and manage through the API

You can run the whole Slurm lifecycle over HTTPS with an Ornn API key: create the cluster, wait for it, read its SSH login details, add or remove workers, and tear it down. Jobs still run over SSH with sbatch and srun. The API reference has every request and response schema. The API is REST over HTTPS; there is no gRPC or GraphQL provisioning API. Your organization can run one Slurm cluster at a time, and cannot run a Slurm cluster and a Kubernetes cluster at the same time. A cluster counts until its teardown finishes.

1. Create the cluster

List the hosts on your reservation with GET /v1/orchestrator/nodes?reservation_id=<reservation-id>. Choose hosts whose status is bare-metal, whose controller_id is null, and whose health_readiness.ready is true. Then create the cluster with kind: "slurm" and those node_ids.
Ornn prepares each selected host before it joins: running processes are stopped, the tenant home directory is wiped, and any VM on the host is removed. Save data first. If you omit node_ids, every bare-metal host on the reservation is used.
Slurm logins use your organization’s SSH keys. Omit ssh_key_ids to authorize every active key, or list specific key IDs from GET /v1/organizations/{organization_id}/ssh-keys?status=active. With no active key, the launch returns 409 slurm_ssh_key_required. Leave out node_count, or set it to exactly the number of hosts you list; a mismatch returns 409.
Expect 202 Accepted with the cluster id and state: provisioning. That means the launch was accepted, not that the scheduler is ready. A repeat request for the same reservation returns the existing cluster instead of creating another, and it does not add hosts. This route does not read an Idempotency-Key header; after a timeout, read the cluster list before sending the request again.

2. Wait for the cluster and read its SSH login

Poll GET /v1/orchestrator/controllers?kind=slurm every 10 seconds and select your cluster by controller.id. state moves from provisioning to active once the workers have joined, the scheduler is running, and SSH login has been issued; failed means the launch could not finish, and controller.progress.stages names the stage. Each worker in nodes moves from joining to ready. Then read GET /v1/orchestrator/controllers/{cluster_id}/access. A 404 with slurm_credentials_not_ready means login is not issued yet; keep polling. The response gives login_user, login_host, login_port, a ready-made ssh_command, the login node’s ssh_host_key, and the authorized_key_fingerprints of the keys that can sign in.
The curl loop stops on active or failed; check the state before you continue. The login port is specific to the cluster and is usually not 22. A launch whose workers cannot join is marked failed after about 30 minutes; if your own deadline passes while the cluster is still provisioning, contact Ornn support with the cluster ID instead of launching again.

3. Add or remove workers

Add one host with POST /v1/orchestrator/controllers/{cluster_id}/nodes/{node_id}. A new host normally returns state: cleaning while Ornn prepares it, then appears in the cluster’s nodes as joining and ready. Remove one with DELETE on the same path; the response is state: draining, and the worker leaves nodes once its host confirms cleanup. Both requests are safe to repeat. Confirm the scheduler’s view with sinfo on the login node.
The CLI equivalents are ornn clusters add-node and ornn clusters remove-node. Removing a worker stops the jobs on it and does not cancel its reservation. Ornn does not add workers when jobs are queued; scaling is a call your automation makes against hosts you already reserved.

4. Tear down and confirm

Teardown stops the scheduler, removes SSH login, and interrupts every job. Export data first. Reservation billing continues, and separately provisioned filesystems are not deleted.
Send POST /v1/orchestrator/controllers/{cluster_id}/teardown. The cluster stays in deleting while Ornn waits up to five minutes for workers to confirm cleanup, then it is removed. Repeating the request during teardown returns {"state": "deleting"}. Teardown is complete when the cluster is absent from the cluster list and the access request returns 404 with cluster_not_found; teardown itself then returns 404 with no body. Wait for that before you create another cluster.
The CLI equivalent is ornn clusters teardown <cluster-id> --wait.

Connect over SSH

Copy Connect from the cluster page. Use the displayed user, host, and port; the login port varies by cluster and is not necessarily 22. Compare the first-connection host key with Host key before accepting it.
Run the following commands on the login node. Use it to edit scripts, transfer files, and submit jobs. Run training on allocated workers through the scheduler.

Verify the scheduler and GPUs

sinfo shows available partitions and worker states. Idle workers can accept jobs; allocated workers are busy. For NVIDIA capacity, allocate one GPU and verify it:
For AMD Instinct capacity:
These commands can wait for free resources. A successful result lists the allocated GPU. srun releases this allocation when the command finishes.

Submit and follow a batch job

Save this self-contained NVIDIA test as gpu-smoke.sh on the login node:
Submit it from a directory available to the worker. Prefer a shared filesystem for scripts, logs, and checkpoints; see storage below.
sbatch returning an ID confirms submission. Look for COMPLETED, exit code 0:0, and the expected GPU output to confirm success. A job disappearing from squeue can mean success or failure; check sacct and the log. Cancel only the intended job when needed:
For AMD, replace the GPU directive with #SBATCH --gres=gpu:1 and the command with srun amd-smi list. Use a distinct output name.

Run containers and distributed jobs

Bring an image containing your framework and dependencies. Apptainer and the srun --container-image container workflow are available. For example, on NVIDIA capacity:
Image downloads can take time. Private registries require your own credentials. Do not assume a Python package installed only on the login node is installed on every worker. For a multi-node connectivity check, choose a count within your allocation:
This verifies scheduled tasks, not distributed training performance. Your training script must configure one or more ranks per node, the rendezvous address, compatible GPU libraries, and the right interconnect. Use --gpus-per-node for an explicit per-node allocation; --gpus requests a total for the job. Start with a small distributed run and check logs before using the full allocation. The Slurm user guide explains job and resource commands.

Choose storage

Attached object storage

Open Storage, choose a bucket, select Deploy, and choose the reservation or cluster. Select read-only or read/write access and wait for placement and node acknowledgement. Ornn exposes /home/tenant/volume on the login node and workers. Before relying on it, check both:
Object storage does not provide full POSIX locking or safe simultaneous writes to the same file. Use separate output paths per job or rank. A writable mount is shared with local Linux users; use a read-only attachment when jobs only need to read data.

Shared filesystem

A Private cluster can use a separately provisioned filesystem at /workspace. Contact Ornn to confirm the capacity, tier, region, cost, and network. The console’s shared-filesystem view directs you to Ornn. For CLI provisioning, run these commands on your computer:
The deploy command requests both provisioning and attachment for the reservation. Review storage pricing before confirming, then wait for readiness. Once active, the login and workers use /workspace as their shared home. Verify before submitting a long job:
Copy scripts and data into a shared directory before submitting from it. A directory existing only on the login node can cause a job to fail to start or write logs.
Attaching or detaching storage can restart the login and worker environments and interrupt jobs. Checkpoint first. A Ready storage record is not proof that every worker can read it; test access from scheduled work.

Private access with WireGuard

Install WireGuard on your computer and generate a key pair locally:
Paste only the public key into Create config on the cluster’s Network tab. Download the config and fill its private-key placeholder locally. Keep the generated MTU = 1200 and PersistentKeepalive = 25 settings. The cluster’s Network tab uses the private network selected at launch. You do not need to create another network to add a device. Confirm that the tab shows your cluster’s network before creating a config. Shared (default) means the cluster has no dedicated network selected. A dedicated network that is not active keeps its name and shows its status; Dedicated network (unavailable) means its details could not be loaded. Wait for a pending or provisioning network to become active. Contact support if the network is degraded or unavailable, or if Shared (default) appears when you expected a dedicated network. On Linux with wg-quick installed:
On macOS or Windows, import the completed config into the WireGuard app and activate it before SSH. Use a separate key pair and peer per device. To rotate one, remove the old device peer and generate a replacement. Removing it disconnects that device.

Add or remove workers

Use Add nodes on the cluster manage page to select eligible organization-owned hosts or running VMs from the Target nodes dropdown. Wait for readiness, then use sinfo to confirm the scheduler sees them. Select workers in Nodes and use Remove to release them from the cluster. Removal can interrupt jobs and lose local files. Checkpoint and export data first, then verify remaining workers and jobs with sinfo and squeue. A removed VM keeps running and gets its SSH keys back.

Stop or tear down

In the cluster list, hover over a row or focus it with the keyboard to reveal Delete cluster. On mobile, the delete button is always visible. Select it and confirm to tear down the cluster. Reservation billing continues. From the manage page’s actions menu, use Stop launch while provisioning or Tear down cluster when active. Confirm and wait for cleanup. Teardown stops the scheduler, removes login access, and releases the workers back to their reservations. A failed or torn-down cluster can disappear after cleanup. Launch again from available reserved nodes and copy the new connection details; the old host key or port may no longer apply.
Teardown interrupts jobs and removes the cluster environment. Export local files and checkpoints first. It does not cancel the reserved term or delete separately provisioned storage. Filesystem deletion is a separate destructive action. Do not use ornn filesystems delete as a data-preserving detach; export data first and confirm deletion with Ornn.

Troubleshooting

Use the user and port from Connect and the private key matching a registered public key. Confirm access is ready and check authorized key fingerprints in the cluster’s SSH keys tab. Use ssh -v to see which key your client offers; sanitize logs before sharing them.
Wait for access issuance in launch progress. For Private clusters, activate the matching WireGuard tunnel first. Keep MTU 1200. Check that your local firewall permits the displayed port. If launch fails, record its stage and error before contacting support.
Verify the replacement key against Host key on the current cluster page first. If the change follows an expected relaunch, remove only the old host-and-port entry with ssh-keygen -R '[<login-host>]:<login-port>', then reconnect and verify the new key.
Run squeue -j <job-id> -o '%.18i %.9P %.8j %.8u %.2t %.10M %.6D %R' and scontrol show job <job-id>. Read the reason. Check free GPUs, requested node count, partition, and worker states in sinfo; queued does not mean failed.
Check sacct -j <job-id> --format=JobID,State,ExitCode,Elapsed, then the output file. Verify the working directory exists on workers, the image contains dependencies, and requested resources fit. Local login files are not automatically shared.
Check sinfo, the cluster’s node status, and Observability. For storage, confirm both placement readiness and access from srun. Avoid changing worker services or restarting the scheduler yourself; send support the affected node and job IDs.

Monitor and get help

The cluster’s Observability tab shows host metrics and kernel console logs. Use squeue, sacct, and job output for workload status. Open Support or email support@ornn.com with the reservation and cluster IDs, job ID, failed stage or error, and approximate time. Never send private keys, tokens, or registry credentials.

What’s next

access

Kubernetes access

Prefer container orchestration? Run a managed Kubernetes cluster on your reserved GPUs instead.
ssh-keys

Manage SSH keys

Register the account SSH keys your Slurm logins use.