Environments, sign-in, organizations and scopes
How novaos-cli resolves environments, how sign-in works, org context, roles, token scopes and the traps around them.
Quick setup (novaos-cli)
Two environments are supported. US staging (staging) is the default. FDE US (fde) is one switch away.
Guided: novaos_workflow_start {"workflow":"setup_cli"} for US staging, or {"workflow":"setup_cli","params":{"env":"fde"}} for FDE US. By hand:
novaos-cli version # 2.2.1 or later; `--version` is not a flag
# US staging (default)
novaos-cli env add staging --api-base https://api.staging.novaos.orbitronai.com --iam-url https://id.staging.novaos.orbitronai.com --client-id 7d548iiaxv5qkaksilkay --marketplace-url https://marketplace.staging.novaos.orbitronai.com --label "US staging" --service-environment staging
# FDE US
novaos-cli env add fde --api-base https://api.fde.us.orbitronai.com --iam-url https://id.fde.us.orbitronai.com --client-id 7d548iiaxv5qkaksilkay --marketplace-url https://marketplace.fde.us.orbitronai.com --label "FDE US" --service-environment staging
novaos-cli env use staging # writes ~/.novaos/config.json "environment"
novaos-cli env show --verbose # resolved URLs and where each came from
novaos-cli --env staging auth login # browser sign-in (OAuth + PKCE)
novaos-cli --env staging auth org list
novaos-cli --env staging auth org use <org-id>
novaos-cli --env staging auth whoami # identity, org, roles
novaos-cli --env staging publisher show # slug for manifest "publisher"
Always pass --env in scripts. Re-run auth login per environment; sessions are separate.
Switch environment
- Ask "switch NovaOS to FDE" (
novaos_env_use {"env":"fde"}), or back with{"env":"staging"}. It switches novaos-cli and this server together, and every later command targets the new env. - novaos-cli 2.2.x keeps ONE sign-in for all envs (
~/.novaos/credentials.json). Signing in to FDE replaces the US staging sign-in, and switching back needs a new browser sign-in.auth whoamionly decodes the token locally, so it looks valid for the wrong env; calls then get 401. This server checks the token's issuer and says "Signed in to a different NovaOS environment" instead. - Organization, publisher, agents, instances and knowledge collections are separate per env. After a switch, run the
setup_clijourney with that env: it adds the env, signs in and picks the org, skipping what is done. - Publisher slugs differ per env (for example
novaos-business-teamon US staging,orbitron-fdeon FDE). Checknovaos_publisher_showafter a switch and updatepublisherin manifest.json before publishing there. - Publishing goes to the active env. Check it with
novaos_env_showbefore you publish.
CLI environment model (2.2.x)
- Only
localis built into the CLI. Hosted environments live in~/.novaos/environments.json(add withnovaos-cli env add <name> --api-base ... --client-id ... [--iam-url] [--marketplace-url]). - Active env resolution:
--envflag (errors if unknown) ->NOVAOS_ENV->~/.novaos/config.jsonenvironment->local. - TRAP: an unknown name in
NOVAOS_ENVorconfig.jsonsilently falls back tolocal(localhost). This server always passes--envexplicitly andnovaos_env_listwarns about it. - Per-URL overrides: flags
--gateway-urletc., or env varsNOVAOS_GATEWAY_URL,NOVAOS_AGENT_OPS_URL,NOVAOS_MCP_OPS_URL,NOVAOS_REVIEW_URL,NOVAOS_IAM_URL,NOVAOS_CONNECTOR_HOST_URL,NOVAOS_CLIENT_ID,NOVAOS_MARKETPLACE_URL. agent list,publisher showandinitpublisher lookup need a marketplace URL in the env entry. Both presets include one.
Tools: novaos_env_list, novaos_env_setup, novaos_env_use, novaos_env_show.
Sign-in
novaos-cli auth loginopens a browser (OAuth Authorization Code + PKCE against Logto, callback on localhost:8976-8978, 120 s timeout). Signing in on the website does NOT sign in the CLI.- Tokens are stored in
~/.novaos/credentials.json(0600; never print it). Access tokens last ~15 min and refresh automatically 60 s before expiry; one forced refresh on 401, then "Session expired and refresh failed. Run 'novaos-cli auth login'". - This MCP server reuses the CLI sign-in (
novaos-cli auth token) internally; tokens are never shown to the model. - Default CLI scopes include
agent:* mcp:tools:* llm:model:* rag:* memory:* connector:* platform:admin(granted only if your roles allow).
Tools: novaos_auth_login, novaos_auth_status.
Organizations
- Every token must carry an organization (
organization_id). Without it most calls 403, and the CLI says[ORG_CONTEXT_REQUIRED]. novaos-cli auth org list/auth org use <org-id>(stored asactiveOrganizationId). Env varNOVAOS_ORGANIZATION_IDoverrides.
Tools: novaos_org_list, novaos_org_use.
Roles
developer: needed for most remote CLI commands (publish, logs, agent list). Client-side gate plus service enforcement.platform-admin: approves reviews, shadow deploys, connector registration. Developers, publisher owners and tenant admins cannot approve; service accounts never can.- Org Owner / Tenant admin: manages the org console (service accounts, models, connectors, MCP subscriptions). Org owner is NOT automatically an app admin.
Scopes (the #1 cause of "works for me, fails in the agent")
NovaOS copies the CALLER's scopes into the run's execution token. Whatever the user or service account lacks, the agent lacks.
| Need | Scope |
|---|---|
| Start/read runs | agent:execute agent:read |
| Install agents | agent:install |
| MCP tools | mcp:tools:* or mcp:tools:<category> (registered category, not display name) |
| Models | llm:model:* or llm:model:<id> |
| Knowledge read | rag:query rag:collections:read |
| Knowledge write | rag:parse rag:ingest rag:collections:write (+ chunk_document persist_artifact seen in apps) |
| Memory | memory:read:<scope>, memory:write:<scope> |
Symptoms: MODEL_UNAUTHORIZED (model scope), "RAG scope mismatch" (rag scopes), MCP "category mismatch" (mcp/llm scopes).
User sign-in for apps (SPA, Logto PKCE) should request agent:execute agent:install mcp:tools:* llm:model:* rag:query rag:collections:read for urn:novaos, org-scoped.
Token facts
- Resource (audience)
urn:novaos. Logto M2M tokens are ES384; NovaOS execution tokens are RS256: validators must accept both. Gateway JWKS:<gateway>/.well-known/jwks.json. - Every client_credentials request needs
resource=urn:novaosANDorganization_id, or the gateway returns a silent 403. - Refresh tokens rotate on every use: store the new one immediately.
- Logto end-session page has CSP
form-action 'self'(blank page in Chrome): sign out locally and useprompt=loginto switch accounts.