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
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.- Signed in to the right env + org, developer role, real publisher slug (
novaos_publisher_show; placeholderlocal-publisheris refused). - Docker running with buildx. New
version(re-publishing an existing version fails), andAGENT_VERSIONin code equal to it. 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/approvalsof 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 headerX-Requested-With: XMLHttpRequest(CSRF guard; else 403). Upper-caseA2A;agent_namerequired. Responsedata.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(runseval/suite.jsonthrough 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
- Backend (migrations, new routes)
- MCP server: publish, approve, activate
- Agent: publish, approve
- Reinstall/upgrade instances; update instance-id secrets (force-sync external secrets)
- Restart backend and agent-tools
- Frontend