DocsBook a demo

Platform

Platform overviewArchitectureWorkflow orchestrationGitOps configurationGovernance and AAAAI and MCPKnowledge and contextRuntime and executionEvidence and monitoring

Use cases

All use casesProduction incidentRelease preparationHotfix to productionSecurity scan triage
Why NopsAIIntegrationsSecurity

Resources

All resourcesAI agent governanceMCP governanceMCP securitySelf-hosted platforms
PricingGitHub

Company

How a run worksAboutContactBook a demo

Control plane and execution plane

The API, AAA, dispatcher, git-bot, UI, PostgreSQL, Gotenberg, and socket proxy form the control plane; runners and per-run agents form the execution plane.

ConceptAdministratorOperatorDeveloper

Key points

  • nopsai-api owns REST APIs, validation, orchestration, setup, monitoring, credentials, notifications, GitOps, auth integration, and run records.
  • aaa owns authorization decisions, policy checks, ACL expansion, filtering, and decision audit records.
  • dispatcher owns runner registration, queueing, routing, capacity selection, and job assignment over gRPC.
  • git-bot owns GitHub App webhooks, repository access, check runs, and GitHub-specific integration.
  • Runners start one agent per assigned run; the agent then starts step containers or pods and reports status back.
  • Gotenberg renders PDF final outputs. The Docker socket proxy exposes only the allow-listed reads System Logs needs.

How it works

The API submits jobs to the dispatcher. Runners hold long-lived outbound connections to the dispatcher, which keeps registration and capacity visible to the control plane without inbound access to the runner.

Docker runners create containers and named Docker volumes. Kubernetes runners create an agent pod, a PVC-backed workspace, and step pods in their namespace.

UI and CLI are entry points only. They call authenticated REST routes and never talk directly to AAA, the dispatcher, PostgreSQL, or runners.

During cold starts, setup preflight keeps /healthz unready while retrying a database that is still starting. /livez stays process-alive, and normal API startup resumes automatically once PostgreSQL is reachable.

Examples

Component topologytext
ENTRY POINTS
  browser · CLI · API clients            git providers
            │                                 │
            │ authenticated REST              │ signed webhooks
            │                                 ▼
            │                              git-bot
            └───────────────┬─────────────────┘
                            ▼
───────────────────────────────────────────────────────────
DURABLE CONTROL PLANE
                       nopsai API ◀────▶ aaa
                            │
           ┌────────────────┼──────────────────┐
           ▼                ▼                  ▼
      PostgreSQL       gotenberg      docker-socket-proxy
     durable state     PDF outputs    allow-listed reads
───────────────────────────────────────────────────────────
                            │ SubmitJob gRPC
                            ▼
EPHEMERAL EXECUTION PLANE
                       dispatcher
                          ▲   │
        runner dials out ─┘   │ assigns runs over that stream
                              ▼
                           runner
                              │ starts one agent per run
                              ▼
                           agent ────▶ step containers or pods
                              │
                              ├───────▶ LLM providers
                              └───────▶ MCP servers
───────────────────────────────────────────────────────────
Result

The dashed direction matters: the runner opens the stream to the dispatcher, so a runner never needs inbound network access.

Limits

Current behavior
  • Kubernetes emptyDir is not used for shared run workspaces; the agent owns a PVC instead.
  • Docker runners ignore Kubernetes runtime pools and affinity settings.

Implementation evidence

  • doc/service-reference.md

    What each service owns and which files to read.

  • services/nopsai/routes.go

    The REST surface the control plane exposes.