Architecture

OpsNexus is a web app (React) in front of a Python API (FastAPI), with Celery workers for background jobs, PostgreSQL for data, Redis for queues and live updates, and HashiCorp Vault for secret values. Build agents run on your own machines and talk to the API over HTTPS. Everything except the agents runs as containers from one docker-compose.yml.

#Diagram

                        Browser
                           │  HTTPS (via your reverse proxy)
                           ▼
                 ┌───────────────────┐
                 │ web (Nginx :8080) │  serves the React app
                 └─────────┬─────────┘
                           │ /api, /api/ws (WebSocket)
                           ▼
 Build agents ──HTTPS──► ┌──────────────────┐ ──► vault (secret values)
 (Linux, Windows,        │ api (FastAPI     │ ──► guacd ──RDP──► Windows servers
  macOS, Docker)         │      :8000)      │ ──SSH──────────► Linux servers
                         └──┬───────────┬───┘
                            │           │
                            ▼           ▼
                     ┌──────────┐  ┌──────────────────────────┐
                     │ db       │  │ redis                    │
                     │ Postgres │  │ job queue, pub/sub,      │
                     └──────────┘  │ rate limits              │
                            ▲      └──────┬────────────▲──────┘
                            │             │ jobs       │ schedule
                            │             ▼            │
                            │      ┌────────────┐  ┌───┴────────┐
                            └──────┤ worker     │  │ scheduler  │
                                   │ (Celery)   │  │ (Celery    │
                                   └─────┬──────┘  │  beat)     │
                                         │         └────────────┘
                                         ▼
           Jenkins, GitLab, Azure DevOps, Argo CD, GitHub Actions,
           AWS, Azure, Google Cloud, Oracle Cloud, Kubernetes APIs,
           container registries, scanners, notification channels

#Services

The api, worker and scheduler containers share one image. The entrypoint picks the role: api, worker or scheduler.

#How a request flows

1. The browser loads the app from web and calls /api/... with an access token (Authorization: Bearer ...), or a script calls it with an API key (X-API-Key).
2. web forwards the request to api.
3. The API checks the token, checks that the session has not been revoked, and loads the user's effective permissions: the highest level per module across the user's role and team roles, then their project role for project modules.
4. If the level is too low for the action, the API returns 403.
5. The route calls a service, which reads and writes PostgreSQL (and Vault when secrets change) and records an audit event.
6. Every query is limited to the caller's organization and active project.

#How live updates flow

1. A service or background job publishes an event (for example, an agent status change or a finished sync) on the organization's Redis channel.
2. The browser keeps a WebSocket open to /api/ws.
3. The API forwards events from Redis to the browser, which refreshes the affected data.

#How background jobs flow

1. The scheduler puts due jobs on the Redis queue at fixed intervals.
2. The API also queues jobs directly, for example a sync you start by hand or a notification to deliver.
3. A worker takes each job, does the work (usually calling an external API) and writes the result to PostgreSQL.

If Redis cannot be reached when the API queues a sync or a pipeline scan, the API can run it directly instead.

#Scheduled jobs

#How build agents work

Agents only make outbound HTTPS requests to OpsNexus. OpsNexus never connects to them.

1. Register. The agent exchanges a single-use registration token for an agent ID and secret, which it saves in a config file readable only by its service account.
2. Heartbeat. About every 15 seconds it sends host health and receives settings and commands (such as restart or upgrade).
3. Run pipelines. When it has executors, it claims pipeline runs from the API, runs the steps in its workspace, streams logs and events back, uploads artifacts, and reports the result.
4. Infra designer deployments run as pipelines on agents. The agent downloads the generated Terraform, runs plan and apply in the hashicorp/terraform image, and uses OpsNexus as the Terraform HTTP state backend.

#How remote access works

• SSH terminal. The browser opens a WebSocket to /api/ws/terminal/... with a single-use, 60-second ticket. The API opens the SSH connection itself, with credentials from the secret store, so passwords and keys never reach the browser.
• Remote Desktop. The API connects to guacd, does the Guacamole handshake and fills in the password. guacd opens the RDP connection, so it must be able to reach your servers.

#Where data is stored

Some values in PostgreSQL are encrypted with a key derived from SECRET_KEY (or LOCAL_SECRET_KEY): MFA seeds, Terraform state, pipeline webhook tokens and secret masks for build logs. The audit log is append-only and each entry is hash-chained to the previous one.

With SECRET_BACKEND=local (development only), secret values are stored encrypted in PostgreSQL instead of Vault.

#Scaling

• api is stateless. Raise API_WORKERS, or run more replicas behind a load balancer.
• worker scales horizontally. Raise WORKER_CONCURRENCY or run more containers.
• scheduler must run as exactly one container.
• Builds run on agents, not on the server. Add agents or executors to run more builds at once.

See Running in production and Environment variables.