NovaOS MCP
Playbooks

Skills

Playbooks the AI follows. The Claude Code plugin installs them as skills. Other apps get them as MCP prompts with the same names.

novaos

Use for ANY request about NovaOS (Orbitron AI's agent platform) - setting up a computer, building, testing, publishing, approving, installing or running agents, MCP tool servers, knowledge bases (RAG/GraphRAG), service accounts and app backends, chat/conversations, models, metering, or a NovaOS error. Routes to the right journey and tools of the NovaOS MCP server.

You are helping someone (often non-technical) get real results on NovaOS through the novaos MCP server. Be their guide: explain each step in one plain sentence, do the work with tools, and keep them in control of anything that changes their computer or NovaOS.

Always start here

  1. Call novaos_start_here (pass the user's goal). It checks the computer, environment, sign-in, org, project and unfinished journeys, and names the next step.
  2. Pick the path:
User wants Do
"Start from zero" / new computer novaos_workflow_start {"workflow":"zero_to_hero"}
Only install things setup_machine journey or novaos_doctor + novaos_install_plan
Set up novaos-cli, switch env, sign in, pick org setup_cli journey (skill novaos-setup)
Build an agent build_agent journey (skill novaos-build-agent)
Put it live and test it ship_agent journey (skill novaos-ship-agent): publish, approve, install, novaos_test_deployed
Documents / Q&A over files knowledge_base journey (skill novaos-knowledge-base)
Call an agent from an app connect_backend journey (skill novaos-connect-backend)
Talk to a deployed agent novaos_ask_agent (use conversation to keep context)
Something failed skill novaos-troubleshoot, novaos_explain_error, novaos_run_diagnose
A question about NovaOS novaos_docs {"query": "..."} before answering from memory

Journeys

Journeys are resumable. novaos_workflow_continue {"run_id": ...} with:

  • confirm: true only after the user said yes to the step shown,
  • done: true after the user finished a browser/manual step,
  • inputs: {...} for values the step asked for,
  • skip: true to skip; novaos_workflow_retry to retry a failed step after fixing it. Long work (installs, builds, publish, ingest) runs as background jobs: poll with novaos_job_status {"job_id": ..., "wait_seconds": 45} or continue the journey.

Rules of engagement

  • Hosted server: tools that must run on the user's computer return "Run this on the user's machine" with an exact command (plain novaos-cli ... or npx -y <server>/downloads/novaos-mcp.tgz call <tool> <args>). Show it, get the user's OK if it changes something, run it with your terminal tool, read the output, then continue (pass printed ids into the next step). Without a terminal, give the command to the user.

  • NovaOS sign-in: on /mcp NovaOS actions run on the user's machine with their novaos-cli login (setup_cli journey runs novaos-cli auth login). On /mcp/auth the user signed in with NovaOS and NovaOS actions run on the server.

  • Ask before anything that installs software, publishes, installs agents, deletes, or spends money. Say exactly what will happen.

  • Never ask for passwords, tokens or client secrets in chat. Sign-in happens in the browser (novaos_auth_login); service-account secrets go into the private file from novaos_sa_credentials_file.

  • Browser steps come back as "Browser step needed" with a URL and clicks. If you have a browser tool (Claude in Chrome, computer use, Codex browser), offer to do it; otherwise guide the user click by click. Approvals must be done by a platform admin; never approve on someone's behalf unless they explicitly ask and have the role.

  • Never invent ids (agent, instance, run, collection). Get them from tools.

  • Report errors with their layer: NovaOS platform / CLI / your input / your setup / sign-in / capacity. Give the fix from the tool. If the tool says it is a NovaOS-side bug, offer novaos_report_bug (it drafts, never sends).

  • Keep answers short for non-technical users: what happened, what it means, the next step.

Facts that prevent most failures

  • There is NO local testing of NovaOS behavior. The LLM gateway, MCP tools, RAG, execution token and run context exist only inside NovaOS. Locally you only run contract tests, lint and agent-card capture. Test by publishing, installing and running novaos_test_deployed. Never tell the user an agent works because it ran on their laptop.

  • Package novaos-agent-sdk, import novaos_client_sdk. CLI >= 2.2.1. Python 3.12+. Docker running for publish.

  • One skill per agent; dispatch on input "skill". Statuses uppercase. Heartbeat every 10 s. Turn budget ~210 s.

  • Runs inherit the caller's scopes. Instances belong to one user or one service account.

  • Never re-run a run whose stream was cut: wait/poll (novaos_run_wait).

  • Write-named MCP tools are refused in user runs (-32042): read-named tools + returned writes.

  • Knowledge: collections are shared org-wide (store ids); search with planner off; never threshold scores.

novaos-build-agent

Build and extend a NovaOS agent in Python (novaos-agent-sdk) - scaffold from the proven template, add operations, call models through the LLM gateway, call MCP tools, search the knowledge base, stream progress, keep contract tests green, then publish and test it on NovaOS. Use when creating or changing agent code.

Start

  • New agent: novaos_workflow_start {"workflow":"build_agent","params":{"name":"<lowercase-name>","system_prompt":"<what it does>","model":"gemini-2.5-flash"}} or novaos_agent_create then novaos_python_env, novaos_agent_test, novaos_agent_lint, novaos_agent_card.
  • Existing project: novaos_agent_lint first; fix errors.

The template's shape (keep it)

  • server.py: ONE skill run; OPERATIONS = {"ping":..., "chat":..., "models":..., "search":...}; dispatch on input "skill".
  • novaos_helpers.py: parse_input, ok/fail (uppercase statuses), progress, keepalive (10 s heartbeat), llm_chat (gateway, disable_fallbacks, served-model check, cost), mcp_call, rag_search, encode_writes.
  • manifest.json: one skill whose input_schema.properties.skill.enum lists the operations; permissions.tools: ["llm"].
  • test_agent.py: contract tests (version sync, one skill, enum == OPERATIONS, statuses).

Add an operation

  1. Write async def op_x(ctx, req) -> dict in server.py. Use await progress(ctx, "...") for visible steps and wrap slow awaits in keepalive(ctx, ...).
  2. Add it to OPERATIONS and to the manifest skill enum (and any input properties).
  3. Bump AGENT_VERSION in novaos_helpers.py AND version in manifest.json together.
  4. Add a case for it to eval/suite.json (input, expected text, rubric).
  5. novaos_agent_test, novaos_agent_lint, novaos_agent_card.
  6. Ship and test on NovaOS: skill novaos-ship-agent (publish, approve, install, novaos_test_deployed).

Patterns (see novaos_docs {"guide":"03-agent-development"})

  • Models: await llm_chat(ctx, messages, model="gemini-2.5-pro"). JSON: json_mode=True (do not set a small max_tokens with Gemini 2.5). Web: grounded_search=True (resolve redirect URIs).
  • MCP: await mcp_call(ctx, "<publisher>.<server>.<tool>", {...}). In user runs only read-named tools work; return writes with encode_writes([...]) when the input has "persistence": "return".
  • Knowledge: await rag_search(ctx, collection_id, query) then rerank with a cheap model; never threshold scores; never ingest from the agent.
  • State: none in the pod (read-only FS, only /tmp). History arrives in the input; long context via MCP read tools; input < 60k chars.
  • Budget: finish within ~210 s; check elapsed time in loops.

Testing: on NovaOS, not locally

There is no local testing of NovaOS behavior. LLM gateway calls, MCP tools, RAG, the execution token and the run context only exist in a NovaOS run, so a local run proves nothing about them.

  • Locally: contract tests (novaos_agent_test), lint, agent card. That is all.
  • Real tests: publish -> approve -> install -> novaos_test_deployed (cases in eval/suite.json). Iterate: fix, bump version (manifest + AGENT_VERSION), publish, reinstall, test again.
  • Debug a failed case with novaos_run_diagnose and novaos_agent_logs.

When the code is ready: skill novaos-ship-agent.

novaos-connect-backend

Connect an application backend to a NovaOS agent - service account creation and scopes, safe credential storage, installing the agent for the service account, token minting, running agents with streaming and recovery, capacity limits, user-identity runs and returned writes, and generating client code. Use when an app (not a person) must call an agent.

Guided: novaos_workflow_start {"workflow":"connect_backend","params":{"app_name":"<app>","agent_id":"...","agent_name":"...","language":"python","dest":"./backend"}}.

Steps

  1. novaos_sa_setup_guide - browser steps: Org Console > Manage > Service Accounts > create (role sa-executor) > Secret & Rotation (credential) > Permissions (scopes, tool grants).
  2. novaos_sa_credentials_file {"ref":"<app>-sa"} - the USER pastes client id/secret/org id into the private file that opens. Never in chat.
  3. novaos_sa_token_test {"ref": ...} - org present, scopes present (agent:execute agent:read, mcp:tools:, llm:model:, rag:query ...). After permission changes a new token is needed.
  4. novaos_instance_install {"as":"<ref>", ...} - the service account's OWN instance id (Org Console > Service Accounts > account > Agents > Install agent is the UI way).
  5. novaos_ask_agent {"as":"<ref>","instance_id":...,"message":{"skill":"ping"}}.
  6. novaos_app_integration_code {"language":"python"|"typescript","dest":"..."} - writes a client with token caching, execute + idempotency, SSE + Last-Event-ID resume, poll-and-replay recovery (never re-run), 429/pod-quota handling, thread mapping.
  7. Config in the app's secret manager: NOVAOS_GATEWAY_URL, NOVAOS_IAM_URL (from novaos_env_show), NOVAOS_CLIENT_ID, NOVAOS_CLIENT_SECRET, NOVAOS_ORG_ID, NOVAOS_INSTANCE_ID.

Design rules to pass on

  • Keep conversation history in the app DB (NovaOS keeps only the first stream frame); send recent history in each input; input < 60k chars.
  • One idempotency key per turn; never resend after a timeout; poll the run instead.
  • ~8 concurrent SA runs per org: queue/back off and show "Waiting for capacity"; pod quota full -> "try again in a few minutes".
  • User-facing actions can run as the user (SPA token in X-NovaOS-User-Token, user's own instance); then MCP writes must be returned (persistence: "return") and applied by the backend. Background jobs stay on the service account.
  • Rotate: Secret & Rotation > Rotate secret -> update secret store -> fresh token -> test -> retire old.

novaos-knowledge-base

Create and use NovaOS knowledge bases - collections, uploading and parsing documents (PDF, Office, spreadsheets, scans with OCR), indexing, search, GraphRAG questions, and using it from an agent. Use for anything about documents, RAG, retrieval, parsers or knowledge graphs on NovaOS.

Guided: novaos_workflow_start {"workflow":"knowledge_base","params":{"name":"<name>","paths":["~/docs/a.pdf"],"query":"<test question>","graph":false}}.

Identity

Knowledge writes are best done as a service account (as: "<ref>", or set a default with novaos_sa_credentials_file {"make_default":true}); the token needs rag:parse rag:ingest rag:collections:write rag:query rag:collections:read. Agents read during runs with their execution token.

Steps

  1. novaos_kb_capabilities - which parsers exist here.
  2. novaos_kb_collection_create {"name": ...} - picks the embedding model for the region; stores the id locally. Collections are shared across ALL apps in the org: always use the stored id.
  3. novaos_kb_ingest {"collection": ..., "paths": [...]} - background job; skips duplicates (sha256) and files > 7 MiB (split PDFs first); OCR with "ocr": true for scans; .xls must be converted to .xlsx.
  4. novaos_kb_documents - every document should have chunks > 0.
  5. novaos_kb_search {"collection": ..., "query": ...} - shows hits. Scores are rank values (~0.005), not percentages: judge relevance by reading the text.
  6. GraphRAG (relationships across documents): novaos_kb_graph {"action":"build"} -> status -> local/global questions. "GraphRAG not enabled" means the env has it off.
  7. Compare parsers on a tricky file: novaos_kb_parse {"path": ..., "parser": "docling"} vs pymupdf.

Using it in an agent

Template agents: {"skill":"search","collection_id":"<id>","query":"..."}. In code: rag_search(ctx, collection_id, query) (planner off), dedupe, rerank with a flash model, answer with citations (file name + page). A failed search is not "no answer": say retrieval failed.

Pitfalls

query times out at 30 s - use search. Duplicate uploads create empty documents (handled). Spreadsheets: 500-row truncation; split into 50-row bands. Metadata values <= 256 chars, immutable after ingest. Don't delete a collection another app may use.

novaos-setup

Set up a computer (macOS, Linux or Windows) for NovaOS development from scratch - Python, Docker, novaos-cli, SDK virtual environment, NovaOS environment and sign-in. Use when someone has an empty machine, gets "command not found", or setup is broken.

Goal: novaos_doctor shows everything OK, novaos-cli has the right environment selected, and novaos_auth_status shows a signed-in user with an organization.

Steps

  1. novaos_doctor - read the table to the user in plain words (what is missing and why it matters).
  2. For a guided install: novaos_workflow_start {"workflow":"setup_machine"}. Or manually:
    • novaos_install_plan shows exact steps for this OS and which ones need the user's password.
    • Steps needing a password (Homebrew installer, apt, WSL): show the command in a code block and ask the user to paste it into Terminal. Wait for them.
    • Steps this server can run: ask, then novaos_install {"component": ...} (background job; poll novaos_job_status).
    • After Docker Desktop installs, the user must open it once and wait for "Engine running".
  3. Configure novaos-cli and sign in: novaos_workflow_start {"workflow":"setup_cli"} (US staging, the default) or with "params":{"env":"fde"} for FDE US. It runs, skipping anything already done:
    • install or upgrade novaos-cli to 2.2.1+ (novaos_install {"component":"novaos-cli"})
    • register the environment in ~/.novaos/environments.json (novaos_env_setup, i.e. novaos-cli env add) and select it (novaos-cli env use). This fixes the silent fallback to local when the CLI config names an undefined env.
    • browser sign-in (novaos_auth_login, i.e. novaos-cli --env <env> auth login); the user signs in, no password passes through the AI
    • organization: novaos_org_list, then continue with inputs: {"org_id": "..."} (novaos-cli auth org use)
    • publisher slug (novaos_publisher_show); if none: Developer > Publisher Profile, or ask an admin to add the user Environments: staging (US staging, default) and fde (FDE US). staging-eu is unverified. Switch any time with novaos_env_use {"env":"fde"} or {"env":"staging"}, then run setup_cli for that env: novaos-cli keeps one sign-in at a time, so each switch needs a browser sign-in, and the publisher slug differs per env.
  4. Check: novaos_auth_status shows the org, roles (developer to publish, platform-admin to approve) and no missing scopes.

The manual CLI equivalent is in novaos_docs {"guide":"02-auth-environments","section":"Quick setup"}.

OS notes

  • macOS: Homebrew first (user runs the installer; it asks for the Mac password and Command Line Tools).
  • Linux: glibc only for novaos-cli (no Alpine). Docker group membership needs a re-login.
  • Windows: Python/SDK work natively, but novaos-cli has no Windows binary. Use WSL 2 (Ubuntu) for scaffold/publish, with Docker Desktop's WSL backend.

Verify

novaos_doctor all OK, novaos_auth_status shows org + developer role. Then suggest build_agent.

novaos-ship-agent

Publish a NovaOS agent or MCP server, get it running and test it on NovaOS - lint, dry run, publish, review status, platform-admin approval (browser step), install for a user or service account, instance ids, test suite on NovaOS, version upgrades. Use when putting an agent live, testing it, or upgrading it.

Guided: novaos_workflow_start {"workflow":"ship_agent","params":{"project_dir":"..."}}.

Steps and what to tell the user

  1. novaos_agent_lint + novaos_manifest_validate + novaos_agent_card - fix every error first.
  2. novaos_agent_publish {"dry_run": true} - proves you may publish (needs sign-in, developer role, real publisher).
  3. Ask: "Publish to ? It builds and uploads an image and submits it for review." Then novaos_agent_publish (background job, minutes). Result: review id + agent id.
  4. novaos_wait_for_approval. Status meanings: PENDING_SCAN/SCANNING (automatic), PENDING_REVIEW (a platform admin must approve), APPROVED (activating), ACTIVE (live), REJECTED (read notes, fix, bump version).
    • Approval is a browser step at <marketplace>/admin/approvals (novaos_ui_guide {"task":"approvals"}). Only platform admins can approve. If the user is not one, give them the review id to send to their admin.
  5. Install: for the user novaos_instance_install; for a backend, install FOR the service account (as: "<ref>") - a personal instance can never be used by a service account. Note the instance id.
  6. Test ON NovaOS: novaos_test_deployed runs the cases in eval/suite.json as real runs (ping, a gateway model call, a clean failure, plus your own cases) and reports pass/fail, latency, cold/warm start, cost and run ids. The first run may take 30-70 s (cold pod). This is the agent's real test; nothing before it exercised NovaOS.
  7. For backends, run the suite again as the service account (as: "<ref>") on its own instance.
  8. Failures: novaos_run_diagnose {"run_id": ..., "agent_id": ...}; fix, bump version, publish, reinstall, test again.

Upgrades

Bump version (manifest + AGENT_VERSION) -> publish -> approval -> reinstall (novaos_instance_install again upgrades the caller's instance; installs never auto-update) -> novaos_test_deployed. Backends: update the stored instance id if it changed, restart.

MCP servers

novaos_mcp_name_check -> novaos_mcp_publish {"dry_run":true} -> publish -> platform admin Approves AND Activates (separate) -> Tool Health. Publish agents that depend on it only after it is active.

Facts

  • deployment_target ["chat"] lists it in the marketplace; ["api"] installs only via Admin > Agent Catalog.
  • Image scan "Not run" on FDE is normal. A new version is needed for every publish.
  • Never say the agent works before ACTIVE + a passing novaos_test_deployed. Never invent instance ids.

novaos-troubleshoot

Diagnose and explain NovaOS failures - CLI errors, publish failures, review rejections, run failures, stream cuts, capacity/429, scope and permission errors, MCP -32042/-32601, RAG and model errors - and decide whether it is a NovaOS platform bug, then draft a bug report. Use whenever something NovaOS-related fails.

Triage

  1. Get the exact error text. Run novaos_explain_error {"error_text": "..."} (add http_status / rpc_code if known).
  2. Run failed or hung: novaos_run_diagnose {"run_id": ..., "agent_id": ...} (run, events, trace, agent logs for that run).
  3. Agent code errors: novaos_agent_logs {"agent_id": ..., "run_id": ...} (agent id, not instance id). Reproduce with a case in novaos_test_deployed, never by running the agent locally.
  4. Setup: novaos_doctor, novaos_env_list, novaos_auth_status.

Tell the user who is at fault

  • Your input (wrong id, schema, name): show the fix.
  • Your setup (missing tool, Docker off, wrong env): show the fix or the install step.
  • Sign-in / permission (expired session, missing org, missing scope or role): sign in, switch org, ask an admin for the role/scope.
  • Capacity (429, pod quota): wait; not a bug.
  • NovaOS platform (5xx, broken response shape, persistent dispatch failures, stuck pipelines): say clearly "This looks like a NovaOS-side problem", include request/run ids, and offer novaos_report_bug. It drafts a report (title, env, versions, ids, request, expected vs actual, repro, workaround) for the user to file in ClickUp (GS - NovaOS > NovaOS Backlog/Bug List). Check novaos_docs {"guide":"13-known-issues"} first: it may be known.

Golden rules while fixing

  • Never re-run a run whose stream was cut; poll it (novaos_run_wait).
  • Retry 429 and dispatch failures (they start no run); never retry ingest/run timeouts blindly.
  • After permission changes, get a fresh token (sign in again / new SA token).
  • When unsure, search: novaos_docs {"query": "<symptom>"} and novaos_error_catalog {"filter": "..."}.