First-Time Setup
Install Trinity, log in as the admin, and meet the starter fleet a fresh install comes with.
How to finish first-time setup
1:219 chapters
I Built a DevOps Agent That Deploys Other Agents
Apr 2026
Key Concepts
Admin Account — The primary account with full platform access. It is created from ADMIN_PASSWORD in .env when the backend first starts; the installer (start.sh) requires that value, so on a normal install the account exists before you open the browser. To change the admin password, use Settings → General → Password (see Changing the admin password); the new password survives restarts. A backend start re-applies ADMIN_PASSWORD only when the value in .env differs from the one it last applied, so editing that line and recreating the backend still sets a new password or recovers a forgotten one. The exception is a cloud install created without a password — a DigitalOcean Marketplace 1-Click droplet, a Vultr Marketplace server, or an AWS install: it boots with no admin account, and the first person to open it in a browser creates one (on AWS, only after proving the instance ID). The admin signs in with the username admin (or ADMIN_USERNAME) or a registered email address, plus the password.
First-run form — A one-page “Create your admin account” screen at /setup that appears only on an install with no admin account — a one-click marketplace or AWS install claimed in the browser, a blank ADMIN_PASSWORD brought up without the installer, or a hand-rolled backend. It refuses to run once a usable admin exists, whatever the setup flag says.
Email Login— A passwordless authentication method where users receive a one-time code via email. Requires an email service to be configured.
Starter fleet— The agents a fresh install seeds for you: the Cornelius second-brain agent plus a three-agent starter team. Nothing to configure; deleting them does not bring them back.
How It Works

The recommended production shape: everything on one host as Docker containers, private access over your VPN (Tailscale recommended), public endpoints published only through an outbound tunnel, and agents on a separate network from the data plane. A local install is the same containers with ports exposed directly.
Prerequisites
Database. A local install runs on a bundled PostgreSQL container, and ./scripts/deploy/start.sh generates its password. SQLite reached end-of-support on 2026-09-01, and an existing trinity.db is refused at start until it moves: see the SQLite → PostgreSQL guide.
Installation
Clone the repository
git clone https://github.com/abilityai/trinity.git
cd trinitySet the admin password
cp .env.example .env
# Set ADMIN_PASSWORD to a strong password (12+ characters)start.sh refuses to start while ADMIN_PASSWORD is blank. It generates every other secret (SECRET_KEY, INTERNAL_API_SECRET, CREDENTIAL_ENCRYPTION_KEY, AGENT_AUTH_SECRET, the Redis passwords) and detects DOCKER_GID on first run, writing them back to .env.
Start all services
./scripts/deploy/start.shOn first run this builds the base agent image if it is missing (5–10 minutes), starts the backend, frontend, MCP server, Redis, scheduler, Vector and OTel collector, waits for the backend to report healthy, and prints the access URLs with a next-steps card. ./quickstart.sh is an alias for the same script.
No-prompt install: run ./scripts/deploy/start.sh --unattended (or set TRINITY_UNATTENDED=1) and the script never stops to ask for input — it generates the admin password and prints it in the final summary. Save it: it lands in .env and is shown only once. (A Marketplace 1-Click droplet is the exception: it never generates a password; its login banner prints the URL to claim the instance instead — see the first-run form below.) An AI coding agent (Claude Code) can drive the entire local install for you via the runbook at docs/AGENT_INSTALL_GUIDE.md. Server installs, prebuilt images and the DigitalOcean 1-Click: Deploying Trinity.
Open in your browser and log in
Navigate to http://localhost and log in.
The first-run form (installs with no admin only)
If the backend started with a blank ADMIN_PASSWORD, every page redirects to a one-page “Create your admin account” form at /setup until an admin exists. These installs land here:
A DigitalOcean droplet created without a password (the Marketplace 1-Click, or the trinity-do-create.sh installer). This is by design: the 1-Click create page has no input form, so the image boots with ADMIN_PASSWORD blank and ADMIN_PASSWORD_SOURCE=browser, and the droplet's login banner prints the URL to claim it — never a password. A 1-Click droplet you gave a password at create time (cloud-init user-data) has its admin provisioned at boot and never shows the form; that password stays in the droplet's user-data for the droplet's life. A Vultr Marketplace server behaves the same way.
An AWS install created without a password (start.sh --provision --cloud aws, the CloudFormation stack, or the AWS Marketplace AMI). The form also asks for the EC2 instance ID — see Instance-ID claim below.
A bare docker compose up -d or a hand-rolled backend brought up with the password blank. The installer does not allow this on a normal install. A hosted compose started by hand with a blank password and no ADMIN_PASSWORD_SOURCE=browser marker is refused: set ADMIN_PASSWORD in .env and restart, or run ./scripts/deploy/start.sh --hosted.
On the form, enter your admin email (required — it becomes your sign-in identity), a password (12+ characters with uppercase, lowercase, number, and special character; a live checklist guides you, and the strength meter reads Excellent only once all five are met — with one missing it names it, for example Needs 12+ characters), confirm it, and optionally your company name and an opt-in to security and product update emails. Submitting signs you straight in and opens the Dashboard. In the background, Trinity then deploys the system agent (trinity-system) and seeds the starter fleet — on these installs both wait until the admin exists, because they are owned by it. The form disables itself permanently after the account is created, and the backend refuses it outright whenever a usable admin already exists — so an install that booted with ADMIN_PASSWORD set is never in this window.
Instance-ID claim. An install whose .env sets ADMIN_PASSWORD_SOURCE=instance-id adds one field to the form: the server's EC2 instance ID, found in the AWS console under EC2 → Instances. Provisioning stores that ID in a setup-claim file in the data directory, and the form works only when you enter the same ID. Any mismatch gets one answer, That instance ID does not match this server., and repeated wrong guesses are rate-limited like failed logins. Email is optional on this path; without one, the admin signs in as admin with the password. The stored ID is deleted once the account exists. If the file is missing, every attempt is refused. An AWS install with no password takes this mode by default: start.sh --provision --cloud aws (which the AWS Marketplace AMI and the CloudFormation stack also run) reads the ID from the instance metadata service and writes the file. Supply ADMIN_PASSWORD to skip the claim. Other clouds never use it. See Deploying on AWS.
On a claimed droplet, .env keeps ADMIN_PASSWORD blank on purpose — the password lives only in the database, and reboots and start.sh --hosted updates leave it alone. Forgot it? Set ADMIN_PASSWORD in .env and recreate the backend container (./scripts/deploy/start.sh --hosted, or docker compose up -d backend); docker compose restart does not re-read .env. The backend adopts the value on that boot.
Security note: on an install with no admin, the form is reachable without authentication until you use it — anyone who can reach the URL can claim the instance. Keep such an instance behind a tunnel, VPN, or firewall until the admin account exists. On a 1-Click droplet, open its URL right after creating it (first boot takes about ninety seconds) or restrict port 443 to your own IP until you have claimed it; if a droplet you have never opened shows the login page instead of the form, someone else got there first — destroy it and create another. Setting ADMIN_PASSWORD before first boot closes the window entirely.
Logging In
Admin login — Enter username admin or the admin's registered email, plus the password.
Email login (passwordless) — Enter your email address, receive a 6-digit verification code, and submit it to log in. This requires email service configuration. On an install that cannot send email — the default console provider, or a provider missing its key or SMTP settings — the code step says so instead of “We sent a code”: No email provider is configured on this install, so no email was sent. The code for an allowed address is in the backend log (docker compose logs backend, the EMAIL (console mode) block), and an Admin Login button there switches to the password form. The admin manages allowed email addresses under Settings → Access → Email Whitelist. Each entry is one full email address, matched without regard to case — there are no domain or wildcard entries. An entry that is not one address (empty, containing spaces, without exactly one @ with text on both sides, or over 254 characters) is refused with the reason shown beside the field, and the API answers 422 with the same one-sentence reason. Intranet addresses such as user@localhost are accepted. Remove works on every row, including older entries that contain unusual characters such as /.
Password login is rate-limited: five failed attempts on one account within 15 minutes lock that account out until the window passes (a looser per-address limit — 30 failures in 5 minutes — guards shared networks without locking out everyone behind one address).
Changing the admin password
Settings → General → Password changes the password of the account you are signed in as. It appears only for an account that has a password (the admin); an email-only account has none and never gains one.
- 1.Enter the Current password, the New password (the same rules as the first-run form: 12+ characters with uppercase, lowercase, number and special character) and Confirm new password.
- 2.Optionally tick Also revoke the MCP API keys I created. A password change does not sign MCP keys out; your agents' own keys are not affected either way.
- 3.Click Change password.
Changing the password signs every other session of the account out, on every browser and device, and closes their open live connections (event streams and terminals); the session you changed it from stays signed in. If any keys you created still work afterwards, the panel says how many and links to Settings → MCP Keys. Five wrong current passwords within 15 minutes block further attempts for the window.
The new password survives restarts. If .env still holds the old ADMIN_PASSWORD, the panel reminds you to update the file too, so the MCP server's password sign-in and any scripts that read it keep working. Putting a new value in .envand recreating the backend still overrides an in-app change, which is how you recover a forgotten password. An admin cannot reset another person's password: no other account has one.
Terms of use
Every person who signs in is asked to accept the instance's terms of use once, before they can do anything else — the admin included, on whichever door they come in by: the admin panel, the email sign-in or the Workspace. A fresh install ships default terms, so the screen appears with nothing configured. The admin's own first visit after setup shows it too; setup itself is never blocked by it.
An admin edits the terms under Settings → Access → Terms of use:
Title and Text (Markdown), then Save as a new version. Saving changed text or title stamps a new version, and everyone is asked to accept again on their next visit; saving what is already in force changes nothing.
Restore the default puts the shipped default text back.
Ask every person to accept the terms switches the screen on or off. It is on by default.
Acceptances lists who accepted which version and when.
Accepting is recorded per person and version, with the time and address, and the edits and acceptances are recorded in the audit log (the edit rows carry the version only, never the text). Declining signs the person out; they accept on their next sign-in. Scripts and the CLI are never asked, and neither are the MCP keys of operators and above or agents' keys: the screen is for people signing in to the app, so an ops key or an agent's key keeps working whether or not anyone has accepted. A Workspace-only (user) person's own key is held until that person accepts.
Your First Dashboard
On a fresh install the Dashboard opens first-run setup: one sequence over a dashboard that does not move underneath it. A rail on the left lists the steps this install actually needs — steps that do not apply to you never appear — and marks each one done as you go. The order is fixed, and you can go back:
Secure this instance — Only on an install provisioned onto a cloud VM at a bare IP (the DigitalOcean 1-Click or trinity-do-create.sh installer, the Vultr Marketplace app, or an AWS install), for admins, until a domain is configured. Point a domain at the server, enter it as the Public URL and click Save domain, then optionally serve it through a Cloudflare Tunnel. Saving completes the step. Its badge reads Domain saved until the first visit to that name reaches the server, then Domain reached. “Why this matters” explains both stages and links the full hardening guide. See Single Server → DigitalOcean 1-Click.
Sign-in email — Only when the admin account has no email yet, so you can log in with email + password. An admin provisioned from ADMIN_PASSWORD has none until you bind one here (on PostgreSQL, earlier builds recorded the username as the email, which hid this step; an upgrade clears that and the step appears). Trinity mails a 6-digit code to the address (valid 10 minutes) and binds it only once you enter that code, so nobody can claim an address they do not own. One address belongs to one account: an email already used by another account is refused. On an install whose email provider is still console (codes go only to the server log), the admin may bind without a code. An install you claimed in the browser collected the email at /setup, so this step does not appear. Also at Settings → General → Admin sign-in email.
Connect Claude— The one required step. Paste a Claude subscription token or an Anthropic API key; it is checked with Anthropic before it is saved, and the first credential is handed to the agents that had none. Until this is done, no agent can run.
Other keys — Optional: a GitHub token, an email-provider key (needed for email sign-in codes), and a Gemini key (voice features and generated agent avatars). Each says what skipping it costs, and all of them live at Settings → Integrations afterwards. See Platform Keys.
Your first agent — Two doors: Show me (Watch Cornelius work) opens a seeded agent's chat so you can see one at work, and Make me one creates one from a purpose you pick — the details are in Quick Start → Guided Onboarding. Already running a fleet? A link takes you to migrating an existing one. Whichever door you take, Doneat the end of the sequence opens that agent's chat. The step counts as done once you own an agent Trinity did not seed.
Usage sharing — The anonymous usage-sharing consent, asked once inside the sequence rather than as a dialog afterwards (see Telemetry).
Every step except Connect Claude is skippable, and skipping tells you where to find it later. Finish later closes the whole sequence; nothing re-opens it on its own. To pick it up again, use Settings → General → First-run setup → Re-run setup, or add ?onboarding=1to the Dashboard URL — completed steps stay complete.
After setup, a Getting started checklist can keep you going. It ticks off your first milestones over your first days and hides itself when the last one is done. It appears only on instances with the matching enterprise entitlement.
Where it is — In the Dashboard's left Systems sidebar, under the list of views and above New View. It is not in the Dashboard body, so it never pushes the fleet down. The sidebar opens expanded unless you collapsed it earlier in this browser. Collapsing it hides the checklist along with the view labels.
How it works — Its header shows your progress (for example 1/4) and collapses or expands the list. Your browser remembers that choice. Only the next unfinished item has an action button. The list refreshes whenever you return to the Dashboard, so a milestone you reach on another page shows up without a reload.
Retiring it — Don't show this againhides the checklist for good. Nothing brings it back, so collapse the header instead if you only mean “not now”.
Your Starter Fleet
On a fresh install, Trinity seeds agents so you land on something working without cloning or configuring a template:
Cornelius — a ready-to-use second-brain agent, cloned from its public template at first boot and kept pull-only (it never pushes your knowledge back to that shared upstream), with the Brain Orb enabled — a self-rendering 3D knowledge graph on its Brain tab (see Dynamic Dashboards → the Brain Orb).
The acme starter team — three collaborating agents from the bundled default system manifest: acme-scout (research), acme-sage (strategy) and acme-scribe (content), sharing folders and able to call each other. They ship with no schedules and need no credentials at seed time. Skip or replace this fleet with TRINITY_DEFAULT_SYSTEM_MANIFEST — see System Manifests → Default System on First Run.
Seeded agents appear on the Dashboard as soon as they exist; closing first-run setup refreshes the fleet. Seeding runs once, only on a truly fresh install: it is skipped when the instance already has agents, and deleting a seeded agent does not re-create it. Installs without Docker (demo mode) skip it entirely. The seeded agents cannot think until you add a model credential — the Connect Claude step of first-run setup, or an Anthropic API key or a Claude subscription under Settings → Integrations; the first credential you add is connected to every agent that has never run successfully. The three acme agents ship with a bundled default avatar; Cornelius shows initials until a Gemini key exists and Generate Default Avatars(Settings → General) has run.
Security & product updates (optional)
Settings → General → Security & product updates lets the admin opt in to occasional security and product-update emails from the Trinity team: Email (required), Company, Name, Role and Primary use case (optional), an Exactly what would be sent preview, and Opt in & submit. It sends exactly that, at most once per install, and nothing leaves the box unless you submit. An install claimed in the browser asked the same question on the /setup form; ticking it there is the same once-per-install submission. Air-gapped or privacy-strict installs disable it entirely with OPERATOR_INTAKE_ENABLED=false or DO_NOT_TRACK=1. The separate, anonymous Usage sharing consent is described in Telemetry.
Key URLs
| Service | URL |
|---|---|
| Web UI | http://localhost |
| Backend API docs | http://localhost:8000/docs |
| MCP Server | http://localhost:8080/mcp (on a server install also https://trinity.your-domain.com/mcp). Clients outside the Trinity server — Claude Code on your laptop included — need External MCP access turned on once under Settings → MCP Keys; a fresh install starts with it off. See MCP Server |
Stopping and Starting
# Stop all services (containers and the agent network stay in place)
./scripts/deploy/stop.sh
# Start all services
./scripts/deploy/start.sh
# Rebuild services after code changes
docker compose build --no-cache backend frontend mcp-server scheduler
# View backend logs
docker compose logs -f backendNever docker compose down an instance you want to keep — see Deploying Trinity → Managing Services.
Settings
Settings is tabbed — General, Access, Integrations, MCP Keys, Agents, Retention, plus tabs that appear only when the corresponding capability is enabled. The tab-by-tab guide is in Using Trinity → Settings. The GitHub personal access token that lets agents pull and push repositories is covered in GitHub PAT Setup.
For Agents: Authentication API
Authenticate programmatically using the token endpoint:
POST /api/token
Content-Type: application/x-www-form-urlencoded
username=admin&password=YOUR_PASSWORDReturns:
{
"access_token": "eyJ...",
"token_type": "bearer"
}Include the JWT access_token in the Authorization header for all authenticated requests:
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
http://localhost:8000/api/agentsToken Details
JWT tokens are valid for 7 days
Tokens are invalidated when the backend restarts. Re-login is required.
MCP API keys (prefixed trinity_mcp_) also work as Bearer tokens
Unauthenticated Endpoints
The following endpoints do not require authentication:
Binding a sign-in email
Both calls take a signed-in browser session; no MCP key can change a sign-in identity.
Changing the password
Terms of use
Until a person accepts, every other call from their signed-in session answers 403 with {"code": "terms_required", "version": "..."}, and the app opens the terms screen.
First-run state
Limitations
Backend restarts invalidate all active JWT tokens. All users and integrations must re-authenticate.
Email login requires a configured email service. Without one, codes are written to the backend log and the login page says so; admin password login always works.
Trinity requires Docker. It cannot run without it.
Seeding Cornelius needs outbound access to GitHub at first boot; a failed pass is retried on the next start.
PostgreSQL is the database backend. See Single-Server Deployment → Database backend.