# Nasiko

> The OpenRuntime for agents, coding harnesses, frameworks and tools.

- [Introduction](https://docs.nasiko.com/index.md): The OpenRuntime for agents, coding harnesses, frameworks and tools.
- [Quickstart](https://docs.nasiko.com/quickstart.md): Find the coding agents already running on your machine, see what each one costs, and route one to the model you choose.
- [Quickstart: deploy an agent](https://docs.nasiko.com/quickstart-deploy.md): Scaffold an agent, run it locally, deploy it to your Nasiko cluster, and see its sessions and spend.
- [Install and connect](https://docs.nasiko.com/install.md): Install the Nasiko CLI, get a Nasiko cluster to connect to, and sign in.
- [Coding agents](https://docs.nasiko.com/coding-agents/overview.md): Find the coding agents already running on your machines, see what each one costs, and route them to the models you choose.
- [Discover and register coding agents](https://docs.nasiko.com/coding-agents/discover.md): List the coding harnesses on a machine, register them with your Nasiko cluster, and turn session reporting on or off.
- [Session reporting](https://docs.nasiko.com/coding-agents/session-reporting.md): What Nasiko records for each coding-agent turn, how turns are queued and delivered, and where they show up.
- [Route models](https://docs.nasiko.com/coding-agents/routing.md): Point a coding harness at Nasiko so its model calls go to the provider and model you choose.
- [Claude Code](https://docs.nasiko.com/coding-agents/claude-code.md): Discover Claude Code, report its sessions, and route its model calls through Nasiko.
- [Codex](https://docs.nasiko.com/coding-agents/codex.md): Discover Codex, report its sessions, and route its model calls through Nasiko.
- [OpenCode](https://docs.nasiko.com/coding-agents/opencode.md): Discover OpenCode, report its sessions, and route its model calls through Nasiko.
- [Cursor CLI](https://docs.nasiko.com/coding-agents/cursor.md): Discover the Cursor CLI and report its sessions to Nasiko.
- [Troubleshooting coding agents](https://docs.nasiko.com/coding-agents/troubleshooting.md): Discovery, reporting, routing, and cluster-binding problems.
- [TokenOps dashboard](https://docs.nasiko.com/tokenops/dashboard.md): Read spend, tokens, latency and attribution on the Overview and TokenOps screens, and export what you see.
- [Cost attribution](https://docs.nasiko.com/tokenops/attribution.md): One cost schema across harnesses, frameworks, models and teams — and why every call is attributed.
- [Reduce cost](https://docs.nasiko.com/tokenops/reduce-cost.md): Compression, context budgets, caching and routing cheaper models — the cost levers that ship today.
- [Pricing](https://docs.nasiko.com/tokenops/pricing.md): Where TokenOps rates come from, how estimated costs are marked, and how custom providers are priced.
- [LLM router](https://docs.nasiko.com/models/llm-router.md): Connect a model provider and assign a model to each reasoning level.
- [LLM configs](https://docs.nasiko.com/models/llm-configs.md): Reusable named configs that say which provider, model, key and fallbacks an agent or harness is routed to.
- [Providers](https://docs.nasiko.com/models/providers.md): Built-in model providers and custom OpenAI-compatible endpoints — LiteLLM, vLLM, Ollama, Azure, Bedrock, OpenRouter.
- [Model registry](https://docs.nasiko.com/models/model-registry.md): The cluster-wide (provider, tier) → model table the smart router falls through when a config does not pin a model.
- [Access control overview](https://docs.nasiko.com/governance/access-control/overview.md): Who can chat with, manage, and deploy agents — and which agents may call each other.
- [User and org management](https://docs.nasiko.com/governance/access-control/users-and-teams.md): Create users, assign roles, and organize departments and teams.
- [User → agent access](https://docs.nasiko.com/governance/access-control/agent-access.md): How ownership, the public flag, and grants decide who can chat with, update, or delete an agent.
- [Access control reference](https://docs.nasiko.com/governance/access-control/reference.md): How the two ACL layers are enforced, the exact capability thresholds, and org-scoped visibility.
- [User → agent MCP access](https://docs.nasiko.com/governance/tool-permissions.md): Which external tools and connectors an agent is allowed to call.
- [Human-in-the-loop approvals](https://docs.nasiko.com/governance/approvals.md): Pause an agent for a human decision — tool approval, extra input, or auth — then resume.
- [Routing and flow limits](https://docs.nasiko.com/governance/flow-limits.md): How the routing pipeline degrades, where it runs, and the flow guard that bounds every agent-to-agent call.
- [Secret management overview](https://docs.nasiko.com/governance/secrets/overview.md): How Nasiko protects agent secrets and platform identity credentials.
- [Managing your agent's secrets](https://docs.nasiko.com/governance/secrets/agent-secrets.md): Set, inspect, and rotate encrypted agent secrets via the CLI or API.
- [Setting up SSO login](https://docs.nasiko.com/governance/sso-and-scim.md): Configure single sign-on with your identity provider using OIDC.
- [Setting up an organization](https://docs.nasiko.com/governance/organizations.md): Create departments, teams, and users, and grant them agent access with the admin CLI.
- [Build and deploy agents](https://docs.nasiko.com/build/overview.md): Run agents built on any framework: scaffold, run locally, deploy, version, and operate.
- [Scaffolding a new agent](https://docs.nasiko.com/build/scaffold.md): Generate an agent project from a template and manage its AgentCard.json.
- [Running and chatting locally](https://docs.nasiko.com/build/run-locally.md): Build, run, and chat with your agent before it touches a cluster.
- [Deploying and managing agents](https://docs.nasiko.com/build/deploy.md): Get your agent onto a cluster, then operate it — logs, scaling, restarts, secrets, teardown.
- [Versions and rollback](https://docs.nasiko.com/build/versions.md): Immutable deploy versions, history, reupload, and rollback.
- [Operate agents](https://docs.nasiko.com/build/operate.md): Logs, scale, restarts, deployments, writable storage, and teardown after an agent is deployed.
- [A2A agents and frameworks](https://docs.nasiko.com/build/a2a.md): What your container must expose to run on Nasiko, and how the platform talks to it.
- [Routing engine](https://docs.nasiko.com/build/routing-engine.md): How Nasiko picks an agent for a query, the knobs to tune, and how to inspect decisions.
- [MAF](https://docs.nasiko.com/build/workflows.md): Chain multiple agents into a repeatable, trackable workflow.
- [MCP gateway overview](https://docs.nasiko.com/build/mcp/overview.md): How agents get tool access: connectors, per-agent permissions, and the gateway endpoint.
- [Connect an external MCP server](https://docs.nasiko.com/build/mcp/external-server.md): Register an MCP server by URL, connect credentials, share it, and handle OAuth 2.1.
- [Deploy your own MCP server](https://docs.nasiko.com/build/mcp/deploy-server.md): Upload your MCP server's source and have Nasiko build, harden, and deploy it as a connector.
- [Connect your agent to the MCP gateway](https://docs.nasiko.com/build/mcp/agent-integration.md): Wire any agent, in any language or framework, to discover and call every tool a user has connected — with no hardcoded tool names.
- [Artifact registry](https://docs.nasiko.com/build/registry/overview.md): Push, pull, and browse agents, skills, tools, and other artifacts.
- [Sample agents](https://docs.nasiko.com/build/registry/sample-agents.md): Curated example agents — what each demonstrates, and how to deploy one.
- [Dashboard overview](https://docs.nasiko.com/dashboard/overview.md): The Nasiko web app — Overview, TokenOps, sessions, agents, routing, and settings.
- [Chat](https://docs.nasiko.com/dashboard/chat.md): Let Nasiko pick an agent, or talk to one directly.
- [Observability](https://docs.nasiko.com/dashboard/sessions-and-traces.md): Review past conversations, trace every agent hop, and follow a multi-agent flow.
- [Agents](https://docs.nasiko.com/dashboard/agents.md): Browse the catalog, deploy agents, manage the ones you've deployed, and watch builds.
- [Workflows](https://docs.nasiko.com/dashboard/workflows.md): The dashboard screens for multi-agent workflows and their executions.
- [MCP gateway](https://docs.nasiko.com/dashboard/mcp-gateway.md): Register MCP servers, upload your own, and control which tools each agent may call.
- [Administration](https://docs.nasiko.com/dashboard/settings.md): Manage agent secrets, platform settings, users, teams, departments, and access.
- [Artifact registry](https://docs.nasiko.com/dashboard/artifact-registry.md): Browse, inspect, and publish agents, skills, and other artifacts in the registry's web app.
- [Deploy the stack](https://docs.nasiko.com/self-hosting/deploy.md): Run Nasiko with Docker Compose or nasiko up, and what each service is for.
- [Server configuration](https://docs.nasiko.com/self-hosting/configuration.md): Environment variables for a self-hosted Nasiko server. Names only — never paste secrets into docs or tickets.
- [Agent hosting](https://docs.nasiko.com/self-hosting/agent-hosting.md): Docker vs Kubernetes hosting, how images reach the cluster, and how server-side builds work.
- [Backup and restore](https://docs.nasiko.com/self-hosting/backup-and-restore.md): What state the platform holds where, and what's on you to back up.
- [CLI reference](https://docs.nasiko.com/reference/cli/overview.md): Every nasiko command, grouped the way nasiko --help groups them.
- [Setup commands](https://docs.nasiko.com/reference/cli/setup.md): up, down, connect, disconnect, use, clusters, status, auth, budget, context-strategy.
- [Coding agents commands](https://docs.nasiko.com/reference/cli/coding-agents.md): discover, install, uninstall, sync, connect, disconnect, status, claude.
- [Create commands](https://docs.nasiko.com/reference/cli/create.md): new, build, run, validate, card, skill.
- [Operate commands](https://docs.nasiko.com/reference/cli/operate.md): deploy, push, upload, import, ps, logs, lifecycle, deployments, versions, rollback, secrets.
- [Chat commands](https://docs.nasiko.com/reference/cli/chat.md): chat, sessions, create-session, history, delete-session.
- [Observe commands](https://docs.nasiko.com/reference/cli/observe.md): sessions, traces, spans, project stats, TokenOps dashboard and insights.
- [Model commands](https://docs.nasiko.com/reference/cli/models.md): llm-config and model-registry.
- [MCP commands](https://docs.nasiko.com/reference/cli/mcp.md): catalog, connect, connectors, credentials, OAuth, agent-tools.
- [Workflow commands](https://docs.nasiko.com/reference/cli/workflows.md): nasiko maf workflow and execution.
- [Integration commands](https://docs.nasiko.com/reference/cli/integrations.md): agents catalog, github, registry.
- [Enterprise CLI](https://docs.nasiko.com/reference/cli/enterprise.md): nasiko-ee: provision, organizations, access, registry publish.
- [API reference](https://docs.nasiko.com/api-reference/overview.md): Authentication, conventions, and where each surface is documented.
- [LLM router API](https://docs.nasiko.com/api-reference/llm-router.md): OpenAI-, Anthropic-, and Gemini-compatible endpoints the Nasiko LLM router serves.
- [Coding agents API](https://docs.nasiko.com/api-reference/coding-agents.md): Register a harness identity and ingest session-turn telemetry.
- [Approvals API](https://docs.nasiko.com/api-reference/approvals.md): Human-in-the-loop request lifecycle.
- [OCI registry API](https://docs.nasiko.com/api-reference/oci-registry.md): Embedded OCI Distribution v2 used by nasiko push, deploy, and agent pulls.
- [List agents visible to the caller (superuser → all; otherwise owner ∪](https://docs.nasiko.com/api-reference/catalog/list-agents-visible-to-the-caller-superuser-→-all;-otherwise-owner-∪.md): List agents visible to the caller (superuser → all; otherwise owner ∪ public ∪ user-grant — see `agent_access_predicate`).
- [Register a new agent in the catalog.](https://docs.nasiko.com/api-reference/catalog/register-a-new-agent-in-the-catalog.md)
- [Discover agents that have a skill tagged `tag`. Access-scoped like `list`](https://docs.nasiko.com/api-reference/catalog/discover-agents-that-have-a-skill-tagged-`tag`-access-scoped-like-`list`.md): Discover agents that have a skill tagged `tag`. Access-scoped like `list` (superuser → all; otherwise owner ∪ public ∪ user-grant — see `agent_access_predicate`). Uses the GIN `idx_agent_skills_tags` via the `@>` containment operator and `EXISTS` (no join fan-out / DISTINCT).
- [Post apiagentscoding integrations](https://docs.nasiko.com/api-reference/catalog/post-apiagentscoding-integrations.md)
- [List an agent's secret names (never decrypted values). Owner-or-superuser only.](https://docs.nasiko.com/api-reference/catalog/list-an-agents-secret-names-never-decrypted-values-owner-or-superuser-only.md)
- [Create or overwrite one of an agent's secrets. Owner-or-superuser only.](https://docs.nasiko.com/api-reference/catalog/create-or-overwrite-one-of-an-agents-secrets-owner-or-superuser-only.md)
- [Copy a subset of the caller's own user-scoped secrets into an agent's](https://docs.nasiko.com/api-reference/catalog/copy-a-subset-of-the-callers-own-user-scoped-secrets-into-an-agents.md): Copy a subset of the caller's own user-scoped secrets into an agent's secrets_env, re-encrypting them under the agent's key. Owner-or-superuser only.
- [Delete one of an agent's secrets. Owner-or-superuser only.](https://docs.nasiko.com/api-reference/catalog/delete-one-of-an-agents-secrets-owner-or-superuser-only.md)
- [Fetch a single agent by UUID or name, rendered as an A2A AgentCard-shaped envelope.](https://docs.nasiko.com/api-reference/catalog/fetch-a-single-agent-by-uuid-or-name-rendered-as-an-a2a-agentcard-shaped-envelope.md)
- [Update an agent's catalog metadata. Owner-or-superuser only.](https://docs.nasiko.com/api-reference/catalog/update-an-agents-catalog-metadata-owner-or-superuser-only.md)
- [Delete an agent and tear down its running containers (best-effort).](https://docs.nasiko.com/api-reference/catalog/delete-an-agent-and-tear-down-its-running-containers-best-effort.md): Delete an agent and tear down its running containers (best-effort). Owner-or-superuser only.
- [List an agent's build/version history.](https://docs.nasiko.com/api-reference/catalog/list-an-agents-buildversion-history.md)
- [Delete a specific version record. Rejects deleting the currently active](https://docs.nasiko.com/api-reference/catalog/delete-a-specific-version-record-rejects-deleting-the-currently-active.md): Delete a specific version record. Rejects deleting the currently active version — roll back to another version first. Owner-or-superuser only.
- [Clone a GitHub repo (via the caller's stored OAuth token), then build and deploy it.](https://docs.nasiko.com/api-reference/catalog/clone-a-github-repo-via-the-callers-stored-oauth-token-then-build-and-deploy-it.md)
- [Import an agent from an OCI registry: a source-tarball layer is built and](https://docs.nasiko.com/api-reference/catalog/import-an-agent-from-an-oci-registry:-a-source-tarball-layer-is-built-and.md): Import an agent from an OCI registry: a source-tarball layer is built and deployed like `/import/upload`; a plain container image is pulled and deployed directly.
- [Upload a source archive and synchronously build + deploy it as an agent.](https://docs.nasiko.com/api-reference/catalog/upload-a-source-archive-and-synchronously-build-+-deploy-it-as-an-agent.md): Meant to be quick and direct, not production-grade robust: unlike its sibling `/api/agents/upload` (`oss/server/src/agents/upload.rs`), which is asynchronous, tracked via `upload_status`, and retried on failure through a real job queue, this runs the whole build-and-deploy pipeline synchronously ins…
- [Look up an agent by its UUID or name (registry-entry lookup).](https://docs.nasiko.com/api-reference/catalog/look-up-an-agent-by-its-uuid-or-name-registry-entry-lookup.md): Look up an agent by its UUID or name (registry-entry lookup). Equivalent to GET /agents/{id} but exposed at the /registries/ path for clients that use the registry-centric URL scheme.
- [Returns agents accessible to the current user: owned + public + explicitly granted.](https://docs.nasiko.com/api-reference/catalog/returns-agents-accessible-to-the-current-user:-owned-+-public-+-explicitly-granted.md): Returns agents accessible to the current user: owned + public + explicitly granted. Supports optional `?q` (name/description search), `?status`, `?limit`, `?offset`. Superusers see all agents.
- [search](https://docs.nasiko.com/api-reference/catalog/search.md): Agent-only search.  Scoring: GREATEST across (name×2.8, description×2.0, tag score) with tiered exact/prefix/contains scoring.  Minimum query length: 2 chars.
- [Search the user directory. The user directory (usernames + emails) is](https://docs.nasiko.com/api-reference/catalog/search-the-user-directory-the-user-directory-usernames-+-emails-is.md): Search the user directory. The user directory (usernames + emails) is sensitive (CAT-4), so results are scoped via `AuthService::org_visible_user_ids` — OSS returns `None` (unrestricted, no org hierarchy to scope by); EE restricts non-admin callers to their own department/team, same as the MCP share…
- [Restart an agent's deployment (K8s: scale-to-1; Docker: destroy + recreate).](https://docs.nasiko.com/api-reference/agents/restart-an-agents-deployment-k8s:-scale-to-1;-docker:-destroy-+-recreate.md): Restart an agent's deployment (K8s: scale-to-1; Docker: destroy + recreate). Owner-or-superuser only.
- [List the caller's deployments (superuser → all, newest 50 first). Callers](https://docs.nasiko.com/api-reference/agents/list-the-callers-deployments-superuser-→-all-newest-50-first-callers.md): List the caller's deployments (superuser → all, newest 50 first). Callers below deployer role get `200 {"available": false}` instead of an error — see `nasiko_server::unavailable`.
- [Server-Sent Events stream of `{"status": ..., "build_id": ...}` on each](https://docs.nasiko.com/api-reference/agents/server-sent-events-stream-of-`-`-on-each.md): Server-Sent Events stream of `{"status": ..., "build_id": ...}` on each status change, polling every 3s until the build reaches `success`/`failed` (or `{"status": "not_found"}` once, if the build id doesn't exist). Callers below deployer role get `200 {"available": false}` instead.
- [The platform fallback env vars the CP injects into every deployment](https://docs.nasiko.com/api-reference/agents/the-platform-fallback-env-vars-the-cp-injects-into-every-deployment.md): The platform fallback env vars the CP injects into every deployment (OPENAI_* today). Consumed by `nasiko run` so a local container starts with the same defaults a CP deployment would get. Deployer-gated: anyone who can deploy already receives these values inside the containers they deploy.
- [List agents the caller has uploaded (superuser → all), one row per agent](https://docs.nasiko.com/api-reference/agents/list-agents-the-caller-has-uploaded-superuser-→-all-one-row-per-agent.md): List agents the caller has uploaded (superuser → all), one row per agent (most recent upload), joined with live catalog metadata.
- [Register a new agent from a source zip and queue an asynchronous](https://docs.nasiko.com/api-reference/agents/register-a-new-agent-from-a-source-zip-and-queue-an-asynchronous.md): Register a new agent from a source zip and queue an asynchronous build-and-deploy job (poll via `/uploads/{upload_id}` or `/deploys/{build_id}/stream`). Deployer role required.
- [List the caller's uploads/builds, newest first (superuser → all). Also](https://docs.nasiko.com/api-reference/agents/list-the-callers-uploadsbuilds-newest-first-superuser-→-all-also.md): List the caller's uploads/builds, newest first (superuser → all). Also mounted at the top-level `/api/upload-status` alias (`status_router`). Callers below deployer role get `200 {"available": false}` instead of an error.
- [Get the status of a single upload/build (by `upload_id`, i.e. the build id](https://docs.nasiko.com/api-reference/agents/get-the-status-of-a-single-uploadbuild-by-`upload_id`-ie-the-build-id.md): Get the status of a single upload/build (by `upload_id`, i.e. the build id as a string). Callers below deployer role, or a non-owner non-superuser, get `200 {"available": false}` instead of an error.
- [Get an agent's current (non-stopped) deployment. Callers who can't deploy](https://docs.nasiko.com/api-reference/agents/get-an-agents-current-non-stopped-deployment-callers-who-cant-deploy.md): Get an agent's current (non-stopped) deployment. Callers who can't deploy or can't access the agent get `200 {"available": false}` instead of an error.
- [The agent's **resolved** routing config (attached → owner default →](https://docs.nasiko.com/api-reference/agents/the-agents-**resolved**-routing-config-attached-→-owner-default-→.md): The agent's **resolved** routing config (attached → owner default → none), which config is attached, its source, and the inbound format. Owner-or-superuser only.
- [Detach the config and clear the agent-level pin in one call. Owner-or-superuser only.](https://docs.nasiko.com/api-reference/agents/detach-the-config-and-clear-the-agent-level-pin-in-one-call-owner-or-superuser-only.md)
- [Attach/detach a reusable LLM config to an agent, and optionally change the](https://docs.nasiko.com/api-reference/agents/attachdetach-a-reusable-llm-config-to-an-agent-and-optionally-change-the.md): Attach/detach a reusable LLM config to an agent, and optionally change the inbound SDK format. A config can only be attached if it belongs to the agent owner. Owner-or-superuser only.
- [Issue a short-lived agent identity token for a local SDK process. The caller](https://docs.nasiko.com/api-reference/agents/issue-a-short-lived-agent-identity-token-for-a-local-sdk-process-the-caller.md): Issue a short-lived agent identity token for a local SDK process. The caller must own the agent; the signing secret never leaves the control plane.
- [Roll back to a previous rollback-eligible version (defaults to the most](https://docs.nasiko.com/api-reference/agents/roll-back-to-a-previous-rollback-eligible-version-defaults-to-the-most.md): Roll back to a previous rollback-eligible version (defaults to the most recent one) — a synthetic build record so the same SSE polling path works, no image rebuild. Owner-or-superuser only.
- [Rebuild and redeploy an agent from a new source archive, bumping its](https://docs.nasiko.com/api-reference/agents/rebuild-and-redeploy-an-agent-from-a-new-source-archive-bumping-its.md): Rebuild and redeploy an agent from a new source archive, bumping its version. Runs the build asynchronously (poll via `/uploads/{id}` SSE or `/deploys/{build_id}/stream`). Owner-or-superuser only.
- [List the caller's LLM configs, ordered by name.](https://docs.nasiko.com/api-reference/llm-router/list-the-callers-llm-configs-ordered-by-name.md)
- [Create a named LLM config owned by the caller, optionally storing the](https://docs.nasiko.com/api-reference/llm-router/create-a-named-llm-config-owned-by-the-caller-optionally-storing-the.md): Create a named LLM config owned by the caller, optionally storing the referenced API-key secret and/or marking it as the caller's default.
- [Fetch one of the caller's configs; configs the caller doesn't own read as 404.](https://docs.nasiko.com/api-reference/llm-router/fetch-one-of-the-callers-configs;-configs-the-caller-doesnt-own-read-as-404.md)
- [Soft-delete one of the caller's configs. Fails while any live agent still](https://docs.nasiko.com/api-reference/llm-router/soft-delete-one-of-the-callers-configs-fails-while-any-live-agent-still.md): Soft-delete one of the caller's configs. Fails while any live agent still has the config attached.
- [Partially update one of the caller's configs; absent fields keep their](https://docs.nasiko.com/api-reference/llm-router/partially-update-one-of-the-callers-configs;-absent-fields-keep-their.md): Partially update one of the caller's configs; absent fields keep their current value. Use `POST /api/llm-configs/{id}/default` to change the default.
- [Mark one of the caller's configs as their default, clearing any prior default.](https://docs.nasiko.com/api-reference/llm-router/mark-one-of-the-callers-configs-as-their-default-clearing-any-prior-default.md)
- [Clear the default flag on one of the caller's configs, leaving them with no](https://docs.nasiko.com/api-reference/llm-router/clear-the-default-flag-on-one-of-the-callers-configs-leaving-them-with-no.md): Agents that were falling back to this default resolve to `source: "none"` afterwards and use the platform key path (see `resolve_agent_config`).
- [List every provider/model with a currently-effective `model_pricing` row,](https://docs.nasiko.com/api-reference/llm-router/list-every-providermodel-with-a-currently-effective-`model_pricing`-row.md): List every provider/model with a currently-effective `model_pricing` row, grouped by provider. Backs the UI provider/model dropdown.
- [List every configured tier→model mapping, ordered by provider and tier.](https://docs.nasiko.com/api-reference/llm-router/list-every-configured-tier→model-mapping-ordered-by-provider-and-tier.md)
- [Upsert one `(provider, tier)` → model mapping. Superuser only.](https://docs.nasiko.com/api-reference/llm-router/upsert-one-`provider-tier`-→-model-mapping-superuser-only.md)
- [Agent-facing MCP JSON-RPC gateway. Generic `tools/list` / `tools/call`](https://docs.nasiko.com/api-reference/mcp/agent-facing-mcp-json-rpc-gateway-generic-`toolslist`-`toolscall`.md): Authorization rules (docs/MCP_GATEWAY_AGENT_AUTH.md §2.4), all failing closed: 1. bearer token missing/unknown/revoked → 401 2. `tools/list` (and initialize/ping) → allowed with agent-only identity 3. `tools/call` with no/unknown/dead-flow traceparent → 403 4. `tools/call` where the agent is not a r…
- [`GET /api/mcp/agents/{agent_id}/connectors` — connectors + per-agent status.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpagents-connectors`-—-connectors-+-per-agent-status.md): Same relaxed gate as `list_tool_rules` below (and `set_connector_access`/ `list_connector_tools`, already relaxed by `a9012ded`/`56e46b07`): a caller who can't manage the whole agent still sees the connector(s) they themselves can reach (narrowed, not blocked outright) — otherwise this endpoint (the…
- [`PUT /api/mcp/agents/{agent_id}/connectors/{connector_id}` — toggle a connector.](https://docs.nasiko.com/api-reference/mcp/`put-apimcpagents-connectors-`-—-toggle-a-connector.md): Allows either full agent management, or the connector's own owner acting on their connector once it's been granted to this agent (see `ensure_can_manage_agent_connector`) — a connector owner can enable/disable their own connector on someone else's agent without managing the agent itself.
- [`GET /api/mcp/agents/{agent_id}/connectors/{connector_id}/tools` — tools + stances.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpagents-connectors-tools`-—-tools-+-stances.md): Same relaxed gate as `set_connector_access`: the connector's own owner can view its tools/stances on this agent once it's been granted here.
- [`DELETE /api/mcp/agents/{agent_id}/permissions` — reset to all-allowed.](https://docs.nasiko.com/api-reference/mcp/`delete-apimcpagents-permissions`-—-reset-to-all-allowed.md)
- [`GET /api/mcp/agents/{agent_id}/tools` — the agent's current tool rules.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpagents-tools`-—-the-agents-current-tool-rules.md): Agent-wide (every connector's rules at once), so a non-agent-manager never gets the unfiltered view: if they can't manage the whole agent, the result is narrowed to only the connector(s) they themselves can manage (`can_manage_agent_connector` — reachable, and either already granted to this agent or…
- [`PUT /api/mcp/agents/{agent_id}/tools` — batch upsert tool rules.](https://docs.nasiko.com/api-reference/mcp/`put-apimcpagents-tools`-—-batch-upsert-tool-rules.md): Each rule names its own `connector_id`, so the gate is per-connector: full agent management, or (for each distinct connector referenced) that connector's own owner acting on a connector already granted to this agent — same relaxed rule as `set_connector_access`. An empty batch still requires full ag…
- [`GET /api/mcp/auth-configs` — list platform Composio connectors (admin).](https://docs.nasiko.com/api-reference/mcp/`get-apimcpauth-configs`-—-list-platform-composio-connectors-admin.md)
- [`POST /api/mcp/auth-configs` — register a platform Composio connector (admin).](https://docs.nasiko.com/api-reference/mcp/`post-apimcpauth-configs`-—-register-a-platform-composio-connector-admin.md)
- [`DELETE /api/mcp/auth-configs/{connector_id}` — remove a composio connector (admin).](https://docs.nasiko.com/api-reference/mcp/`delete-apimcpauth-configs-`-—-remove-a-composio-connector-admin.md)
- [`PATCH /api/mcp/auth-configs/{connector_id}` — edit composio catalog metadata (admin).](https://docs.nasiko.com/api-reference/mcp/`patch-apimcpauth-configs-`-—-edit-composio-catalog-metadata-admin.md)
- [`GET /api/mcp/catalog` — connectable services, credential-free.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpcatalog`-—-connectable-services-credential-free.md)
- [`GET /api/mcp/composio/toolkits` — platform Composio toolkits only.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpcomposiotoolkits`-—-platform-composio-toolkits-only.md)
- [`POST /api/mcp/connect` — connect any connector type.](https://docs.nasiko.com/api-reference/mcp/`post-apimcpconnect`-—-connect-any-connector-type.md)
- [`GET /api/mcp/connections` — the caller's connections.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpconnections`-—-the-callers-connections.md)
- [`DELETE /api/mcp/connections/{connector_id}` — disconnect the caller's connection.](https://docs.nasiko.com/api-reference/mcp/`delete-apimcpconnections-`-—-disconnect-the-callers-connection.md)
- [`GET /api/mcp/connectors` — custom connectors visible to the caller.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpconnectors`-—-custom-connectors-visible-to-the-caller.md)
- [`POST /api/mcp/connectors` — register a custom MCP connector (owned by caller).](https://docs.nasiko.com/api-reference/mcp/`post-apimcpconnectors`-—-register-a-custom-mcp-connector-owned-by-caller.md)
- [list my uploads](https://docs.nasiko.com/api-reference/mcp/list-my-uploads.md): `GET /api/mcp/connectors/my-uploads` — list uploaded MCP connectors owned by the caller, mirroring `/api/agents/my-uploads`.
- [`GET /api/mcp/connectors/pinned` — the caller's pinned connectors.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpconnectorspinned`-—-the-callers-pinned-connectors.md)
- [`POST /api/mcp/connectors/probe` — detect a server's auth type.](https://docs.nasiko.com/api-reference/mcp/`post-apimcpconnectorsprobe`-—-detect-a-servers-auth-type.md)
- [`GET /api/mcp/connectors/recent` — the caller's recently-used connectors.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpconnectorsrecent`-—-the-callers-recently-used-connectors.md)
- [`POST /api/mcp/connectors/upload` — multipart zip upload.](https://docs.nasiko.com/api-reference/mcp/`post-apimcpconnectorsupload`-—-multipart-zip-upload.md)
- [upload github](https://docs.nasiko.com/api-reference/mcp/upload-github.md): `POST /api/mcp/connectors/upload-github` — clone a repo instead of a zip. Re-validates `github_url` (HTTPS-only + host allowlist) the same way `execute_build`/`execute_mcp_server_build` already do at clone time — this is a defence-in-depth check at the handler layer, not the only one.
- [`GET /api/mcp/connectors/{id}` — a single connector, 404 if not reachable.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpconnectors-`-—-a-single-connector-404-if-not-reachable.md)
- [`DELETE /api/mcp/connectors/{id}` — delete an owned connector (or any, if admin).](https://docs.nasiko.com/api-reference/mcp/`delete-apimcpconnectors-`-—-delete-an-owned-connector-or-any-if-admin.md)
- [`PATCH /api/mcp/connectors/{id}` — update an owned connector.](https://docs.nasiko.com/api-reference/mcp/`patch-apimcpconnectors-`-—-update-an-owned-connector.md)
- [build logs](https://docs.nasiko.com/api-reference/mcp/build-logs.md): `GET /api/mcp/connectors/{id}/build-logs` — same ownership check as `build_status`, real container stdout/stderr via `ContainerRuntime::logs`.
- [`GET /api/mcp/connectors/{id}/build-status` — plain polling JSON, no SSE.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpconnectors-build-status`-—-plain-polling-json-no-sse.md)
- [`GET /api/mcp/connectors/{id}/consumers` — agents that have this connector configured.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpconnectors-consumers`-—-agents-that-have-this-connector-configured.md)
- [`POST /api/mcp/connectors/{id}/credential` — store the caller's credential.](https://docs.nasiko.com/api-reference/mcp/`post-apimcpconnectors-credential`-—-store-the-callers-credential.md)
- [`DELETE /api/mcp/connectors/{id}/credential` — remove the caller's credential.](https://docs.nasiko.com/api-reference/mcp/`delete-apimcpconnectors-credential`-—-remove-the-callers-credential.md)
- [`GET /api/mcp/connectors/{id}/credential/status` — whether a credential exists.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpconnectors-credentialstatus`-—-whether-a-credential-exists.md)
- [`GET /api/mcp/connectors/{id}/grants` — list a connector's grants.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpconnectors-grants`-—-list-a-connectors-grants.md)
- [`POST /api/mcp/connectors/{id}/grants/agents/{agent_id}` — grant to an agent.](https://docs.nasiko.com/api-reference/mcp/`post-apimcpconnectors-grantsagents-`-—-grant-to-an-agent.md)
- [`DELETE /api/mcp/connectors/{id}/grants/agents/{agent_id}` — revoke from an agent.](https://docs.nasiko.com/api-reference/mcp/`delete-apimcpconnectors-grantsagents-`-—-revoke-from-an-agent.md)
- [`POST /api/mcp/connectors/{id}/grants/public` — make connector public.](https://docs.nasiko.com/api-reference/mcp/`post-apimcpconnectors-grantspublic`-—-make-connector-public.md)
- [`DELETE /api/mcp/connectors/{id}/grants/public` — revoke public access.](https://docs.nasiko.com/api-reference/mcp/`delete-apimcpconnectors-grantspublic`-—-revoke-public-access.md)
- [`POST /api/mcp/connectors/{id}/grants/users/{user_id}` — grant to a user.](https://docs.nasiko.com/api-reference/mcp/`post-apimcpconnectors-grantsusers-`-—-grant-to-a-user.md)
- [`DELETE /api/mcp/connectors/{id}/grants/users/{user_id}` — revoke from a user.](https://docs.nasiko.com/api-reference/mcp/`delete-apimcpconnectors-grantsusers-`-—-revoke-from-a-user.md)
- [`POST /api/mcp/connectors/{id}/oauth/authorize` — start the OAuth 2.1 flow.](https://docs.nasiko.com/api-reference/mcp/`post-apimcpconnectors-oauthauthorize`-—-start-the-oauth-21-flow.md)
- [`GET /api/mcp/connectors/{id}/oauth/status` — token presence + expiry.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpconnectors-oauthstatus`-—-token-presence-+-expiry.md)
- [`DELETE /api/mcp/connectors/{id}/oauth/token` — remove the caller's token.](https://docs.nasiko.com/api-reference/mcp/`delete-apimcpconnectors-oauthtoken`-—-remove-the-callers-token.md)
- [`POST /api/mcp/connectors/{id}/pin` — pin for quick access.](https://docs.nasiko.com/api-reference/mcp/`post-apimcpconnectors-pin`-—-pin-for-quick-access.md)
- [`DELETE /api/mcp/connectors/{id}/pin` — unpin.](https://docs.nasiko.com/api-reference/mcp/`delete-apimcpconnectors-pin`-—-unpin.md)
- [`GET /api/mcp/oauth/callback` — public browser redirect target (HTML, not JSON).](https://docs.nasiko.com/api-reference/mcp/`get-apimcpoauthcallback`-—-public-browser-redirect-target-html-not-json.md)
- [`GET /api/mcp/share-targets?q=` — search users to share a connector with.](https://docs.nasiko.com/api-reference/mcp/`get-apimcpshare-targets?q=`-—-search-users-to-share-a-connector-with.md)
- [resolve target](https://docs.nasiko.com/api-reference/mcp/resolve-target.md): `GET /api/mcp/share-targets/resolve?username=` — exact username → user_id, for `share add`/`share remove` to target someone outside the caller's own org-visibility scope (unlike `search_targets` above, this is intentionally NOT scoped — see `service::connectors::resolve_share_target`'s doc comment).
- [Trace/cost/latency stats for one agent (accepts a UUID or agent name).](https://docs.nasiko.com/api-reference/observability/tracecostlatency-stats-for-one-agent-accepts-a-uuid-or-agent-name.md)
- [`GET /api/observe/agents/{agent_ref}/logs`](https://docs.nasiko.com/api-reference/observability/`get-apiobserveagents-logs`.md): `agent_ref` may be a UUID or an agent name (e.g. `my-agent`).
- [`GET /api/observe/agents/{agent_ref}/logs/stream`](https://docs.nasiko.com/api-reference/observability/`get-apiobserveagents-logsstream`.md): SSE live-tail stream. `agent_ref` may be a UUID or agent name.
- [Windowed replica-hours per agent (billing source of truth), optionally bucketed.](https://docs.nasiko.com/api-reference/observability/windowed-replica-hours-per-agent-billing-source-of-truth-optionally-bucketed.md)
- [FinOps dashboard: per-agent cost/token rows plus fleet-wide summary.](https://docs.nasiko.com/api-reference/observability/finops-dashboard:-per-agent-costtoken-rows-plus-fleet-wide-summary.md)
- [LLM-generated cost insights from the caller-supplied FinOps KPI snapshot.](https://docs.nasiko.com/api-reference/observability/llm-generated-cost-insights-from-the-caller-supplied-finops-kpi-snapshot.md)
- [List chat sessions (DB-authoritative, enriched from Tempo when available).](https://docs.nasiko.com/api-reference/observability/list-chat-sessions-db-authoritative-enriched-from-tempo-when-available.md)
- [Detail for one session: traces, token usage, and cost summary.](https://docs.nasiko.com/api-reference/observability/detail-for-one-session:-traces-token-usage-and-cost-summary.md)
- [Detail for one span: attributes, input/output content, and cost.](https://docs.nasiko.com/api-reference/observability/detail-for-one-span:-attributes-inputoutput-content-and-cost.md)
- [Detail for one trace: full span tree with per-span token/cost attribution.](https://docs.nasiko.com/api-reference/observability/detail-for-one-trace:-full-span-tree-with-per-span-tokencost-attribution.md)
- [Server-side A2A dispatch endpoint. Accepts JSONRPC `message/send` or `message/stream`.](https://docs.nasiko.com/api-reference/orchestrator/server-side-a2a-dispatch-endpoint-accepts-jsonrpc-`messagesend`-or-`messagestream`.md): No gateway required: the server validates the JWT and enforces authorization itself (see `require_auth`/`Claims`). This handler is the production A2A path.
- [`POST /api/a2a/upload` — multipart/form-data A2A dispatch entry point.](https://docs.nasiko.com/api-reference/orchestrator/`post-apia2aupload`-—-multipartform-data-a2a-dispatch-entry-point.md): Accepts: - `query`   (text field, required) — the user's question - Any number of additional fields treated as file attachments
- [Aggregated agent-selection stats from the `agent_selection_stats`](https://docs.nasiko.com/api-reference/orchestrator/aggregated-agent-selection-stats-from-the-`agent_selection_stats`.md): Aggregated agent-selection stats from the `agent_selection_stats` materialized view (newest date, most-selected agent first; max 200 rows).
- [List the caller's secrets (names + metadata only — never decrypted values).](https://docs.nasiko.com/api-reference/secrets/list-the-callers-secrets-names-+-metadata-only-—-never-decrypted-values.md)
- [Create a secret, or overwrite the value if one with this name already exists.](https://docs.nasiko.com/api-reference/secrets/create-a-secret-or-overwrite-the-value-if-one-with-this-name-already-exists.md)
- [Fetch and decrypt a single secret's value.](https://docs.nasiko.com/api-reference/secrets/fetch-and-decrypt-a-single-secrets-value.md)
- [Overwrite an existing secret's value.](https://docs.nasiko.com/api-reference/secrets/overwrite-an-existing-secrets-value.md)
- [Delete a secret.](https://docs.nasiko.com/api-reference/secrets/delete-a-secret.md)
- [Per-agent usage breakdown for the caller, ordered by total tokens.](https://docs.nasiko.com/api-reference/usage/per-agent-usage-breakdown-for-the-caller-ordered-by-total-tokens.md)
- [Per-provider/model usage breakdown for the caller, ordered by total tokens.](https://docs.nasiko.com/api-reference/usage/per-providermodel-usage-breakdown-for-the-caller-ordered-by-total-tokens.md)
- [Per-day usage breakdown for the caller over the last `days` days.](https://docs.nasiko.com/api-reference/usage/per-day-usage-breakdown-for-the-caller-over-the-last-`days`-days.md)
- [Aggregate token usage and cost for the caller over the last `days` days.](https://docs.nasiko.com/api-reference/usage/aggregate-token-usage-and-cost-for-the-caller-over-the-last-`days`-days.md)
- [List users (superuser-only; EE additionally exposes a role/org-scoped](https://docs.nasiko.com/api-reference/users/list-users-superuser-only;-ee-additionally-exposes-a-roleorg-scoped.md): List users (superuser-only; EE additionally exposes a role/org-scoped listing at `/api/org/users` — see the EE org-users routes).
- [Create a user. No password is taken — a one-time `access_key`/](https://docs.nasiko.com/api-reference/users/create-a-user-no-password-is-taken-—-a-one-time-`access_key`.md): Create a user. No password is taken — a one-time `access_key`/ `access_secret` pair is minted and returned once; the secret doubles as the user's login password (see `nasiko-user-creation-contract`).
- [List every admin (`role = 'admin'`) user.](https://docs.nasiko.com/api-reference/users/list-every-admin-`role-=-admin`-user.md)
- [The caller's own user record (superuser-only route; EE overrides this](https://docs.nasiko.com/api-reference/users/the-callers-own-user-record-superuser-only-route;-ee-overrides-this.md): The caller's own user record (superuser-only route; EE overrides this with the same EE-aware shape as `get_user` — see the EE users module).
- [Agents accessible to the caller — see `accessible_agents_for_user`.](https://docs.nasiko.com/api-reference/users/agents-accessible-to-the-caller-—-see-`accessible_agents_for_user`.md)
- [Get a user by id (superuser-only).](https://docs.nasiko.com/api-reference/users/get-a-user-by-id-superuser-only.md)
- [Update a user's own-editable fields (superuser-only; EE overrides this](https://docs.nasiko.com/api-reference/users/update-a-users-own-editable-fields-superuser-only;-ee-overrides-this.md): Update a user's own-editable fields (superuser-only; EE overrides this route to additionally accept `department_id`/`team_id` — see the EE `ee_update_user` override). An `is_active: false` transition here runs the same self-deactivate/last-admin guards as the dedicated `/deactivate` route.
- [Delete a user. Rejects self-deletion, deleting the last admin, or a user](https://docs.nasiko.com/api-reference/users/delete-a-user-rejects-self-deletion-deleting-the-last-admin-or-a-user.md): Delete a user. Rejects self-deletion, deleting the last admin, or a user who still owns agents (reassign or delete those first).
- [Agents accessible to a user (owner ∪ public ∪ direct user-grant; EE's](https://docs.nasiko.com/api-reference/users/agents-accessible-to-a-user-owner-∪-public-∪-direct-user-grant;-ees.md): Agents accessible to a user (owner ∪ public ∪ direct user-grant; EE's EE override additionally checks team/department grants).
- [Deactivate a user and revoke their live tokens. Rejects self-deactivation](https://docs.nasiko.com/api-reference/users/deactivate-a-user-and-revoke-their-live-tokens-rejects-self-deactivation.md): Deactivate a user and revoke their live tokens. Rejects self-deactivation and deactivating the last admin.
- [Mint a fresh `access_key`/`access_secret` pair for a user, replacing any](https://docs.nasiko.com/api-reference/users/mint-a-fresh-`access_key``access_secret`-pair-for-a-user-replacing-any.md): Mint a fresh `access_key`/`access_secret` pair for a user, replacing any existing credential, and revoke their live tokens.
- [Reactivate a previously deactivated user.](https://docs.nasiko.com/api-reference/users/reactivate-a-previously-deactivated-user.md)
- [Change a user's role and immediately revoke their live tokens. EE wraps](https://docs.nasiko.com/api-reference/users/change-a-users-role-and-immediately-revoke-their-live-tokens-ee-wraps.md): Change a user's role and immediately revoke their live tokens. EE wraps this with a leadership-displacement cascade — see the EE `ee_change_role` override.
- [Config files](https://docs.nasiko.com/reference/config-files.md): Where the CLI, server, and coding harnesses keep state.
- [Changelog](https://docs.nasiko.com/changelog.md): What changed in Nasiko, most recent first.

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.