6. Starting omicOS: serve mode (browser)

This chapter covers the most common way to start omicOS: run a local daemon and drive it from the browser. Running plain omicos is equivalent to omicos serve (serve is the default subcommand).

6.1 Minimal Usage

cd ~/my-analysis     # enter the directory where you want your data / notebooks
omicos serve

Expected output: the terminal switches to a full-screen dashboard, roughly like this:

  OmicOS  0.3.29                     uptime 00:00:12    theme dark
 ── Runtime ─────────────────────────────────────────────────────
  Local     http://127.0.0.1:5055  (kernel HTTP / WS)
  Browser   https://app.omicos.cn/#/?ws=127.0.0.1%3A5055&auto=true
  Region    CN
  Cloud     ● online
  Process   local-9f2c…1a94
 ── Logs ────────────────────────────────────────────────────────
  …
  q / Ctrl-C quit   urls …

It also opens your browser automatically to the web app, which connects directly to the port shown on the Local line, so you can start chatting right away. If the browser doesn't pop up on its own, copy the URL on the Browser line and open it manually.

Press q or Ctrl-C to quit; the terminal returns to normal.

Two output forms. The dashboard is only drawn when stdin and stdout are both an interactive terminal. When wrapped by nohup, systemd, the desktop app, or when output is redirected / piped, omicos instead prints a set of plain text lines with logs going to stderr — the "Expected output" blocks later in this chapter use this text form, since it's easier to check line by line:

[omicos] online: my-analysis (local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94)
[omicos] listening: http://127.0.0.1:5055
[omicos] opening: https://app.omicos.cn/#/?ws=127.0.0.1%3A5055&auto=true

If you're not logged in, the first line becomes [omicos] offline: run \omicos login` to connect auth.omicos.cn`; local analysis still works as usual.

6.2 Core Flags

For the full flag reference, see Chapter 9: Command & Flag Reference.

6.3 Automatic Port Fallback

If 5055 is taken by another process, omicos doesn't just fail — it tries ports starting from 5056 onward (up to 100 ports), and only falls back to a system-assigned random port if none of those work:

omicos serve --no-browser > omicos.log 2>&1 &

Expected output (contents of omicos.log):

[omicos] online: my-analysis (local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94)
[omicos] port 5055 was busy; using 5056 instead
[omicos] listening: http://127.0.0.1:5056

Everything downstream must use the port it actually bound to (here, 5056) — including health checks and SSH port forwarding. In the dashboard, this is the value shown on the Local line.

For scripts, --report-port is the most reliable way to get this value:

omicos serve --no-browser --report-port > omicos.log 2>&1 &

Expected output (contents of omicos.log):

[omicos] online: my-analysis (local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94)
[omicos] listening: http://127.0.0.1:5055
OMICOS_LISTENING_PORT=5055

6.4 Servers / Headless Scenarios: --no-browser

On a machine with no graphical interface, or where you don't want a browser popping up:

omicos serve --no-browser

Expected output: same as 6.1 (dashboard or text lines), just without the opening: line, and it never tries to launch a browser.

The daemon starts and listens as usual; you then connect from a browser on another machine (see remote deployment).

6.5 Workspace Lock: One Instance Per Directory

omicos places a lock at <workspace>/.omicos/serve.pid, ensuring a given workspace directory only ever has one daemon. Running omicos serve again in the same directory doesn't error out — it reuses the instance that's already running:

omicos serve --no-browser 2>&1 | cat

Expected output:

[omicos] already running in this workspace (pid 41287, port 5055); reusing it instead of starting a second instance.
[omicos] open: https://app.omicos.cn/#/?ws=127.0.0.1%3A5055&auto=true

Then (unless --no-browser is set) it opens a browser pointed at the existing instance and exits successfully. So the second time you type omicos, it feels like "it just opened the one that was already running."

To actually start a second instance, switch to a different workspace directory, or point --data-dir at a different data directory.

omicos serve and omicos cli share the same workspace lock. When a serve instance is already running in a workspace, omicos cli connects directly to it (see Chapter 7) instead of erroring out.

6.6 Health Check

Confirm the daemon is healthy:

curl -sS http://127.0.0.1:5055/health

Expected output:

{"service":"omicos-core","status":"ok","version":{"build_profile":"release","display":"0.3.29+a1b2c3d","git_rev":"a1b2c3d","semver":"0.3.29","target_triple":"aarch64-apple-darwin"}}

Check process identity and workspace:

curl -sS http://127.0.0.1:5055/api/process/info | python3 -m json.tool

Expected output (excerpt):

{
    "core_workspace_root": "/Users/you/my-analysis",
    "hostname": "your-macbook",
    "id": "local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94",
    "kernel": "native-python-worker",
    "launched_by": "terminal",
    "name": "my-analysis",
    "pid": 41287,
    "port": 5055,
    "process_id": "local-9f2c4d7a1b8e4f5c8d3a6b0e2f7c1a94",
    "process_name": "my-analysis",
    "runtime": "rust",
    "version": "0.3.29",
    "workspace": "/Users/you/my-analysis",
    "ws_port": 5055
}

A few notes:

• The response has no status field (that's on /health only).
• When not logged in, id / process_id still have values, falling back to local-<workspace_id>; process_name falls back to OmicOS Core. So a value in these fields doesn't mean you're logged in — check the online / offline line, or run omicos login --status.
• launched_by is terminal (started from the terminal) or desktop (started by the desktop app).
• hostname is this machine's hostname — useful when debugging remote connections.

6.7 The First Launch Doesn't Wait on the Python Environment

omicos serve doesn't delay startup to prepare the environment: the port binds immediately, chat and file operations are available right away, and the Python environment prepares in the background. If you try to run analysis during that window, you'll see:

The Python environment is still being prepared — chat works now; retry running Python in a moment.

We recommend setting up the environment ahead of time with omicos env setup (see Chapter 4) so your first analysis doesn't collide with an environment that's still installing.

Next Steps

• Want a pure terminal experience instead of the browser? → Chapter 7: cli mode
• Want to run on a remote server and view it from your local browser? → Chapter 8: remote deployment