---
sidebar_position: 1
---

# Installation

This guide walks you through setting up a CoderFlow server.

## Prerequisites

A Linux server with the following installed:

- **Docker** — [Install Docker Engine](https://docs.docker.com/engine/install/)
- **Git** — Available via your distribution's package manager

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](https://manpages.ubuntu.com/manpages/noble/man1/authbind.1.html) 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):

```bash
# 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:

```bash
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:

```bash
sudo su - coder
```

## Install Node.js via NVS

Use the [installation guide](https://github.com/jasongin/nvs?tab=readme-ov-file#mac-linux) 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:

```bash
nvs add node/24
nvs use node/24
nvs link node/24
```

## Setup

### Install the Server

```bash
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:

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

Otherwise, create a new one:

```bash
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:

```bash
coder-server config set coder_setup_path mycompany-coder-setup
```

### Install License

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

### Create Admin User

```bash
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):

```bash
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.

:::

```bash
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:

```bash
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](/admin/server-monitoring#reverse-proxy-notes) for operational notes.

### Start the Server

```bash
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:

```bash
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](/integrations/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:**
```bash
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:**
```bash
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](/integrations/ai-providers).

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:

```bash
coder-server start --daemon
```

Manage the daemon with:

```bash
# 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](https://pm2.keymetrics.io/) for process management.

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

#### Install PM2 Globally

```bash
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:

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

Otherwise start like this:

```bash
pm2 start --name coderflow coder-server -- start
```

#### View Logs

```bash
pm2 logs coderflow
```

#### Stop/Restart

```bash
pm2 stop coderflow
pm2 start coderflow
pm2 restart coderflow
```

#### Auto-start On System Boot

Save the PM2 process list to disk:

```bash
pm2 save
```

Generate a PM2 startup script:

```bash
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.
