NovaOS overview and glossary
What NovaOS is, the IDs you will meet, and how this MCP server's tools are organized.
What NovaOS is
NovaOS (Orbitron AI) is a platform to build, publish, govern and run AI agents. Agents are small web services (Python, A2A protocol) packaged as container images. NovaOS hosts them, gives them a governed LLM gateway, MCP tools, a knowledge base (RAG + GraphRAG), memory, a marketplace for installation, service accounts for app backends, metering, approvals and logs.
Typical lifecycle:
- Set up a computer (Python 3.12+, Docker, novaos-cli >= 2.2.1).
- Sign in to an environment (US staging by default, or FDE US) and pick an organization.
- Build an agent with the Python SDK (
novaos-agent-sdk, importnovaos_client_sdk). - Check it locally (contract tests, lint, agent card), then
novaos-cli publish-> review -> platform-admin approval -> ACTIVE. - Install it (marketplace) to get an instance, then TEST IT ON NOVAOS. There is no local testing of NovaOS behavior: the LLM gateway, MCP tools, RAG and the run context exist only inside NovaOS.
- Optionally: knowledge base, MCP tool servers, service accounts for backends.
Glossary of IDs (never interchange them)
| ID | What | Where it comes from |
|---|---|---|
| Publisher slug | Your team's marketplace identity, goes in manifest publisher |
novaos_publisher_show |
| Agent ID | Catalog id of an agent (stable across versions) | publish output, novaos_agent_list |
| Review ID | One publish submission in the review pipeline | publish output |
| Instance ID | One installation of an agent for ONE principal (a user or a service account), per environment | novaos_instance_install, novaos_instance_list |
| Run ID | One execution on an instance | novaos_run_start / novaos_ask_agent |
| Thread ID | Gateway conversation thread (must be created by the gateway) | returned by execute |
| A2A Task ID | The agent's own A2A task id (local SDK calls only) | Client.send_message |
| Collection ID | A knowledge-base collection (org-wide, shared by all apps) | novaos_kb_collection_create |
| Org (tenant) ID | Organization; must be in every token | novaos_auth_status |
A user can only run instances THEY own; a service account only its own. A personal install is never a substitute for a service-account install.
Environments
| Name | Label | API base | Notes |
|---|---|---|---|
staging |
US staging | https://api.staging.novaos.orbitronai.com | Default. IAM https://id.staging.novaos.orbitronai.com, marketplace https://marketplace.staging.novaos.orbitronai.com. |
fde |
FDE US | https://api.fde.us.orbitronai.com | IAM https://id.fde.us.orbitronai.com, marketplace https://marketplace.fde.us.orbitronai.com. |
staging-eu |
EU staging | https://api.stg.eu.orbitronai.com | Unverified. IAM https://id.stg.eu.orbitronai.com; some Claude models not deployed |
local |
built into the CLI | http://localhost:300x | platform developers only |
Switch with novaos_env_use {"env":"fde"} or {"env":"staging"}. Service URLs derive from the API base: /gateway, /agent-ops, /mcp-ops, /review, /s2s (RAG), /llm, /s2s/connector.
Hosted or local
- Hosted: connect the AI app to
<server>/mcp(no sign-in) or<server>/mcp/auth(NovaOS sign-in via OAuth). The server never touches the user's computer: steps that need it (installs, project files, Docker publish, novaos-cli) come back as exact commands the AI app runs in its terminal. Needs Node.js 20+ on the computer for those steps. - On
/mcp, NovaOS actions also run on the computer with the user's novaos-cli login (novaos-cli auth login, via thesetup_clijourney). - On
/mcp/auth, NovaOS actions (instances, runs, tests, knowledge base, conversations, cost) run on the server as the signed-in user. Publishing still runs on the computer. - Local: the same server on stdio (
novaos-mcp), with direct access to the computer.
How this MCP server is organized
- guide tools: orientation and knowledge (
novaos_start_here,novaos_docs,novaos_explain_error,novaos_ui_guide,novaos_template). - workflow tools: resumable journeys (
zero_to_hero,setup_machine,build_agent,ship_agent,knowledge_base,connect_backend). - molecule tools: one outcome made of several operations (
novaos_agent_create,novaos_agent_publish,novaos_ask_agent,novaos_kb_ingest, ...). - atom tools: one raw operation (one CLI command or one API call), plus
novaos_cliandnovaos_apiescape hatches.
Set NOVAOS_MCP_PROFILE=beginner to hide atoms. Errors always say WHO is at fault (NovaOS platform, CLI, your input, your setup, auth, capacity) and what to do; NovaOS-side bugs can be drafted with novaos_report_bug.
Official sources
- SDK on PyPI: https://pypi.org/project/novaos-agent-sdk/ (API docs https://orbitronai-repo.github.io/novaos-agent-sdk/)
- CLI: https://github.com/OrbitronAI-Repo/novaos-cli (npm
novaos-cli, Homebreworbitronai-repo/novaos/novaos-cli) - Customer wiki (ClickUp): https://app.clickup.com/90181480068/docs/2kzkrbm4-53358