NovaOS MCP
Field guide

Publish, review, approval, installation and instances

From a local agent to a running instance: publish flow, review states, platform-admin approval, deployment targets, user vs service-account installs, versions and release order.

Before publishing

  1. novaos_agent_lint (all known traps), novaos_manifest_validate, novaos_agent_test (contract tests only), novaos_agent_card (catches Agent Card drift and agent_module errors before a slow build). These are the only local checks: NovaOS behavior is tested after install.
  2. Signed in to the right env + org, developer role, real publisher slug (novaos_publisher_show; placeholder local-publisher is refused).
  3. Docker running with buildx. New version (re-publishing an existing version fails), and AGENT_VERSION in code equal to it.
  4. novaos-cli --env <env> publish manifest.json --dry-run (checks authorization only; still needs login).

Publish

novaos-cli --env <env> publish manifest.json [--dockerfile Dockerfile.novaos] [--context ..] [--platform linux/amd64] --json Steps inside: validate -> publish auth -> buildx build -> Agent Card capture (python -m novaos_client_sdk.agent_card server:agent) + drift check -> push -> finalize. Prints the review id and agent id. Push can take minutes on slow links. Tool: novaos_agent_publish (background job). The FDE PoC repo's CI ignores apps/<slug>/agent/**: agents are always published with the CLI, never by App Apply. Commit before publishing (a published local tree that is not committed is hard to reproduce).

Review states

PENDING_SCAN -> SCANNING -> PENDING_REVIEW (waiting for a platform admin) -> APPROVED (activating) -> ACTIVE; or REJECTED (see review notes) / ROLLED_BACK. novaos-cli publish-status <review-id> [--wait --timeout 900] [--verify] exits 1 on REJECTED/ROLLED_BACK or timeout. Tools: novaos_publish_status, novaos_wait_for_approval. Image scan and dependency audit often show "Not run" on FDE; base-image check may warn.

Approval (browser)

  • Who: a verified human Platform Admin. Developers, publisher owners, tenant admins and service accounts cannot approve. Trusted publishers may auto-approve.
  • Where: marketplace /admin/approvals of the env you published to (US staging: https://marketplace.staging.novaos.orbitronai.com/admin/approvals, FDE: https://marketplace.fde.us.orbitronai.com/admin/approvals). Developers watch their submissions in Developer > Publishes (Review Pipeline, Review Details, Review Notes, Scan Results).
  • Hosted MCP servers: Platform Admin > Connectors > Tool Reviews: Approve, then Activate (separate), then Tool Health.
  • Never claim an agent is live while it is in review; never invent instance ids; never self-approve on someone's behalf. Tool: novaos_ui_guide {"task":"approvals"}.

Deployment target

  • ["chat"] (default): listed in Marketplace > Available Agents, usable in Chat; non-admin users can install it.
  • ["api"]: not listed; an admin finds it in Admin > Agent Catalog and installs it for a service account.
  • Listing metadata is visible across orgs: no confidential text in descriptions. API-only is not access control.

Install = get an instance

  • Instance = (agent, principal, env). A user can only run their own instances; a service account only its own. No shared/org-wide installs, no on-behalf-of.
  • User install (UI): Marketplace > Available Agents > open agent > check version > fill config > Install; then Installed Agents > Open Agent.
  • User install (API): POST {marketplace}/api/instances {agent_id, agent_name, adapter_type: "A2A", agent_version?, config?, secrets?} with header X-Requested-With: XMLHttpRequest (CSRF guard; else 403). Upper-case A2A; agent_name required. Response data.instance.instance_id; 201 READY; idempotent per org+user+agent; reinstall upgrades. Tool: novaos_instance_install.
  • Service-account install (UI): Org Console > Manage > Service Accounts > account > Agents > Install agent; read back version and Instance ID. API: same marketplace call with the SA token (novaos_instance_install {as: "<sa ref>"}).
  • List: GET {gateway}/api/v1/instances?limit=50&cursor= (pages of 50; status == READY). Tool: novaos_instance_list.
  • A new agent version does NOT update existing installs: reinstall (upgrade) or pin agent_version. After every SA re-install, store the (possibly new) instance id in your backend secret and restart.
  • Installation config values become pod env vars; per-instance secrets are per user and per instance (rotation = reinstall). Instances with config/secrets never get warm-pool pods.
  • READY is not business success: test on NovaOS with novaos_test_deployed (runs eval/suite.json through the gateway: ping, a model call, a clean failure). This is the agent's real test.

Versions

novaos-cli agent list (agent ids), novaos-cli release list --agent <id> (versions). Admin: Admin > Agent Version Management. release create is deprecated: use publish.

Release order for an app with agent + MCP + backend

  1. Backend (migrations, new routes)
  2. MCP server: publish, approve, activate
  3. Agent: publish, approve
  4. Reinstall/upgrade instances; update instance-id secrets (force-sync external secrets)
  5. Restart backend and agent-tools
  6. Frontend