8. Remote / SSH / HPC Deployment Recipes

Often your data and compute live on a remote server or HPC cluster, while you want to drive everything from your local laptop. This chapter gives copy-paste-ready command recipes for three typical scenarios.

First, keep one key distinction in mind: which machine the kernel (compute) runs on and which machine you operate the UI from are two independent things. The options below are about trading off between the two.

Scenario A: Local laptop + browser

Both data and analysis live on your own machine. This is the simplest case:

mkdir -p ~/my-analysis && cd ~/my-analysis
omicos login            # email / password
omicos serve            # listens on 127.0.0.1:5055, auto-opens browser to app.omicos.cn

Best for: day-to-day analysis on a personal computer.

Scenario B: Pure terminal TUI (headless HPC)

You've SSH'd into an HPC login node with no graphical interface, and you want to do everything in the terminal — neither login nor chat needs a browser:

omicos login            # email / password, pure-terminal login (no browser needed)
cd ~/my-analysis
omicos cli              # enter the terminal chat interface

If it's inconvenient to type a password on this machine, use omicos cli login device-code pairing instead, and confirm the pairing code on another device that's already logged in to omicOS.

Best for: pure command-line environments, strict firewalls, and HPC clusters where opening a browser tunnel is impractical.

Scenario C: Analysis runs on the server, you view it in the laptop browser

This is the most common scenario, and the one most worth spelling out.

SSH port forwarding

Have your local browser connect directly to port 5055 on the server through an SSH tunnel. Kernel calls stay entirely inside the server, with zero cloud relay:

# Set up the tunnel on your laptop
ssh -L 5055:127.0.0.1:5055 user@sherlock.stanford.edu

# Start omicos inside the same SSH session
cd ~/my-analysis
omicos serve --no-browser

# Back on your laptop, open https://app.omicos.cn in the browser
# The web app automatically finds the forwarded local port 5055

• Pros: plots, variable details, and kernel execution all go over the local tunnel — lowest bandwidth cost and latency.
• Cost: you must keep that SSH window open. The moment SSH drops, the browser hitting localhost:5055 gets connection refused.
• Official recommendation: route heavy kernel work (large data, frequent plotting) through this path.

Keeping the process alive in the background

On a server, you usually want omicos to keep running after you disconnect from SSH. Three common approaches (all paired with --no-browser):

# nohup
nohup omicos serve --no-browser > omicos.log 2>&1 &
disown

# tmux
tmux new-session -d -s omicos \
  'cd ~/my-analysis && omicos serve --no-browser'

# screen
screen -dm -S omicos bash -c \
  'cd ~/my-analysis && omicos serve --no-browser'

For a systemd service, write ExecStart as:

ExecStart=/usr/local/bin/omicos serve --no-browser

(When omicos detects a non-TTY environment, it automatically skips drawing the dashboard and routes logs to stderr, adapting to the systemd journal.)

Health checks and smoke tests

Regardless of deployment, you can confirm the service is healthy with this set of commands:

curl -sS http://127.0.0.1:5055/health
# Expect HTTP 200, returning JSON:
# {"service":"omicos-core","status":"ok","version":{"semver":"0.2.x", ...}}

curl -sS http://127.0.0.1:5055/api/process/info | python3 -m json.tool
# Expect HTTP 200, of the form:
# {"name":"OmicOS Core","runtime":"rust","version":"0.2.x", ...}
# Note: the response has no "status" field; when not logged in / started in terminal mode, id, process_id, and process_name are empty strings

One thing to watch: switching accounts triggers a self-healing restart

If you switch the logged-in account within a workspace, the cloud notifies you via WebSocket close code 4403, and omicos rotates the workspace_id and automatically restarts itself. This looks like a crash, but it's actually the expected recovery behavior. The cost is that the session-sync high-water mark is cleared, so the session list may appear empty under the new account (your old local session files are still there). See Troubleshooting for details.