/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.
- 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.
--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 withsbatch 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 withGET /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.
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.
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
PollGET /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.
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 withPOST /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.
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.
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.
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.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:
srun releases this allocation when the command finishes.
Submit and follow a batch job
Save this self-contained NVIDIA test asgpu-smoke.sh on the login node:
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:
#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 thesrun --container-image container workflow are available. For example, on NVIDIA capacity:
--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:
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:
/workspace as their shared home. Verify before submitting a long job:
Private access with WireGuard
Install WireGuard on your computer and generate a key pair locally: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:
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 usesinfo 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
Permission denied (publickey)
Permission denied (publickey)
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.No SSH details or connection times out
No SSH details or connection times out
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.
Host key changed
Host key changed
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.Job stays Pending
Job stays Pending
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.Job failed or output is missing
Job failed or output is missing
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.Workers are down or a mount is missing
Workers are down or a mount is missing
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. Usesqueue, 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

Kubernetes access
Prefer container orchestration? Run a managed Kubernetes cluster on your reserved GPUs instead.

Manage SSH keys
Register the account SSH keys your Slurm logins use.