5. First Login & Cloud Account

This chapter covers linking this machine to your omicOS cloud account. Agent chat, cross-device viewing, and subscription tiers all depend on it.

There are two routes to log in — pick whichever fits your environment:

  • Web / GUI login (most common). If you have a browser, you never need to touch the command line. omicos serve automatically opens app.omicos.cn, where you sign in with email / password; the desktop app and omicos.cn use the same account.
  • Terminal login (headless environments). On HPC nodes, servers, and other environments with no browser, login happens entirely in the terminal — that's what sections 5.1 / 5.2 below cover.

Terminal login itself comes in two flavors, differing in authentication method:

Method Command How it authenticates
Email / password omicos login Enter your email and password directly in the terminal
Device-code pairing omicos cli login The terminal prints a pairing code, confirmed on another device already logged in to omicOS

omicos login is the simplest choice in most cases.

5.1 Email / Password Login: omicos login

No browser required, and it works on any machine (laptop, server, HPC login node):

omicos login

Expected output (interactive — Email: / Password: are prompts, the password isn't echoed):

Email: you@example.com
Password:
[omicos] logged in as you@example.com
[omicos] process: my-analysis
[omicos] config: /Users/you/.omicos/cloud_login.json

Available flags:

Flag What it does
--email <address> Pass the email directly, skipping the interactive prompt
--password <password> Pass the password directly (stays in shell history, use with caution)
--name <name> Override the process display name (defaults to the conda environment name or the current directory name)
--force Force re-authentication even if already logged in
--server <URL> Auth service address, defaults to https://auth.omicos.cn
--status Don't log in — just verify and print the current login state
--logout Log out and delete local credentials

Check your current login status:

omicos login --status

Expected output (logged in):

[omicos] logged in as you@example.com
[omicos] process: my-analysis
[omicos] config: /Users/you/.omicos/cloud_login.json

Expected output (not logged in):

[omicos] not logged in: not logged in

Running omicos login again once you're already logged in doesn't re-authenticate:

omicos login

Expected output:

[omicos] already logged in as you@example.com
[omicos] process: my-analysis
[omicos] config: /Users/you/.omicos/cloud_login.json

Add --force to force re-authentication.

5.2 Device-Code Pairing Login: omicos cli login

If you don't want to type a password on this machine, or want to authorize a new machine from a device that's already logged in to omicOS, use device-code pairing:

omicos cli login

Expected output:


→ Open this URL in a browser where you're signed in to omicos:
    https://auth.omicos.cn/device

→ Confirm code:
    ABCD-WXYZ

Waiting for approval... (Ctrl-C to cancel)
  ✓ approved

✓ logged in as you@example.com
  config: /Users/you/.omicos/cloud_login.json
  core: no running local core detected

The flow:

  1. On another device already logged in to your omicOS account, open the address printed in the terminal.
  2. Enter the confirmation code and confirm.
  3. This machine automatically polls for the approval result, writes the credentials to disk, and login is complete.

The last line, core:, reports whether an omicos process is already running on this machine — if so, the new credentials are synced to it without a restart.

Device-code login has only two flags: --server (defaults to https://auth.omicos.cn) and --logout.

Which one should you use? Know your password and want to be done in one step → omicos login. This is a new machine, typing a password is inconvenient, but another device is already logged in → omicos cli login. Both complete entirely in the terminal, and neither needs a browser on this machine.

5.3 What Login Leaves Behind

The credential file is called cloud_login.json, and lives in one of two possible locations:

  • omicos login writes to the global ~/.omicos/cloud_login.json by default — this is also the config: path it prints, regardless of which directory you run it from.
  • But the daemon reads the workspace-local <current directory>/.omicos/cloud_login.json first, falling back to the global copy. Cloud account switches and credential realignment write to the workspace-local copy. So within a given workspace, omicos serve uses that workspace's login identity.
  • With OMICOS_LOCAL_HOME set, both locations point to $OMICOS_LOCAL_HOME/cloud_login.json.

The file has 0600 permissions (readable and writable only by you) and contains:

Field Meaning
server The auth service address used at login
user_token Long-lived user token, authenticates user-level APIs (such as querying account and subscription info)
process_token Process token, used for the cloud process connection and heartbeat, rotated on every login
process_id Cloud process identifier, in the form local-<workspace_id>
process_name Process display name (overridable with --name)
user Account info; user.cloud_base is the domain basis for all subsequent cloud calls
logged_in_at Login time (Unix seconds)

Security note: cloud_login.json is not encrypted — it's protected only by file permissions. Never commit it to git, paste it into a chat, or hand it to anyone. Windows has a different permission model, so double-check it there.

5.4 Logging Out

omicos login --logout

Expected output:

[omicos] logged out

omicos cli logout

Expected output:

[omicos cli] logged out
  removed /Users/you/.omicos/cloud_login.json

Running omicos cli logout while not logged in prints [omicos cli] not logged in.

omicos login --logout deletes both the workspace-local and global cloud_login.json — this machine is fully logged out. (There's also an "account-scoped cleanup" case: when the cloud determines an account is no longer valid, omicos only clears that account's credentials, leaving other accounts on the same machine untouched. This happens automatically; you don't need to trigger it by hand.)

Next Steps

Once logged in, start omicOS:

results matching ""

    No results matching ""