5. First Login & Cloud Account

omicOS's agent chat, cross-device viewing, and subscription tiers all rely on a cloud account. There are two routes to log in—pick whichever fits your environment:

  • Web / GUI login (the common path). If you have a browser, you never have to touch the command line. omicos serve automatically opens the web client at app.omicos.cn, and you just sign in there with your email / password; the desktop app and the web version at omicos.cn use the same account and the same in-app sign-in. This is what most people use.
  • Terminal login (headless environments). On HPC nodes, servers, or pure command-line setups with no browser, you can complete login entirely in the terminal—that's what sections 5.1 / 5.2 below cover.

Terminal login itself comes in two flavors; the difference is the 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 that you confirm on another device already logged in to omicOS

In most cases, omicos login is the simplest option.

5.1 Email / password login: omicos login

Just enter your email and password in the terminal—no browser required—and it works on any machine (laptop, server, HPC login node):

omicos login
# Interactive terminal prompts:
#   Email:    you@example.com
#   Password: ********
# Login succeeds → credentials written to ~/.omicos/cloud_login.json

Available options:

Option Purpose
--email <address> Pass the email directly, skipping the interactive prompt
--password <password> Pass the password directly (note: it stays in your 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> Authentication service address, defaults to https://auth.omicos.cn
--status Don't log in—just check the current login state and print the email + process name
--logout Log out and delete the local credentials

Check your current login status:

omicos login --status

5.2 Device-code pairing login: omicos cli login

If you'd rather not type a password into the terminal, or want to authorize a new machine from a device that's already logged in to omicOS, you can use device-code pairing (RFC 8628 standard):

omicos cli login
# The terminal prints a pairing address + a short code, for example:
#   Open https://auth.omicos.cn/device on a device already logged in to omicOS
#   and enter the pairing code: ABCD-WXYZ

The flow:

  1. On another device already logged in to your omicOS account, open the pairing address shown in the terminal.
  2. Enter the short code ABCD-WXYZ and confirm.
  3. The current machine automatically polls for the approval result, writes the credentials to disk, and completes the login.

Device-code login has fewer options: --server (defaults to https://auth.omicos.cn) and --logout.

When to use which? If you know your account password and want to do it in one step → use omicos login. If the machine in front of you is brand new, typing a password is inconvenient, but you have another device already logged in → use omicos cli login to authorize via the pairing code. Both happen entirely in the terminal, and neither needs a browser on the local machine.

5.3 What login leaves behind

Login credentials are stored both locally in the workspace and globally:

  • omicos login writes credentials to the global ~/.omicos/cloud_login.json by default (this is also the config: path printed by omicos login --status, regardless of which directory you run it from).
  • However, the daemon actually reads the workspace-local <workspace>/.omicos/cloud_login.json first—cloud account switching and credential realignment write credentials there, with the global copy as a fallback. So within a given workspace, omicos serve uses that workspace's login identity.

Both files have 0600 permissions (readable and writable only by you) and identical contents, including:

Field Meaning
user_token Long-lived user token, used to authenticate user-level APIs (such as querying account and subscription info)
process_token Short-lived process token, used for the WebSocket process connection and heartbeats, rotated on every login
process_id Cloud process identifier, in the form local-<workspace_id>
user.cloud_base Server domain (auth.omicos.cn), used as the basis for all subsequent cloud calls
logged_in_at Login time

Security warning: cloud_login.json is not encrypted—it's protected only by its 0600 file permissions. Never commit it to git, paste it into a chat, or share it with anyone. On Windows the file permission model is different, so be sure to check your umask.

5.4 Logging out

omicos login --logout         # log out of email / password login
omicos cli login --logout     # log out of device-code login

Logout deletes credentials scoped by account_id—it only clears the current account's credentials and won't accidentally remove the shared global login of other accounts on the same machine.

Next steps

Once logged in, you can start omicOS. Choose based on your scenario:

results matching ""

    No results matching ""