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. There are two ways to do it.

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.

Method 2: Pure cloud relay (no SSH, plug-and-play across machines)

As long as the daemon on the server is logged in, the cloud relay is automatic — no extra flag required. After login, omicos serve proactively dials an outbound wss connection to wss://auth.omicos.cn/ws/process and registers itself. When you open the web app from any browser and select this instance in the process picker, the cloud pushes chat / UI requests down over this socket; the daemon then forwards them to its own local runtime (127.0.0.1:5055, where the kernel lives) and sends responses back over the same socket:

# One-time prerequisite: log in on the server first
omicos login

# Start it on the server (no SSH tunnel, and no --upstream-base-url)
cd ~/my-analysis
omicos serve --no-browser

# On your laptop, open https://app.omicos.cn in any browser (same account required)
# Select the sherlock instance in the process picker → the cloud ProcessHub relays kernel calls
  • Pros: zero network configuration; switch to any internet-connected machine and you're in.
  • Cost: plots / variable details / kernel execution are all relayed through wss://auth.omicos.cn, so bandwidth is consumed in the cloud and latency is higher.
  • Recommendation: use it for occasional check-ins and lightweight interaction; for heavy analysis, stick with Method 1.

Don't attribute the relay to --upstream-base-url. The only condition for enabling the relay is that the daemon holds a process_token (from omicos login, or the OMICOS_PROCESS_TOKEN environment variable) — it has nothing to do with --upstream-base-url. --upstream-base-url only configures a local HTTP proxy fallback (forwarding unmatched /api/* to the backend, i.e. the escape hatch for cloud sync); it does not decide where the kernel runs, and you normally don't need to pass it manually. The kernel defaults to 5055 on the local machine, controlled separately by --kernel-base-url.

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.)

Attaching to a cloud process remotely with cli

If you want to attach directly to a remote process and chat from your local terminal, use omicos cli --process:

omicos cli --process local-<remote workspace_id>

This lets the local TUI drive the analysis process on that remote machine directly.

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.

results matching ""

    No results matching ""