This guide walks you through the steps you need to take to start running experiments on the COSMOS testbed. Each step links to the dedicated page with the full instructions, screenshots, and troubleshooting tips.
In a hurry? Your first hour on the testbed is the same journey condensed into seven short steps — register, key, reserve, console, image, experiment, collect.
Already have an ORBIT account? You can skip steps 1 and 2 — your existing credentials work on COSMOS too.
COSMOS is not a single homogenous pool of machines — it's a collection of domains, each one a self-contained slice of the testbed serving a different purpose. Examples include the Grid (WINLAB's indoor 20 × 20 radio room), BED (the West Harlem rooftop deployment), small sandboxes (sb4–sb7, sb9, plus sb1.cosmos and sb2.cosmos) for trying things before scaling up, the Weeks Hall advanced-manufacturing site, and several reserved project subdomains. Every domain is independent: it has its own hardware inventory, its own network space, and its own scheduler entry. The full catalogue is at Hardware → Domains.
Inside each domain you'll typically find:
Each domain has a single console host at console.<domain>.<root-domain> — for example console.sb1.cosmos-lab.org, console.bed.cosmos-lab.org, or console.grid.cosmos-lab.org. The console is your primary access point into the domain: it's where you run the omf command-line tools, where you mount NFS-shared storage, and where you reach the nodes / servers / devices on the domain's internal network.
You always log in to the console via SSH from your local machine:
ssh <your-username>@console.<domain>.<root-domain>
# e.g.
ssh alice@console.sb1.cosmos-lab.org
ssh alice@console.bed.cosmos-lab.org
ssh alice@console.grid.cosmos-lab.org
SSH lands you on the console; from there you control everything in that domain for the duration of your reservation.
Register through the COSMOS portal: pick your group, supply your contact info, then have your PI approve the request. New users go through an email-verification round-trip before the account is activated.
→ Full instructions: Account Creation
Generate an SSH key pair locally (use ed25519), then upload the public key through the portal's SSH Keys page. All testbed-side hosts — consoles, servers, sandboxes — accept your reservation-time SSH login via that key.
→ Full instructions: Configuring SSH Keys · connection patterns, tunneling, file transfer and troubleshooting are all on SSH Access.
Reservations are made from the portal Scheduler. Pick the testbed or sandbox you want, choose a time window (maximum duration varies by domain — 2 h on the grid, up to 6 h on the COSMOS domains), submit, and wait for the auto-approver to confirm. Lower 28-day usage = higher priority on contested slots.
→ Full instructions: Portal: Scheduler · the page covers the per-domain duration limits, automatic approval, conflict resolution, and the fairness algorithm.
When your reservation window opens, SSH into the console for the domain you reserved — for example ssh seskar@console.sb1.cosmos-lab.org for SB1. From the console you control everything within that domain.
→ Full instructions: SSH Access · helper material: Chrome Remote Desktop for GUI access, Remote Graphics for X11.
omf is the command-line tool used on every console for controlling the nodes in your reservation: status checks, image load, power on/off, save image, run experiments.
The most common workflow is:
| Step | OMF command |
|---|---|
| Status of all nodes | omf stat -t all |
| Load a saved disk image onto your nodes | omf load -t all -i baseline.ndz |
| Power-on the nodes (imaging leaves them off) | omf tell on -t all |
| Power-off when done | omf tell offs -t all |
| Save one node back to a custom image | omf save -n node1-1.sb5.cosmos-lab.org |
omf loadfinishes with the nodes powered off — always follow it withomf tell on. Andomf savehas no output-name flag: it writes<user>-<node>-<epoch>.ndzinto the image store, which you then rename.
→ Full instructions, all subcommands, options, and worked examples: OMF Quick Start · deeper reference: OMF Commands.
Once the nodes are loaded and powered on, you run experiments from the console — the orchestration host for your domain. Simple experiments run straight from the console shell (SSH into a node and run your tools); more complex, multi-node experiments are orchestrated with Ansible playbooks. The Experimentation guide explains the two ways to work, and the Tutorials section has fuller scenarios.
→ See the Experimentation guide · Tutorials for end-to-end examples.
If you get stuck:
→ Full instructions and contact details: Support.