This page explains how you actually run experiments on COSMOS once you
have a reservation and imaged nodes: what the console is, how the
nodes behind it do the work, the two ways to work (headless and
interactive desktop), and how to orchestrate complex, multi-node
experiments with Ansible.
New here? Start with Getting Started
for accounts, reservations, and imaging, then come back to this page.
Every COSMOS domain (the Grid, BED, a sandbox, …) is reached through one
console — a small always-on host named console.<domain>.cosmos-lab.org
(e.g. console.sb1.cosmos-lab.org). The console is your orchestration
head: you SSH into it, and from there you drive everything in that domain.
The nodes are the machines that do the real work — programmable
compute + radio boxes (USRPs, servers, phones, O-RUs, …). You do not
log into nodes from the public Internet; you reach them from the
console, on the domain's private control network.
A typical flow from the console:
# from your laptop
user@laptop:~$ ssh console.sb1.cosmos-lab.org
# on the console: load an image onto your reserved nodes, power them on
user@console:~$ omf load -i ubuntu2404-baseline.ndz -t node1-1,node1-2
user@console:~$ omf tell -a on -t node1-1,node1-2
# then work with the nodes (see the two modes below)
user@console:~$ ssh root@node1-1
See OMF Quick Start for the
omf load / save / tell / stat commands, and
Remote Access for SSH details.
Depending on the tool, you either work headless (command line only) or
in an interactive desktop (full graphical session). Most COSMOS work is
headless; use the desktop when a tool really needs a GUI.
The default and most reproducible mode. You SSH from the console to a node
and run everything from the shell — scripts and CLI tools — with no
display involved. Even a tool with a graphical designer can run headless:
in GNU Radio experiments, a flowgraph drawn in GNU Radio Companion is
compiled to a plain Python script that runs over SSH with no GUI at run
time (this compile-to-script step is specific to GNU Radio; most other
tools are already command-line).
user@console:~$ ssh root@node1-1
root@node1-1:~$ python3 experiment.py --param value
Headless is what you want for sweeps, automation, and anything you'll repeat
or hand to Ansible (below).
When you need a real GUI — GNU Radio Companion, a spectrum display, a
browser on the node, an IDE — use an interactive desktop session. COSMOS
offers two ways to get pixels back to you:
SSH with X11 forwarding — good for a single graphical window. From the
console, forward the node's X apps:
user@console:~$ ssh -X root@node1-1
root@node1-1:~$ gnuradio-companion # window opens on your local screen
You need an X server running locally (built in on Linux; XQuartz on macOS;
VcXsrv / Xming / MobaXterm on Windows). Full per-OS setup is on the
Remote Graphics page.
Chrome Remote Desktop — a full remote desktop when X11 forwarding is
too slow or you want a persistent graphical session (multiple windows, a
file manager, a browser). It streams a complete desktop to the Chrome
Remote Desktop client / browser tab. Setup is on the dedicated
Chrome Remote Desktop page.
Driving one node by hand is fine for trying things out. Real experiments
usually span many nodes — a transmitter and a receiver, a cell with an
AP and several clients, a base station and UEs — and need the same steps
run on each, in the right order. COSMOS uses Ansible
(the cosmos-ansible toolchain) for this.
You describe the experiment once — which node does what, with which
parameters — in an inventory + playbooks, and run it from the
console. Ansible stages the code onto each node, starts the transmitter,
runs the receiver, collects the results, and tears down — the same way
every time. Experiment parameters (frequencies, gains, modulation, sweep
ranges, …) live in group_vars, so you can re-run any combination with a
one-line override instead of editing scripts.
user@console:~$ cd ~/cosmos-tutorials-<name>
user@console:~$ ansible-playbook experiment.yml -e '{"param":"value"}'
The Tutorials section has complete,
Ansible-driven examples you can download and run — e.g. the WiFi
rate-vs-attenuation and SDR BER-vs-SNR tutorials — each shipping its
inventory, playbooks, and group_vars so you can adapt them to your own
experiment.