Admin UI guide

Logging in & two-factor authentication

Login has two steps:

  1. Enter the admin password.
  2. Enter the 6-digit code from your authenticator app (or a one-time backup code).

The first time you log in, the panel makes you set up two-factor authentication (2FA) before anything else. It shows a QR code — scan it with an authenticator app such as Google Authenticator — and 10 backup codes. Save the backup codes somewhere safe; each one works once if you ever lose your phone.

You can enrol more than one device, and a code from any of them signs you in. Add and remove them on the Settings page.

Lost your phone? Use a backup code on the code-entry screen, then remove the lost device from Settings and add a new one. No codes left either? Run ci-agent reset-2fa on the server to clear 2FA and enroll again. See Security for the full 2FA model.

You can give this install its own name and logo. Both are optional.

What this means. Branding is cosmetic and per-install (stored on the server, so everyone who logs in sees it). It does not change how anything works — it just makes one box easy to tell apart from another.

Themes

A theme picker sits at the bottom of the sidebar. Click it to open a list of 16 themes, grouped into Dark (8) and Light (8), each with a small colour swatch. Examples: Dark · slate (the default), Ocean · azure, Crimson · red, Light · gray, Rose · blush.

Pick one and the whole panel changes instantly. The choice is one setting for the whole server, saved in the agent’s database: it follows you to every browser and device you log in from, it is used on the login and 2FA pages too, and it is included in backups. It is applied before the page draws, so there’s no flash on reload. It only changes colours — nothing else.

Notes

A Notes tab on the right edge of every admin page (the docs site excepted) slides out a scratchpad. Each note is a free-text box you edit in place — it autosaves as you type, with no separate form or save button. “+ New note” adds a row; the trash icon deletes one; a note left empty is discarded automatically. Notes are stored server-side (in the database), so they’re the same in every browser you log in from. Only whether the drawer is open or closed is remembered per-browser. Press Esc to close it.

Dashboard /

The home page, refreshed every few seconds. It shows:

Resources /metrics

A detailed, live view of how busy the server is — open it from the sidebar or by clicking a dashboard sparkline. It covers the last 10 minutes and shows:

Projects /projects

The Projects page lists every project. Each row shows the project’s Name, Slug, Category, Endpoint, a live Health badge (see Operations for what it means) and its Last run. Each row has two buttons: Open and Copy (see Copying a project below).

Creating a project

The New project form is the card below the project list.

  1. Type a Name. The Slug fills in by itself. You can change the slug now, but never after the project is created. Use lowercase letters, numbers and dashes.
  2. Optional: add one or more Category names (see the note below).
  3. Pick Build from: Docker Compose, Dockerfile, Prebuilt image or Inline compose (see deploy modes).
  4. Fill in the fields for that mode: Git URL and Branch, Working directory (for monorepos), Compose path, Dockerfile path, Image or Compose file. The compose and Dockerfile paths are relative to the working directory and must stay inside the repository (no leading /, and no .. above the repository root).
  5. Optional: set the HTTP port. Leave it blank and a free port is picked for you. In Dockerfile and Prebuilt image mode, Container port is the port the app listens on inside the container (blank = same as the HTTP port).
  6. Click Create project.

Env vars, the run timeout, volumes and domains are not on this form. You set them on the project page after it is created. Env vars are encrypted on disk but shown in cleartext in the form, so you can read and edit them.

What is a category? A category is a private Docker network. Type one or more categories (separated by commas — each becomes a removable chip); the project joins every network you list and can reach, and be reached by, any project that shares at least one of those networks by hostname. Projects with no category in common are isolated from each other. Leave it blank for the shared default category. Typing a brand-new category shows a small warning so you can catch typos. Changing the list re-homes the running stack immediately — no redeploy needed. See Project conventions.

Private clones authenticate with a credential you register on the Git credentials page (see Git credentials below).

Copying a project

You can duplicate a project with its settings.

  1. Click Copy on the project’s row in the list, or in the project page header.
  2. In the Copy project dialog, type Copy to name and New slug. The slug must be unique.
  3. Click Copy project.

The copy gets the same env vars, volumes, service limits and proxy settings. Its host ports are changed to free ports, so it doesn’t clash with the original. Domains and run history are not copied, and the copy gets its own new webhook token.

screenshot: the Copy project dialog

The project page

The header shows the project name with an active or archived chip and when it was created. Buttons on the right:

If another project uses the same port, a banner says Port … is also claimed by: ….

Below the header are four tabs. Each tab has its own address, so you can bookmark it:

Tab Address What’s on it
Overview /projects/<slug> Internal access, Health, Network
Domains /projects/<slug>/routing the Domains card: domains per port, default URLs, Proxy tuning
Deployments /projects/<slug>/deploy Webhooks, Trigger a run, Run history, Containers
Settings /projects/<slug>/settings the Settings card, Ports, Resource limits, Volumes, Danger zone

Overview tab:

Settings tab — the Settings card holds several small forms, each with its own button:

Domains tab

screenshot: the Domains tab with the primary radio, HTTPS chips and Maintenance checkbox

The Domains card lists the hostnames that serve this app. When the project has more than one port, there is one table per port. Every change is written to nginx and reloaded right away.

Under each port you may also see:

What this means. The primary domain is the “real” address. Visitors who type another of the app’s domains are sent there, so search engines and cookies see one name.

What you can do on the project page

SSL for one domain /projects/<slug>/domains/<id>/ssl

Click Add SSL or Manage next to a domain on the Domains tab. The page title is SSL · your-domain.

Full details: Domains & TLS.

screenshot: the SSL page for one domain

Certificates /certs

All certificates on this server in one place. Open it from the Certificates link in Settings → Default subdomain or on a domain’s SSL page.

Full details: Domains & TLS.

screenshot: the Certificates page

Offline certs /offline-certs

Get a trusted Let’s Encrypt certificate for a server that has no internet.

  1. On a server with internet, open Offline certs. Under Issue & export (online server), enter the Domain, pick Wildcard or Dedicated, and click Start order.
  2. With a DNS provider picked in TXT records, ci-agent does the DNS part itself. With Manual, publish the DNS TXT record it shows, then click Validate & issue.
  3. Download the bundle from the Offline certificates table.
  4. On the offline server, open Offline certs. Under Import a bundle (offline server), choose the Bundle file and click Import bundle.

A certificate issued through a DNS provider renews by itself on the online server; for a manual one, Renew in the table starts a fresh DNS order. Either way, download and import the new bundle again. Full details: Domains & TLS.

screenshot: the Offline certificates page

Run detail /projects/<slug>/runs/<number>

Open a run from Run history. The page shows a Timeline (queued, started, finished, duration), a Details card, and the live log: the full run log replays instantly, then streams in real time while the run is active. While the run is active, a Cancel button stops it (and force-kills it if it doesn’t stop). The log viewer has the same controls described under Container logs below.

The Details card shows the trigger, source, commit, message, committer, image tags and any error. It also shows:

screenshot: run detail page with the Run ID and Status callback rows

Container logs /projects/<slug>/logs

Live output of the project’s currently deployed containers (distinct from run logs, which capture a build/deploy). Pick a single service or stream all of them. Both this page and the run log use the same viewer:

Very large logs stay fast — the viewer only draws the lines on screen and, once a log gets huge, drops the oldest lines (shown as a “— N earlier lines dropped —” marker at the top).

Terminals

A terminal is an interactive command-line session you drive from the browser — the same as typing in a real shell on the server.

Both are full terminals: colours, interactive programs and window-resize all work. If the connection drops, click Reconnect.

Important: this is root-level access. The server shell runs as the agent’s own user (ci-agent). Plain sudo asks for a password, and that account has none, so most sudo commands fail. But the account can still do root-level things:

  • it is in the docker group, and Docker access is root-equivalent (for example docker run --privileged);
  • it may run a few commands as root without a password: nginx test and reload, service controls, firewall commands, and the ci-agent program itself, which includes a helper that can read, write and delete any file.

Treat the server shell like a root SSH login. Only give the admin password and 2FA to people you would give root to.

Open host SSH session — for normal admin work as your own account, the server shell’s Snippets drawer has an Open host SSH session button at the top. It drops an ssh <admin>@localhost command at the prompt (the admin account is auto-detected). This logs you into a real host session via sshd, with full sudo. You type your own login password, so the work is tied to a real person’s account rather than the service. (First use trusts localhost’s host key automatically, so you land straight on the password prompt.) When tmux is installed, the session is wrapped in a persistent tmux session, so a browser refresh, network drop, or interrupt only detaches it — your work keeps running and clicking the button again re-attaches.

Copy a file into a container — the Copy file to container card below the container shell pushes a file into a container.

  1. Pick the Container.
  2. Pick the Source: File upload (choose a File from your computer) or Path on host (type a Host path — a file or folder on the server).
  3. Type the Destination path inside the container (blank = /tmp/).
  4. Click Copy into container.

Useful for dropping a config file or a restore file next to a running app.

Snippets — a Snippets tab on the right edge of the shell pages keeps a list of reusable commands (an optional label plus the command). Click + New snippet to add one; it saves as you type, like Notes above. Hover or focus a snippet, then:

Snippets are stored on the server and shared between the server shell and every container shell. The drawer also has a Handy commands list of common commands; click one to put it at the prompt (it won’t run by itself).

Problem Fix
sudo asks for a password and fails The agent account has no password. Use Open host SSH session and log in as your own admin account.
Permission denied after Open host SSH session Wrong password, or the server only allows SSH keys. Enable PasswordAuthentication in sshd, or add a key for the agent account.
The container shell says no containers were found Deploy the project first. A container must be running to open a shell in it.

Files

A point-and-click file manager — the same operations as the shell, without the typing. Two surfaces share one UI:

In either mode you can:

Delete asks you to confirm first, and deletes folders with everything inside them — double-check the path. Changes are recorded in the audit log (see Audit below).

Host /host

The Host controls page puts host-level settings in one place:

Common problem: “Privileged host actions are unavailable.” This yellow banner on the Host and Firewall pages means the agent’s sudo rules are not loaded, so applying nginx config, controlling services and changing firewall rules will fail. Fix it from an SSH session:

sudo /usr/bin/ci-agent reconcile-sudoers

If that logs failed validation, run sudo visudo -cf /usr/share/ci-agent/ci-agent.sudoers to see the error. See Security.

Firewall /firewall

A simple front end for the host’s UFW firewall — no command line needed.

What this means. UFW (Uncomplicated Firewall) decides which network connections the server accepts. “Allow port 80” lets web traffic in; a “Deny” rule blocks it. Rule numbers shift after each delete, so the list is re-read from the firewall every time the page loads.

Common problems and fixes. Locked out after enabling? The panel always allows SSH (22) and its own port first, so you should stay connected — reach the box over SSH and run sudo ufw status to check. Rule didn’t apply? The agent needs its firewall sudo rule; on a package install this is set up for you (see Security).

Tunnel /tunnel

Set this box’s tunnel Role. While tunneling is off the page shows two role cards — Online (a public relay that also serves its own apps) and Local (a private/NAT’d box that dials out). Picking one opens that role’s screen with an On/Off switch and only its settings: on the Online screen you manage tunnels and hostname routes; on the Local screen, the relay connection settings. Nothing changes until you turn the switch on. It lets a box with no public IP serve its apps through a public one, with TLS terminating on the private box. Full guide: Reverse tunnel.

Storage /storage

A read-only storage report on top, then disk cleanup actions.

Report (read-only):

Cleanup — each section shows what it removes, an estimate of how much it will free, the items affected, and a single button:

Images belonging to the last N successful runs of every project (the Redeployable runs / project setting, default 1) and project-data volumes are protected and never removed, so recent versions stay redeployable and app data is safe. With auto-prune on (the default), this same cleanup also runs automatically after each deploy and nightly — so you rarely need these buttons. The Docker actions operate on the whole Docker daemon — if other software shares this host’s Docker, its dangling images and stopped containers are affected too. OS-level cleanup (apt cache, system logs) is intentionally not offered: the agent runs unprivileged — use the Server shell for that.

Audit /audit

The Audit log lists every admin action and accepted webhook, with its Time, Actor, Action and Detail: logins (and failures), project changes, token rotations, triggers, cancellations, prunes, file changes and settings changes. Changes made with an API key show the key as the actor (api:<key name>).

API keys /api-keys

API keys let scripts and AI agents use this server through the API. Each key has an access level:

To create a key, fill in Create key (a name, the level and when it expires) and click Create key. The page then shows the key once, with a Prompt for your AI agent you can paste into the agent. The prompt contains the key, the API address and links to the docs. Copy both before you leave the page.

The Keys table lists every key with its level, the first characters of the key, its status (active, expired or revoked), and when and from which IP address it was last used. Revoke stops a key immediately. A revoked or expired key can then be deleted.

Connect an AI agent shows the same prompt with placeholders. What each level can do lists every API endpoint and the level it needs.

Maintenance /maintenance

Git credentials /git-credentials

Store login details for cloning private repositories, once per git host — not per project. There are two shapes:

Fill the form (Host, optional Owner, optional Username, Secret) and click Save credential. Secrets are encrypted at rest with secret_key_file and never shown again — the table shows only “••••• set”. Delete a credential to revoke access.

What this means. A credential is just a saved username + secret for one git host. You add it here once, and every project that clones from that host uses it — you never paste tokens into individual projects.

Settings /settings

The Settings page collects everything you change from the UI:

What this means. SMTP is the standard way programs send email. You point the agent at a mail server (your own internal relay, or any SMTP server it can reach) and it sends through that. On an air-gapped network, use an internal relay; choose None (25) only on a trusted LAN.