Contents
§ 01
What the installer sets up
The installer sets up Docker, then runs the panel and its services as containers, from release-tagged images and Compose files. Everything in this table runs on your server.
| Component | What it does here |
|---|---|
| Docker Engine, Compose and Buildx | Runs every part. Rootful Docker is required. |
| Traefik | Terminates TLS and routes each app by its web address. It checks the panel sign-in in front of private apps. |
| Keycloak 26 | Sign-in with OpenID Connect and PKCE. It also handles two-factor sign-in and single sign-on. |
| PostgreSQL | Holds the panel's data and its background job queue. |
| Valkey | The in-memory store. Request rate limits use it. |
| OpenBao (2.5.5 by default) | The secrets vault. It sits on an internal network, with no exposed port. |
| The panel | One Go service built on Echo v5. It serves the API and the React web app, built with Ant Design Pro. |
| LiteLLM | The OpenAI-compatible AI gateway behind metered customer keys. |
| Ollama | Runs local models. The installer tries to pull a starter model sized to the server's memory. |
v2.17.0
Who uses it
- Your teamRuns the panel in the browser
- ResellersThe same panel, filtered by their role
- Your customersTheir own portal, with only their own apps
- Your AI toolsConnect through MCP. Admin access stays off until you add an admin key.
- VisitorsOpen the apps you make public
Front door
- TraefikHTTPS certificates from Let's Encrypt
- At least one web address per app
- New apps start private, behind the panel sign-in
The panel One service, written in Go, with a React web app
- Your first day: 2Web appViews for your team, resellers and customers. Setup wizard in seven languages.
- REST API and MCP262 documented API operations. MCP: 28 tools for your team and 10 for customers. API keys and an audit log.
- Built-in AIAn assistant that asks before it changes anything. AI Deploy proposes how to run a repository. Insights show what needs attention.
Needs an AI provider set up in the panel.
- AutofixHandles a set of supported problems. You switch each action on or off and see what it did.
- Your first day: 5Background jobsBuild apps and back up supported databases and volumes. They also watch health, meter AI use per customer key, apply the updates you start and rotate supported secrets.
Services installed with the panel
- KeycloakSign-in, two-factor authentication and single sign-on
- PostgreSQLPanel data and the job queue
- ValkeyIn-memory store
- OpenBaoSecrets, encrypted in separate compartments for the platform and each customer
- LiteLLMAI gateway for apps on your metered AI: a key per customer, monthly budgets, rate limits
- OllamaLocal models. Prompts are processed on your server.
The panel and the server remain trusted parts of the system.
deploys · watches · backs up supported data
Your customers' apps Each app in its own Docker container; each customer's apps share their own network
- Your first day: 3AI agentsOpenClaw, Hermes and OpenHands. Each one uses the AI route chosen when you deploy it.
- Your first day: 4Coding workspacesClaude Code, Codex, OpenCode and Pi in the browser, with the developer's own subscription or key
- Apps from GitRailpack detects common stacks, or the panel uses your Dockerfile or Compose file
- Catalog50 apps: 23 AI apps, 6 databases, 10 developer tools, 11 web apps. Each deploy checks the app's minimum size against your server.
Your first day: 1
Your server
- Certified Ubuntu, Debian, Rocky Linux, AlmaLinux, RHEL or CentOS Stream
- Docker
- from 2 CPU cores, 4 GB memory and 20 GB SSD
Outside your server, your choice
- AI providersFor apps that support it, choose the customer's own key, your metered AI gateway or a local model only. With an outside provider, the app's AI requests go to that provider.only on the routes you choose
- Git hostingPublic repositories by URL. Pushes from GitLab or GitHub can trigger a rebuild when you switch it on. Connecting a GitHub account previewbuilds
- Backup storageOne S3-compatible bucket of your choice, in the Power User and Web Host editions.supported databases and volumes
- UpdatesSigned release images. If the update fails its health check, the panel tries to roll it back.updates you start
- LicencesChecking and activating a paid licence contacts our licensing service.licence check
- Chat channelsSome agents connect to chat apps. OpenClaw can link one WhatsApp number by a QR code on its page in the panel. Hermes connects its own channels.
- Runs on your server
- Outside your server, your choice
- Your first day
- previewReleased as a preview
On the host itself, systemd units apply updates and run the nightly backup of the panel's own data. A systemd timer also keeps the egress guard in place.
Note
The panel and Traefik containers mount the Docker socket, so they can deploy and route apps. The panel and the server remain trusted parts of the system.
§ 02
Install and requirements
It installs on a supported 64-bit Linux server with systemd and rootful Docker.
Public install opens soon. Leave your email address, and we'll tell you when it does. Get started
| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 2 cores | 4 cores or more |
| Memory | 4 GB | 8 GB or more |
| Storage | 20 GB SSD | 50 GB SSD or more |
| Architecture | x86_64 or arm64 | x86_64 |
| Support tier | Distributions |
|---|---|
| Certified, tested on every release | Ubuntu 22.04, 24.04 and 26.04 LTS. Debian 12 and 13. Rocky Linux, AlmaLinux, RHEL and CentOS Stream 9 and 10. |
| Best effort | Current Fedora, Oracle Linux 8 to 10 and Amazon Linux 2023. The installer warns and goes on. |
| Community | openSUSE Leap, SLES and Arch Linux. On SUSE, Docker may need installing first. |
| Unsupported | Systems without systemd, such as Alpine. End-of-life releases, 32-bit systems, OpenVZ and unprivileged LXC. |
| Checks first | Before it changes anything, the installer checks root, systemd, 64-bit, virtualisation, disk, free ports, DNS and clock sync. A failed hard check stops it and names the fix. |
|---|---|
| Dry run | --dry-run prints the full plan without touching the server. |
| Unattended | --unattended runs it for automation, with PANEL_DOMAIN and ACME_EMAIL set. |
| Docker networks | On a fresh Docker, the installer widens its address pools to about 3,500 networks, so each customer can have their own. Existing installs opt in, and that restarts every container. |
| Firewall | It opens ports 80 and 443 in firewalld or ufw once the panel is ready. |
| GPUs | On a host with an NVIDIA GPU and a working driver, the installer sets up the NVIDIA Container Toolkit. CPU-only hosts stay as they are. |
| Setup | The installer creates the administrator in Keycloak and prints a setup link with a one-time code. The setup wizard then asks for your edition, licence and AI settings, in any of seven languages. |
Note
On a first install, the installer and the files it downloads come over HTTPS without a signature check. We don't publish a signature for the installer yet.
§ 03
Network, domains and certificates
| Port | Direction | Use |
|---|---|---|
| 80 | Inbound | HTTP, redirected to HTTPS. Also used for the HTTP-01 certificate check. |
| 443 | Inbound | HTTPS. Traefik terminates TLS. |
| 22 | Inbound | SSH, for your own access to the server. |
Apps are reached through Traefik, by their web address. Compose files that publish host ports are refused. The API and MCP share the panel's domain and certificate, so they need no extra port.
| Your own domain | Point an A record and a wildcard A record at the server. Each app then gets a subdomain, such as myapp.panel.example.com. |
|---|---|
| Certificates | Let's Encrypt with the HTTP-01 check is the default. With a Cloudflare API token, the DNS-01 check works without inbound port 80. |
| No domain yet | Leave the domain empty, and the installer claims a temporary address, such as aap-x7k2f9.aiadminpanel.host, with working HTTPS. To keep it beyond the first seven days, confirm an email address in the panel. Temporary addresses work over IPv4 only. MANAGED_DOMAIN=off turns this path off. |
| Custom domains for apps | In the Power User and Web Host editions, the panel shows the DNS target and checks the record in the background. |
| The metered AI endpoint | Customers with a metered key reach the gateway at https://ai.<your-domain>/v1, once that name points at your server. |
§ 04
Isolation inside the server
On every request, the panel checks the person's role and what they own before anything opens or changes. On the server, these layers keep customers' apps apart.
| Networks | Each customer's apps share a Docker network of their own. Traefik and the AI gateway join each customer network with packet forwarding switched off, so they don't route between customers. A few shared services, such as local models, have their own rules. |
|---|---|
| Older apps | Apps from before v2.14 need a redeploy to move onto their customer's network. The panel lists the ones that haven't moved yet. |
| Container baseline | Catalog and Compose containers drop 16 Linux capabilities, NET_RAW among them, and run with no-new-privileges. Containers built from Git also drop MKNOD and AUDIT_WRITE. An image that needs sudo as a non-root user won't start under this baseline. |
| Exceptions | Image builds run with Docker's default settings. One template, BookStack, has a documented exception. Older containers get the baseline when they are recreated. |
| Egress guard | A host firewall rule blocks known cloud metadata addresses, such as 169.254.0.0/16, for every container and Git build step. Customer containers reach the server itself only on TCP ports 80 and 443 and DNS on port 53, plus ports you list. |
| Guard limits | The guard covers IPv4. Its host-port rule needs Docker 28 or later. Containers on the shared AI and proxy networks can still reach host ports. New installs since v2.15 have the guard, and older servers get it once the installer's updater is refreshed. |
| Reserved names | Customer containers can't use the names of platform services, such as keycloak, openbao or traefik. |
| Templates and Compose files | Variables are checked against an allow list, and the final container definitions are checked again after substitution. Images with traefik.* or aiadminpanel.* labels are refused. |
Note
A running container holds its settings with the values filled in. Anyone with root or Docker access on the server can read them.
§ 05
Secrets
| The vault | OpenBao keeps app passwords, AI keys and customer tokens encrypted, in separate compartments for the platform and for each customer. The panel is its only client. |
|---|---|
| Outside the vault | Other secrets, such as environment variables and Git deploy keys, are encrypted in the panel's database. |
| References | An app's settings can point at a stored secret of the same owner with a {{secret …}} reference. The value is filled in when the container is created. |
| Rotation | Supported secrets rotate from the panel. The panel then recreates the app with the new value, and other apps that use it may need a redeploy. |
| Reveals and write-only fields | Revealing a stored app password writes an audit log entry. Passwords for connected services, such as your mail server, are write-only. |
Caution
The vault unseals itself with a key kept on the same server. Someone with root on the server can therefore reach the secrets. Protect the host as you would any server with customer data.
§ 06
Sign-in, roles and the audit log
| Sign-in | Keycloak 26, with OpenID Connect and PKCE. Browser sessions from Keycloak and API keys are the only ways into the panel. |
|---|---|
| The session cookie | __Host-aap_session is valid for the panel's hostname only. It is never sent to deployed apps. |
| Two-factor | Each user turns on an authenticator app through Keycloak. Recovery codes are in preview. Your team can reset a customer's two-factor with a reason, after a recent sign-in of their own. |
| Private apps | Traefik asks the panel before anyone opens a private app. Each private app gets its own sign-in cookie, valid for its hostname only. |
| Roles | Fine-grained roles pass down the organisation tree and can be limited to one project. Nobody can give a role more rights than they hold. Roles, organisations and resellers come with the Web Host edition. |
| API keys | Each key has its own role, a rate limit and a last-used time, with an optional expiry date and deny list. Revoke one at any time. |
| The audit log | Filter supported events by actor, action, resource and date. Export the view as CSV, up to 10,000 rows. |
§ 07
API and MCP
| Interface | Where | Access |
|---|---|---|
| REST API | /api/v1 on your panel | An API key as a Bearer token. Customer routes sit under /api/v1/portal. |
| OpenAPI file | /api/openapi.yaml and /api/swagger.yaml | Download it to generate a client. |
| API explorer | /api/docs | Interactive. Its requests can change real resources. |
| MCP for your team | /mcp, and /sse for older clients | Off until you switch it on. Each request needs an admin API key. |
| MCP for customers | /mcp/tenant | Off until you allow a customer. Each customer creates their own tokens. |
| Partner Center API | Our Partner Center | Its own tokens, with read or write scope, for licence work. |
- In v2.17.0, the panel's OpenAPI 3.0 file documents 262 operations across 212 paths.
- In v2.17.0, the Partner Center API documents 32 operations across 23 paths.
- v2.17.0 has 28 MCP tools for your team and 10 for customers. Some tools appear in both sets, so the two numbers don't add up to one total.
| Customer MCP tools | List services, check a status, read recent logs, start, stop, restart, redeploy, deploy a catalog app and read usage. A health tool comes with them. Each tool acts on that customer's own apps. |
|---|---|
| Separate keys | An admin key is refused on the customer endpoint. A customer token is refused on the admin endpoint. |
| Transport | Both MCP endpoints use Streamable HTTP with a Bearer header. The admin endpoint accepts protocol versions 2025-03-26, 2025-06-18 and 2025-11-25. |
Note
The OpenAPI file is generated from code annotations, so check the final URL before you send a generated request. API and MCP calls go straight to the permission check. Some actions are only available in the web app.
§ 08
The deploy pipeline
Four ways in: the catalog, a Git repository, AI Deploy and a Docker Compose file. All four share one size picker that checks the server's capacity.
| Build detection | From Git, the panel uses the repository's Compose file, then its Dockerfile, then Railpack 0.42.0 for common stacks. |
|---|---|
| Repositories | Deploys need a repository that clones over HTTPS without credentials. Connecting a GitHub account is in preview. |
| Branches | The form reads the repository's default branch and lists up to 100 branches and 100 tags. |
| Push rebuilds | Switch them on, and pushes from GitHub or GitLab rebuild the app. GitHub deliveries are checked by HMAC-SHA256 signature, GitLab deliveries by token. |
| Rebuild limits | Only pushes to the stored branch build. Each app starts at most one rebuild per minute, and a delivery over 5 MiB is refused. |
| Replacement | The running app is replaced only after the new image is built and checked. A failed clone or build leaves it running. |
| Variables over the API | A Git deploy can carry up to 50 environment variables. They are stored encrypted and never returned or logged. |
| Rollback | Each successful deploy saves a version: images by digest, the Compose file, non-sensitive settings and limits. The panel keeps the newest 10 per app. |
| What a rollback keeps | Data, secrets and domains stay as they are now. Apps built from a Compose file in their repository can't be rolled back. |
| Compose limits | The panel refuses privileged, cap_add, host network, PID or IPC namespaces, the Docker socket and published host ports. It also refuses build: and sensitive host mounts. |
| Sizes and GPUs | Pick a preset from Nano to XL, or set your own limits. NVIDIA GPUs can go to an app: none, all or specific cards. |
Note
If a deploy fails, look at its steps and use the supported retry. Some repositories need changes before they run. With AI Deploy, changes you make in the review form are not applied.
§ 09
AI routing
The panel's own AI and the AI your customers' apps use are set up separately.
| Panel AI | It powers the assistant and AI Deploy. Use OpenAI, Anthropic, OpenRouter, Ollama or another OpenAI-compatible endpoint. |
|---|---|
| Routes for apps | Apps built for it get their route at deploy: the customer's own key, a metered key or a local model. Other apps take a key in the deploy form or set it inside the app. |
| Metered keys | You set a monthly budget and limits on tokens and requests per minute, per plan or customer. LiteLLM enforces them on each metered key. Spend is imported on a schedule, so the meter trails real use. |
| Your provider key | It goes only into your own apps. A customer's app gets the customer's own key, a metered key, a local model or no AI. |
| Local models | Ollama runs on your server. The panel lists installed models, pulls new ones and shows whether each instance uses the GPU. |
| GPU detection | The panel reads nvidia-smi where it can and falls back to a PCI scan. Its model-fit hints from VRAM are advice only. |
Caution
Apps that reach Ollama directly bypass the metered gateway, and turning on metered AI doesn't meter other existing routes. Calls to an outside provider can leave your server.
§ 10
Monitoring and operations
| Health endpoints | /healthz and /readyz, for your load balancer or your own monitoring. |
|---|---|
| Prometheus | GET /api/metrics exports host, service and panel gauges named aap_*. It is off by default and needs its own scrape token as a Bearer header. |
| What the metrics leave out | They carry no customer, organisation or reseller labels. The panel bundles no Prometheus or Grafana, so bring your own. |
| Alerts | Email by SMTP or Resend, Slack, Discord, Telegram or a generic webhook. Each channel gets the categories you pick: service, backup, deploy and system. |
| Insights | A health verdict and a list of what needs attention, with statistical anomaly detection and capacity trends. |
| Autofix restarts | It restarts an unhealthy container up to three times, after 30, 60 and 120 seconds, then alerts you. A crash loop sends one alert. |
| Autofix clean-up | At 80% disk use or more, it removes unused dangling images and orphaned panel containers. It never restarts a service its owner stopped. |
| Logs and terminal | Follow container logs live. Platform administrators can open a terminal in a running container. |
Note
Each autofix action has its own switch, and its history shows what it did. Everything else stays with your team.
§ 11
Updates
The check.
Every day, the panel compares its version with the latest release on the registry. Choose the Stable or Beta channel, or pin the current version.
The swap.
The panel writes an update request, and a systemd unit on the host performs the update.
Before it.
The panel takes a
pg_dumpof its own database and keeps the three most recent. A failed dump stops the update.Signatures.
The image and every file the updater installs are checked against a signed release manifest. A file that fails the check stops the update. Servers with an older updater get this check once it is refreshed.
After it.
If the health check fails, the panel tries to roll the update back.
Automatic updates.
They are off until you switch them on and choose a daily time and time zone.
§ 12
Backups, exactly
| What is captured | PostgreSQL databases in custom format, with roles but without their passwords. For apps without a database, the app's own named volumes. A manifest records sizes and SHA-256 checksums. |
|---|---|
| What is refused | Other database engines, shared volumes and bind mounts. |
| Where it goes | One S3-compatible bucket, by hand or on a cron schedule, with retention in days. Backups to S3 need Power User or Web Host. |
| While it runs | Backing up an app's files stops the app until the backup is done. At most two backup or restore jobs run at once on a server. |
| Size limit | A volume backup holds up to 50 GiB per volume. |
| Full restore | One setup restores from the panel: a small Directus app on PostgreSQL 16 that is not assigned to a customer. Its data can be up to 256 MiB. |
| How it restores | You take the full snapshot by hand. The panel checks the backup and saves a safety snapshot before it restores. |
| Everything else | Database and file backups are kept as stored copies, with no restore in the panel. Your team can put a database backup back by hand. |
| The panel's own data | A systemd timer runs at 03:00 server time. It copies the vault and dumps the panel and Keycloak databases into /opt/aiadminpanel/backups/, and keeps seven days. Older servers get it once the installer's updater is refreshed. |
Caution
The nightly copies stay on the same server, and the database dumps are not encrypted. Copy them to a safe place yourself, and keep the vault's key in a separate place.
§ 13
What connects outside your server
The apps and their data run on your server. These connections reach services outside it.
| What | Where it goes | When |
|---|---|---|
| Licence checks | Our licensing service | When you check or activate a paid licence, then once a day. |
| Update check | The registry that hosts the panel image | Every day. |
| Installer, updates and images | Our download server, package repositories and image registries | When you install, update or deploy. |
| Code | The Git host, such as GitHub or GitLab | When you deploy or rebuild from Git. Builds may also download language runtimes and packages. |
| Models | The model registry | At install for the starter model, then when you pull one. |
| Profile pictures | Gravatar | When a user's picture shows. The browser sends a code made from the user's email address. |
| Usage statistics | Us | The licence agreement allows it. It covers data such as the panel's version, its licence key and counts of customers and services. |
| Certificates | Let's Encrypt | When a certificate is issued or renewed. |
| DNS records | Cloudflare | Only if you connect Cloudflare DNS. |
| Temporary address | Our domain service | Only on installs without their own domain. Keeping it means confirming an email address with that service. |
| AI requests | The provider you set up | When the panel or an app uses an outside provider. |
| Email and alerts | Your mail server or Resend, and your alert channels | When one is sent. |
| Backups | Your S3-compatible bucket | When a backup runs. |
| Chat apps | The chat app you connect to an agent | When the agent sends or receives messages. |
| Each app's own connections | Whatever that app's settings say | As the app decides. |
§ 14
Known limits in v2.17.0
| Private repositories | Deploys need a repository that clones over HTTPS without credentials. Cloning over SSH doesn't work yet. |
|---|---|
| Restore | Full restore covers one setup. Test recovery for each customer's app before you promise it. |
| One server per panel | Apps run on the server where the panel is installed. Each installation is its own panel, with its own customers and apps. |
| Plans and payments | The panel records plans, entitlements and an outside billing reference. It doesn't issue invoices or collect payments. |
| Quotas | A customer's plan limits are checked when an app is deployed. Later changes to a running app's limits are not checked against the plan. |
| Organisation plans | Resource plans for organisations are stored, and the panel doesn't enforce them yet. |
| IPv6 | The egress guard and the temporary addresses cover IPv4 only. |
| Coding workspaces | Files and sign-ins are kept. Running sessions end when the workspace restarts. |
| The catalog | It lists what we package. Check each app with your own setup before you offer it to customers. |
| The audit log | It records supported events. Check that it covers what your customers ask for. |