Installation

Codality ships as a single binary. Download it, run the setup wizard, and it handles the rest — dependencies, TLS, database, systemd service, and admin account creation.

Before you install

You need these ready before starting:

Optional:

Download

Download the latest release from codality.dev:

curl -fsSL https://codality.dev/downloads/linux-amd64 -o codality
chmod +x codality

Run the setup wizard

The setup wizard provisions your entire server:

sudo ./codality setup

Why sudo? The wizard installs system packages, creates a system user, writes to /etc, and configures systemd. It runs individual commands with sudo internally, but it's simplest to run the wizard itself as root or with sudo.

The wizard runs 8 steps sequentially. Each step is idempotent — if you interrupt the wizard or hit an error, just re-run codality setup and it picks up where it left off.

Step 1: License validation

Prompts for the path to your license file, copies it to /etc/codality/license.key.

If a license is already installed, this step is skipped.

Step 2: System dependencies

Checks for required binaries and installs any that are missing:

The wizard detects your package manager (apt-get, dnf, yum, apk, pacman, or brew) and installs packages automatically. On Ubuntu, if the chromium snap package fails (common on headless servers), it falls back to installing Google Chrome directly from Google's .deb package.

Step 3: Configuration

Prompts for configuration values interactively:

This step also:

• Generates a cryptographic session secret (64-char hex) if one doesn't exist
• Computes APP_URL from the domain (https://{domain}) or port (http://localhost:{port})
• Creates the data directory, config directory, and worktrees directory
• Writes all values to /etc/codality/codality.env

Step 4: Database initialization

Verifies the data directory exists and is writable. The SQLite database itself is created automatically on first server start — this step just validates the path.

Step 5: TLS & reverse proxy

Skipped if no domain was configured in step 3.

First, verifies DNS is pointing to this server by resolving the domain and comparing against the server's public IP. If DNS isn't configured, shows instructions for creating the A record and asks whether to continue.

Opens firewall ports 80 and 443 if UFW or firewalld is active.

Then presents TLS options based on what's already installed:

Caddy path

If Caddy is already installed, appends a reverse proxy block to the existing Caddyfile. If installing fresh, writes a new Caddyfile. Caddy handles TLS certificates automatically via Let's Encrypt — no certbot needed.

agent.example.com {
    reverse_proxy 127.0.0.1:8000
}

Nginx path

Two-phase setup:

1. Writes an HTTP-only config, reloads nginx
2. Installs certbot, obtains SSL certificate via webroot verification
3. Rewrites the config with full HTTPS (TLS 1.2/1.3, HTTP→HTTPS redirect, WebSocket upgrade, SSE buffering disabled)
4. Enables the certbot.timer for automatic certificate renewal

Apache path

Same two-phase approach as nginx. Enables required modules (proxy, proxy_http, proxy_wstunnel, ssl, headers, rewrite), obtains certificates, configures SSL VirtualHost with WebSocket rewrite rules and SSE support.

Built-in AutoTLS

Codality handles HTTPS directly on port 443 using its own ACME client. No reverse proxy needed, but port 443 must be free.

Step 6: Systemd service

On Linux:

1. Creates a codality system user (no home dir, no login shell)
2. Sets ownership of the data directory to codality:codality
3. Copies the binary to /usr/local/bin/codality
4. Writes a hardened systemd unit at /etc/systemd/system/codality.service
5. Enables and starts the service
6. Polls the health endpoint until the server is responding (up to 15 seconds)

The systemd unit includes security hardening:

• Runs as the unprivileged codality user
• ProtectSystem=strict — filesystem is read-only except for explicit paths
• ProtectHome=true — no access to home directories
• ReadWritePaths — only the data directory and config directory are writable
• NoNewPrivileges=true, PrivateTmp=true

On macOS, a launchd plist is written to ~/Library/LaunchAgents/dev.codality.plist instead.

Step 7: Admin user setup (OTP)

The server is now running. This step:

1. Fetches a one-time setup code from the running server
2. Displays it in the terminal: 3194 - 5317
3. Tells you to open the web UI and enter the code
4. Waits (with a spinner) until you create your admin account via the browser

The code expires after 30 minutes. After 5 incorrect attempts, the code is invalidated and a new one is printed.

Step 8: Metrics & updates consent

Asks whether to enable anonymous usage metrics and automatic updates. Both default to yes. Updates the env file with your choices.

What the wizard creates

After running codality setup, your server has:

Manual installation

If you prefer to provision manually instead of using the wizard, here's what codality setup does that you'd need to replicate:

1. Install dependencies

sudo apt-get install -y git openssh-client chromium

2. Create system user and directories

sudo useradd --system --no-create-home --shell /usr/sbin/nologin codality
sudo mkdir -p /var/lib/codality/worktrees
sudo mkdir -p /etc/codality
sudo chown -R codality:codality /var/lib/codality
sudo chown codality:codality /etc/codality

3. Write environment file

sudo tee /etc/codality/codality.env > /dev/null << 'EOF'
APP_NAME="Codality"
APP_URL="https://codality.example.com"
DATABASE_PATH="/var/lib/codality/codality.db"
DATA_DIR="/var/lib/codality"
DOMAIN="codality.example.com"
FROM_EMAIL="codality@example.com"
LICENSE_FILE="/etc/codality/license.key"
OPENAI_API_KEY="sk-..."
PORT=8000
SENDGRID_API_KEY="SG..."
SESSION_SECRET="$(openssl rand -hex 32)"
WORKTREE_BASE="/var/lib/codality/worktrees"
EOF
sudo chmod 600 /etc/codality/codality.env
sudo chown codality:codality /etc/codality/codality.env

See Environment Variables for the complete list.

4. Install the binary

sudo cp codality /usr/local/bin/codality
sudo chmod 755 /usr/local/bin/codality

5. Configure TLS

Set up a reverse proxy. See Server Setup for Caddy, nginx, and Apache configurations. Make sure ports 80 and 443 are open in your firewall:

# UFW
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# firewalld
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

6. Create systemd service

sudo tee /etc/systemd/system/codality.service > /dev/null << 'EOF'
[Unit]
Description=Codality — AI Software Engineering Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=codality
Group=codality
WorkingDirectory=/var/lib/codality
ExecStart=/usr/local/bin/codality start
Restart=always
RestartSec=5
EnvironmentFile=/etc/codality/codality.env

NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/codality /etc/codality
PrivateTmp=true

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable codality
sudo systemctl start codality

7. Create admin account

Watch the service logs for the setup code:

journalctl -u codality -f

Open the web UI, enter the setup code, and create your admin account.

First login

When Codality starts with no admin account, it displays a setup code in the terminal and on the service logs:

╔══════════════════════════════════════════════════╗
║  SETUP CODE:  1234 - 5678                        ║
║                                                  ║
║  Enter this code in the web UI to create         ║
║  your admin account. Expires in 30 min.          ║
╚══════════════════════════════════════════════════╝

Open the web UI and enter this code with your email and name. This creates the first admin account.

Subsequent logins use email OTP: enter your email, receive a code via SendGrid, enter it.

Next steps

• Server Setup — Reverse proxy details, firewall, backups, and production tips
• Environment Variables — All configuration options
• Updating — How to update to newer versions