# NebulaCtrl

> NebulaCtrl is a self-hosted, Docker-native platform-as-a-service. You connect your own Linux servers, deploy from Git or a container image, and manage variables, domains, databases, backups, logs and rollbacks from a canvas, a CLI or a REST API. A Go control plane with a Postgres database talks to a small agent on each Docker host; Traefik on each host routes traffic.

The documentation is markdown: append .md to any /docs/<page> URL to read the page as plain markdown. Pages are written for people running their own infrastructure; the CLI and API references are generated from the code.

## Getting started

- [What is NebulaCtrl?](https://nebulactrl.com/docs/getting-started/what-is-nebulactrl.md): A self-hosted platform for deploying apps on your own Docker servers, with a canvas, a CLI and an API.
- [Concepts](https://nebulactrl.com/docs/getting-started/concepts.md): Projects, environments, services, servers and staged changes: the few ideas the rest of NebulaCtrl is built on.
- [Quickstart](https://nebulactrl.com/docs/getting-started/quickstart.md): From a bare machine to a running app with a domain and a database.

## CLI, API and MCP

- [CLI reference](https://nebulactrl.com/docs/reference/cli.md): Every nebulactrl command, argument and flag, generated from the command tree.
- [API reference](https://nebulactrl.com/docs/reference/api.md): Every REST endpoint, generated from the OpenAPI spec, with authentication, errors and conventions.
- [Advanced settings](https://nebulactrl.com/docs/operations/configuration.md): Control-plane timer overrides (NEBULACTRL_MESH_LINK_GRACE, NEBULACTRL_REPLICA_BROKEN_AFTER): what they change, their defaults, and why you normally leave them alone.
- [MCP server](https://nebulactrl.com/docs/reference/mcp.md): Let an AI client run NebulaCtrl the way you would by hand: look, stage a change, apply it, with production changes approved by a person.
- [OpenAPI document](https://nebulactrl.com/api/v1/openapi.json): The complete REST API as OpenAPI 3.1 JSON, served by the control plane without authentication.

## Installing

- [Install NebulaCtrl](https://nebulactrl.com/docs/installing.md): One command installs the control plane on a fresh machine and makes it your first server.
- [Requirements](https://nebulactrl.com/docs/installing/requirements.md): Supported operating systems, architectures, ports and Docker versions.
- [The installer](https://nebulactrl.com/docs/installing/installer.md): What install.sh does, its options, and how to re-run, upgrade or recover with it.
- [Migrate from Coolify](https://nebulactrl.com/docs/installing/migrate-from-coolify.md): Move a host from Coolify to NebulaCtrl in place: install side by side, copy the data, cut over in minutes, roll back in about one.
- [The control plane](https://nebulactrl.com/docs/installing/control-plane.md): How the control-plane containers are laid out, hardened and run by hand.
- [Upgrade and roll back](https://nebulactrl.com/docs/installing/upgrade.md): Update the control plane to a new version, or go back to the previous one.
- [Uninstall](https://nebulactrl.com/docs/installing/uninstall.md): Remove NebulaCtrl from a machine, with or without your data.

## Applications

- [Deployments](https://nebulactrl.com/docs/operations/deployments.md): Rolling and recreate strategies, health checks, rollback, image retention and recovery.
- [Builds](https://nebulactrl.com/docs/operations/builds.md): Dockerfile, Railpack and starter Dockerfiles: how a repository becomes an image.
- [Git providers and deploy on push](https://nebulactrl.com/docs/operations/git-providers.md): Connect GitHub, GitLab and others, and deploy when you push.
- [Deploy hooks](https://nebulactrl.com/docs/operations/deploy-hooks.md): A URL per service that deploys it from CI or a container registry.
- [SSH deploy keys](https://nebulactrl.com/docs/operations/ssh-deploy-keys.md): Clone private repositories over SSH with generated or uploaded keys.
- [Variables and secrets](https://nebulactrl.com/docs/operations/variables.md): Encrypted variables, references between services and write-only secrets.
- [Networking](https://nebulactrl.com/docs/operations/networking.md): Environment networks, shared networks and blocking outbound internet.
- [Domains and proxy routes](https://nebulactrl.com/docs/operations/proxy-routes.md): Publish services and other upstreams on a domain; TCP and UDP routes; per-domain options.
- [Import a Compose project](https://nebulactrl.com/docs/operations/compose-import.md): Turn a docker-compose.yml into staged NebulaCtrl services after a review.
- [Import from Coolify](https://nebulactrl.com/docs/operations/import-coolify.md): Stage the projects, applications, databases, domains and variables of a Coolify v4 instance as NebulaCtrl services.
- [Compose stacks](https://nebulactrl.com/docs/operations/compose-stacks.md): Run a docker-compose.yml as one service with the safe allow-list.
- [Pull-request previews](https://nebulactrl.com/docs/operations/previews.md): A throwaway environment for every open pull request.
- [Clone and move](https://nebulactrl.com/docs/operations/clone-and-move.md): Copy a service or a whole environment, and move a service to another environment.
- [Replicas and autoscaling](https://nebulactrl.com/docs/operations/scaling.md): Run a stateless service on several replicas and scale on CPU.
- [Tasks and cron jobs](https://nebulactrl.com/docs/operations/tasks.md): Scheduled jobs, one-off commands, and commands before and after a deploy.
- [Web terminal and file browser](https://nebulactrl.com/docs/operations/terminal.md): Open a shell or browse files inside a running container.
- [Docker options](https://nebulactrl.com/docs/operations/docker-options.md): Typed container options for a service: hardening, hostname, DNS, sysctls, user, and devices, GPUs and host access on unrestricted servers.
- [Maintenance mode and error pages](https://nebulactrl.com/docs/operations/maintenance-and-error-pages.md): Put a service into maintenance and customise what visitors see on errors.

## Databases and backups

- [Managed databases](https://nebulactrl.com/docs/operations/databases.md): Engines, connection variables, credential rotation and version upgrades.
- [Postgres standby replicas and manual Promote](https://nebulactrl.com/docs/operations/database-replicas.md): Advanced, Postgres only: a standby replica on another server, read offload, manual promote and rebuild. Not a backup and not automatic failover.
- [Database backups](https://nebulactrl.com/docs/operations/database-backups.md): Scheduled and on-demand dumps to S3 or a server directory, and how to restore them.
- [Volume backups](https://nebulactrl.com/docs/operations/backups.md): File-level backups of a service's volumes, with hooks, retention and restore.
- [Control-plane backup and restore](https://nebulactrl.com/docs/operations/backup-restore.md): Back up NebulaCtrl itself: the database and the secret key, and how to restore.

## Templates

- [One-click templates](https://nebulactrl.com/docs/operations/templates.md): Deploy a self-hosted app from the template catalogue.

## Servers

- [Add a server](https://nebulactrl.com/docs/installing/servers.md): Enroll a Linux host with Docker so NebulaCtrl can deploy to it.
- [Servers and agents](https://nebulactrl.com/docs/operations/servers.md): Offline servers, revoking and re-enrolling, and how the reconciler behaves.
- [Build servers and registries](https://nebulactrl.com/docs/operations/build-servers.md): Build on a dedicated server, push to an OCI registry, deploy by digest: roles, placement, registries, rollback and troubleshooting.
- [Draining servers and the fleet](https://nebulactrl.com/docs/operations/draining-servers.md): Take a server out for maintenance or retirement; capacity and overcommit.
- [Certificates, upstream policy and tailnet egress](https://nebulactrl.com/docs/operations/proxy-tailnet-certificates.md): Upload a certificate, the upstream (SSRF) policy and routing to tailnet devices.
- [Proxy ports](https://nebulactrl.com/docs/operations/proxy-ports.md): Move the proxy's HTTP and HTTPS ports from the server, with a plan and a confirm, and what that means for Let's Encrypt.
- [DNS-01 and wildcard certificates](https://nebulactrl.com/docs/operations/dns01-wildcard-certificates.md): Issue wildcard certificates through your DNS provider.
- [Cloudflare DNS](https://nebulactrl.com/docs/operations/cloudflare.md): Connect Cloudflare, keep DNS records in sync, see live DNS status and lock proxied origins to Cloudflare.
- [Per-service tailnet](https://nebulactrl.com/docs/operations/service-tailnet.md): Make one service reachable on your Tailscale or Headscale tailnet.
- [Server mesh and cross-server links](https://nebulactrl.com/docs/operations/mesh.md): Join your servers to your tailnet, link services across servers, and keep the access rules NebulaCtrl generates for it.
- [Host hardening](https://nebulactrl.com/docs/security/host-hardening.md): A Lynis audit of each server and a curated set of safe fixes.
- [Docker cleanup](https://nebulactrl.com/docs/operations/docker-cleanup.md): Daily and disk-alert cleanup of images, build cache and networks.
- [Server patching](https://nebulactrl.com/docs/operations/server-patching.md): Pending OS updates, reboot-required, and the instance admin's Apply updates and Reboot.
- [Upgrades: agents and the control plane](https://nebulactrl.com/docs/operations/upgrades.md): Agents upgrade themselves to the control plane's version; the control plane backs itself up before it upgrades.
- [Host shell](https://nebulactrl.com/docs/security/host-shell.md): An opt-in root shell on a server, for owners and admins with two-factor.

## Observability

- [Monitoring and retention](https://nebulactrl.com/docs/operations/monitoring.md): Health endpoints, JSON logs, metrics and disk alerts.
- [Logs and log drains](https://nebulactrl.com/docs/operations/logs.md): Runtime log history on each server and drains to Loki, OTLP, syslog and HTTP.
- [Traffic analytics](https://nebulactrl.com/docs/operations/traffic-analytics.md): What the proxy access log becomes: requests, status classes and origins.
- [Notifications](https://nebulactrl.com/docs/operations/notifications.md): Email, Slack, Discord, Telegram and signed webhooks for deploy and server events.
- [Service alerts](https://nebulactrl.com/docs/operations/service-alerts.md): Crash, unhealthy, restart-loop and missed-backup alerts: how incidents are detected, announced once and closed, and the thresholds.

## Teams and security

- [Security overview](https://nebulactrl.com/docs/security.md): The two things to remember, and where each security topic lives.
- [Teams, roles and invites](https://nebulactrl.com/docs/operations/teams.md): Who can do what: roles, project scoping and invitations.
- [Login methods](https://nebulactrl.com/docs/security/login-methods.md): Passwords, passkeys, two-step verification and single sign-on.
- [Single sign-on setup](https://nebulactrl.com/docs/security/sso-setup.md): Connect your OpenID Connect provider, with a recipe for common ones.
- [Secret managers and team variables](https://nebulactrl.com/docs/operations/secret-managers.md): Reference Vault, OpenBao, Infisical or Doppler secrets without storing them, limit who may use them, and see what was read.
- [Threat model](https://nebulactrl.com/docs/security/threat-model.md): Trust boundaries, what NebulaCtrl protects and what it does not.
- [Secrets at rest](https://nebulactrl.com/docs/security/secrets-at-rest.md): How NebulaCtrl seals stored secrets: key ring, ciphertext format, key rotation with rekey, release retention and what is and is not protected.

## Platform services

- [Platform services](https://nebulactrl.com/docs/operations/platform-services.md): One-click S3 storage, log store, tailnet, single sign-on and container registry that NebulaCtrl runs for itself.

## Troubleshooting

- [Troubleshooting](https://nebulactrl.com/docs/operations/troubleshooting.md): Proxy and port 80, certificates, DNS, agents that will not connect, stuck deployments.
- [Known limitations](https://nebulactrl.com/docs/operations/limitations.md): What this release does not do.

## Optional

- [Everything in one file](https://nebulactrl.com/llms-full.txt): Every page above concatenated, for loading the whole documentation at once.
- [Operations index](https://nebulactrl.com/docs/operations.md): Every operations page, with when to read it.
- [0001 Go modular monolith](https://nebulactrl.com/docs/decisions/0001-go-modular-monolith.md): Why the control plane is a single Go binary split by domain.
- [0002 Agent transport](https://nebulactrl.com/docs/decisions/0002-agent-transport.md): Why agents dial out over WebSocket with an Ed25519 identity.
- [0003 Traefik proxy](https://nebulactrl.com/docs/decisions/0003-traefik-proxy.md): Why every host runs Traefik v3, managed by the agent.
- [0004 Build on the target host](https://nebulactrl.com/docs/decisions/0004-build-on-target-host.md): Why images are built where they run by default, without a registry.
- [0005 Licence](https://nebulactrl.com/docs/decisions/0005-license.md): NebulaCtrl is licensed under AGPL-3.0-only.
- [0006 Railpack builder](https://nebulactrl.com/docs/decisions/0006-railpack-default-builder.md): Why Railpack is the zero-config builder and a Dockerfile always wins.
- [0007 Compose stacks](https://nebulactrl.com/docs/decisions/0007-compose-stacks.md): Why Compose files run natively with docker compose.
- [0008 Build servers and registries](https://nebulactrl.com/docs/decisions/0008-build-servers.md): Why builds can optionally run on a dedicated build server and ship through an OCI registry.
- [Third-party licences](https://nebulactrl.com/docs/security/third-party-licences.md): Dependency licence scan for the AGPL-3.0-only release, with the rules and the images NebulaCtrl deploys.
- [Navigation transitions](https://nebulactrl.com/docs/architecture/navigation-transitions.md): How route changes animate in the web app: view transitions, shared elements, reduced motion.
- [Analytics API](https://nebulactrl.com/docs/reference/api/analytics.md): 3 operations.
- [Approvals API](https://nebulactrl.com/docs/reference/api/approvals.md): 3 operations. Production approvals for AI clients
- [Audit API](https://nebulactrl.com/docs/reference/api/audit.md): 1 operation. Audit log
- [Auth API](https://nebulactrl.com/docs/reference/api/auth.md): 21 operations. Sessions
- [Backups API](https://nebulactrl.com/docs/reference/api/backups.md): 21 operations.
- [Builds API](https://nebulactrl.com/docs/reference/api/builds.md): 2 operations.
- [Canvas API](https://nebulactrl.com/docs/reference/api/canvas.md): 2 operations. Canvas layouts
- [Certificates API](https://nebulactrl.com/docs/reference/api/certificates.md): 3 operations.
- [Compose API](https://nebulactrl.com/docs/reference/api/compose.md): 2 operations.
- [Databases API](https://nebulactrl.com/docs/reference/api/databases.md): 17 operations.
- [Deployments API](https://nebulactrl.com/docs/reference/api/deployments.md): 13 operations. Deployments and releases
- [Dns01 API](https://nebulactrl.com/docs/reference/api/dns01.md): 12 operations.
- [Domains API](https://nebulactrl.com/docs/reference/api/domains.md): 10 operations. Service domains
- [Environments API](https://nebulactrl.com/docs/reference/api/environments.md): 5 operations. Environments
- [Events API](https://nebulactrl.com/docs/reference/api/events.md): 1 operation. Live invalidation feed
- [Fleet API](https://nebulactrl.com/docs/reference/api/fleet.md): 6 operations.
- [Git API](https://nebulactrl.com/docs/reference/api/git.md): 18 operations.
- [Imports API](https://nebulactrl.com/docs/reference/api/imports.md): 2 operations.
- [Instance API](https://nebulactrl.com/docs/reference/api/instance.md): 8 operations.
- [Integrations API](https://nebulactrl.com/docs/reference/api/integrations.md): 12 operations.
- [Links API](https://nebulactrl.com/docs/reference/api/links.md): 4 operations. Service links
- [Logs API](https://nebulactrl.com/docs/reference/api/logs.md): 16 operations. Logs
- [Me API](https://nebulactrl.com/docs/reference/api/me.md): 14 operations. Current principal
- [Mesh API](https://nebulactrl.com/docs/reference/api/mesh.md): 9 operations.
- [Metrics API](https://nebulactrl.com/docs/reference/api/metrics.md): 2 operations. Metrics
- [Networks API](https://nebulactrl.com/docs/reference/api/networks.md): 6 operations.
- [Notifications API](https://nebulactrl.com/docs/reference/api/notifications.md): 11 operations.
- [Platform API](https://nebulactrl.com/docs/reference/api/platform.md): 13 operations.
- [Previews API](https://nebulactrl.com/docs/reference/api/previews.md): 4 operations.
- [Projects API](https://nebulactrl.com/docs/reference/api/projects.md): 5 operations. Projects
- [Proxy API](https://nebulactrl.com/docs/reference/api/proxy.md): 6 operations.
- [Registries API](https://nebulactrl.com/docs/reference/api/registries.md): 7 operations.
- [Routes API](https://nebulactrl.com/docs/reference/api/routes.md): 5 operations.
- [Secret managers API](https://nebulactrl.com/docs/reference/api/secret-managers.md): 5 operations.
- [Servers API](https://nebulactrl.com/docs/reference/api/servers.md): 37 operations. Servers and agents
- [Services API](https://nebulactrl.com/docs/reference/api/services.md): 23 operations. Services
- [Setup API](https://nebulactrl.com/docs/reference/api/setup.md): 2 operations. First-run bootstrap
- [Shared variables API](https://nebulactrl.com/docs/reference/api/shared-variables.md): 18 operations.
- [Stacks API](https://nebulactrl.com/docs/reference/api/stacks.md): 1 operation.
- [System API](https://nebulactrl.com/docs/reference/api/system.md): 1 operation. Control-plane info
- [Tasks API](https://nebulactrl.com/docs/reference/api/tasks.md): 9 operations.
- [Teams API](https://nebulactrl.com/docs/reference/api/teams.md): 19 operations. Teams, members, invites and instance settings
- [Templates API](https://nebulactrl.com/docs/reference/api/templates.md): 8 operations.
- [Terminal API](https://nebulactrl.com/docs/reference/api/terminal.md): 6 operations.
- [Tokens API](https://nebulactrl.com/docs/reference/api/tokens.md): 3 operations. API tokens
- [Variables API](https://nebulactrl.com/docs/reference/api/variables.md): 11 operations. Service variables
- [Volume backups API](https://nebulactrl.com/docs/reference/api/volume-backups.md): 14 operations.
- [Volumes API](https://nebulactrl.com/docs/reference/api/volumes.md): 3 operations. Service volumes