6. Starting omicOS: serve mode (browser)

omicos serve is the most common way to start: it spins up a local daemon, and you then use your browser to work in the web app. Running omicos on its own is equivalent to omicos serve (serve is the default subcommand).

6.1 Minimal usage

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

The terminal will pause and print something like:

[omicos] online: Local <dir> OmicOS (local-...)
[omicos] listening: http://127.0.0.1:5055
[omicos] opening: https://app.omicos.cn/#/?ws=127.0.0.1%3A5055&auto=true

It will then open your browser automatically and take you to the web app at app.omicos.cn. The web app attaches directly to this local port, and you can start chatting and analyzing right away.

If the browser doesn't pop up automatically, just copy the URL on the opening: line printed in the terminal and open it manually.

6.2 Core options

For the complete option table, see Chapter 9: Command and flag reference.

6.3 Server / headless scenarios: --no-browser

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

omicos serve --no-browser

The daemon starts and listens as usual, it just doesn't try to launch a browser. You can then connect from a browser on another machine (see remote deployment).

6.4 Workspace lock: one daemon per directory

omicos places a lock at <workspace>/.omicos/serve.pid, ensuring that a given workspace directory can only have one daemon. If you run omicos serve again in the same directory, you'll get:

omicos serve already running on this workspace

To fix it: either Ctrl+C the original one, switch to a different workspace directory, or use --data-dir to point at a different data directory.

Note: omicos serve and omicos cli share the same workspace lock, so the two cannot run at the same time in the same directory.

6.5 What it looks like in the terminal

omicos detects whether stdout is a TTY (an interactive terminal):

• Is a TTY (you typed it directly in a terminal) → it renders a ratatui dashboard that shows process status, connections, and logs in real time.
• Not a TTY (wrapped by systemd / nohup / Tauri) → logs go straight to stderr and no dashboard is drawn.

This makes omicos suitable both for interactive use by a person and for running as a background service.

6.6 Health check

To confirm the daemon is healthy:

curl http://127.0.0.1:5055/health
# HTTP 200, returns JSON (not plain text "OK"):
# {"service":"omicos-core","status":"ok","version":{"semver":"0.2.x","build_profile":"release","target_triple":"...", ...}}

curl -sS http://127.0.0.1:5055/api/process/info | python3 -m json.tool
# HTTP 200, looks like:
# {"name":"OmicOS Core","runtime":"rust","kernel":"native-python-worker",
#  "launched_by":"terminal","pid":12345,"version":"0.2.x","workspace":"...","id":"..."}
# Note: there is no "status" field in this response.
# When not logged in, id, process_id, and process_name are empty strings and port/ws_port are 0;
# once logged in (even when started from a terminal / command line) they are populated, e.g. id = process_id = local-<workspace_id>

6.7 The first launch bootstraps the Python environment

The first time you run omicos serve, if the Python environment isn't set up yet, it will bootstrap it synchronously (unless you've set OMICOS_KERNEL_BASE_URL to use a remote kernel). We recommend setting it up ahead of time with omicos env setup (see Chapter 4) so your first launch doesn't stall on environment installation.

Next steps

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