5. First Login & Cloud Account

omicOS's agent chat, cross-device viewing, and subscription tiers all rely on a cloud account. The entire login flow happens in the terminal—no browser is needed on the local machine—whether it's a personal computer or a headless HPC / server with no graphical interface.

There are two ways to log in. The difference is the authentication method, not whether a browser is involved:

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 ""