Skip to main content

Installation

This guide walks you through setting up a CoderFlow server.

Prerequisites​

A Linux server with the following installed:

Optionally, if you'd like the server to listen on a port below 1024 (such as 443 or 80):

  • On Ubuntu and Debian-based distros - Install authbind via APT package manager.
  • Other distros - See your distro's documentation for enabling non-root users to bind network services to privileged ports

Root Permissions​

info

Only a few parts of the installation process require root permissions.
Do not use root permissions (i.e. sudo or su) except where specifically instructed.
The server installs and runs as a non-root user.

Create a Dedicated Linux User For Each Installation​

Each installation of CoderFlow server should run under a unique and dedicated user account, rather than your personal account or root. This provides better security isolation and makes it easier to manage the service.

Create a dedicated user (we suggest coder, but any name works):

# Create the user with a home directory
sudo useradd -m -s /bin/bash coder

# Set a password (optional, if you need interactive login)
sudo passwd coder

# Add the user to the docker group so it can manage containers
sudo usermod -aG docker coder

If coder conflicts with an existing user on your system, choose a different name — the server works the same regardless of the username.

Optional: If Using Server Listen Port Below 1024​

If you'd like to use a server listen port below 1024 (e.g. 443), configure authbind to allow the dedicated CoderFlow user to use the port:

For example, for port 443:

sudo touch /etc/authbind/byport/443
sudo chown coder /etc/authbind/byport/443
sudo chmod 500 /etc/authbind/byport/443

Switch to Dedicated CoderFlow User​

Switch to the dedicated user before proceeding with installation:

sudo su - coder

Install Node.js via NVS​

Use the installation guide to install Node Version Switcher (NVS) in the dedicated user's home directory. This allows each CoderFlow installation/user to use a separate version of Node.js. If you prefer, you can use nvm instead, but NVS will be used in this documentation.

After installing NVS, exit and restart your shell and then install Node 24:

nvs add node/24
nvs use node/24
nvs link node/24

Setup​

Install the Server​

npm install -g @profoundlogic/coderflow-server

Create a Setup Repository​

The setup repository contains your environments, task templates, and configuration.

If your organization already has a setup repository, clone it:

git clone https://github.com/your-org/mycompany-coder-setup.git

Otherwise, create a new one:

coder-server init mycompany-coder-setup

This creates a mycompany-coder-setup directory with the required structure and initializes it as a git repository.

Then configure the server to locate the setup directory using a command like this, specifying the path to the setup directory:

coder-server config set coder_setup_path mycompany-coder-setup

Install License​

coder-server license set <your-license-key>

Create Admin User​

coder-server create-user --username=admin --email=admin@example.com --name="Admin User" --admin

You'll be prompted to set a password.

On a brand-new install, the first created account is automatically granted Server Admin even without --admin (this policy is enforced in the shared user service, so it applies across CLI/API/OIDC auto-provisioning paths).

Optional: Configure Server Listen Port and SSL​

By default the server listens on port 3000. To configure an alternate port (e.g. 443):

coder-server config set server_port 443

To configure a certificate for SSL:

info

Certificate and key files must be in PEM format.
Concatenate certificate, intermediate, and root into a single file, in that order.
File paths can be given as absolute or relative.
Files must be readable by the dedicated CoderFlow user.

coder-server config set ssl_cert_path mycert.pem
coder-server config set ssl_key_path mykey.pem

Optional: Configure Trusted Proxy Headers​

If CoderFlow runs behind nginx, Apache, Cloudflare, or another reverse proxy, enable trusted proxy handling before configuring HTTPS-only integrations such as OAuth providers:

TRUST_PROXY=true coder-server start

You can also enable Trust Proxy later from Server Settings -> General Settings and restart the server. This lets CoderFlow read forwarded protocol, host, and client IP headers correctly. See Server Operations & Monitoring for operational notes.

Start the Server​

coder-server start

If using a listen port below 1024 (e.g. 443, 80) and using authbind to allow that, the server must be started like this instead:

authbind --deep coder-server start

Once running, log in to the Web UI (default port 3000) with the admin user you created.

Set Up Git Providers​

To allow CoderFlow access to your Git hosting service (e.g., GitHub), follow the instructions in Git Providers.

Configure Your Environment​

The coder-server init command created a default environment with placeholder values. Configure it through the Web UI:

  1. Navigate to Environments in the Web UI
  2. Click on the default environment, if it isn't already selected
  3. Update each section:

Repos​

Click Add Repository to add your GitHub repository:

  • Git Provider: Choose a Git provider from the list
  • URL: URL (e.g., https://github.com/acme/my-project.git)
  • Branch: Default branch (e.g., main)

Build Docker Images​

Docker images must be built before you can run tasks. There are two ways to build images: through the Web UI or using the CLI.

Build Base Image​

Build the base image that all environments inherit from.

Web UI:

  1. Navigate to Settings → Environments
  2. Select your environment, if it's not already selected
  3. Click Actions → Build Base Image
  4. Optionally check "Build without cache" for a clean rebuild
  5. Click Build

CLI:

coder-server build base

Build Environment Image​

Build your environment's Docker image.

Web UI:

  1. Navigate to Settings → Environments
  2. Select your environment, if it's not already selected
  3. Go to the Build tab
  4. Click Build Now

CLI:

coder-server build default

Rebuild after making changes to the Dockerfile or setup.sh.

Set Up LLM Access​

Before running tasks, configure access to AI providers. Authentication can be performed by both OAuth and API keys.

To authenticate task execution using your subscription accounts (OAuth), follow the instructions in AI Provider Authentication.

Authentication using AI keys can be used for task execution as well as auto-generating task names. To authenticate using AI keys, do the following:

  1. Navigate to Settings → Server Settings → API Keys in the Web UI
  2. For each provider, enter the corresponding API key (the default agent's API key will be used when auto-generating task names)
  3. To execute tasks for a provider using API keys, switch its toggle on

Supported providers:

  • Claude (Anthropic)
  • Codex (OpenAI)
  • Gemini (Google)
  • Bob (IBM)
  • Grok (xAI)

Verify Installation​

The best way to verify everything works is to submit a task:

  1. Open the Web UI in your browser
  2. Select your environment and enter a simple task (e.g., "List the files in the repository")
  3. Submit and watch the task run

If the task completes successfully, your installation is working.

Server Management​

Running as a Daemon​

Use the --daemon flag to run the server in the background:

coder-server start --daemon

Manage the daemon with:

# View logs
coder-server logs

# Stop server
coder-server stop

# Restart
coder-server restart

# Check health
curl http://your-server:3000/health

Using PM2​

As an alternative to the built-in daemon mode, you can use PM2 for process management.

PM2 provides additional features like automatic restarts on crash and system boot persistence.

Install PM2 Globally​

npm install -g pm2

Start CoderFlow with PM2​

If using a listen port below 1024 (e.g. 443, 80) and using authbind to allow that, the server must be started like this:

pm2 start --name coderflow authbind -- --deep coder-server start

Otherwise start like this:

pm2 start --name coderflow coder-server -- start

View Logs​

pm2 logs coderflow

Stop/Restart​

pm2 stop coderflow
pm2 start coderflow
pm2 restart coderflow

Auto-start On System Boot​

Save the PM2 process list to disk:

pm2 save

Generate a PM2 startup script:

pm2 startup

pm2 startup outputs a commmand string to your terminal, which must be run as root, to configure the system's service manager to start up PM2 at system boot.