# CoderFlow Server

CoderFlow is an enterprise platform that runs autonomous engineering agents inside your infrastructure. Instead of merely suggesting code, agents compile, test, validate, and fix legacy systems end-to-end — delivering verified, ready-to-commit results and 5–10x productivity gains.

CoderFlow:

- Submits coding tasks to AI agents (Claude, Codex, Gemini) running in isolated Docker containers
- Lets agents execute code, compile, test, and validate changes automatically
- Supports both headless execution (submit once, review results later) and interactive sessions (work within containers for guided work)
- Manages multi-repository workspaces with build pipelines and test suites
- Allows developers to review, iterate, and approve changes before committing

## Installation

### 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

> [!IMPORTANT]
> 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
```

#### 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, connect to the server's online documentation to continue with the installation (e.g., http://myserver:3000/docs/#/admin/installation?id=start-the-server).

## Git History Guardrail Tuning

Git History protects server and browser performance by applying diff guardrails for large commits.

- `GIT_HISTORY_MAX_DIFF_FILES` (default: `500`)
- `GIT_HISTORY_MAX_DIFF_BYTES` (default: `5242880`, 5MB)
- `GIT_HISTORY_MAX_SUMMARY_COMMAND_BUFFER` (default: `6291456`, 6MB)
- `GIT_HISTORY_MAX_DIFF_COMMAND_BUFFER` (default: `max(GIT_HISTORY_MAX_DIFF_BYTES + 1MB, 6MB)`)

Suggested tuning profiles:

- Conservative (default): `GIT_HISTORY_MAX_DIFF_FILES=500`, best for lowest server/UI load
- High-churn monorepo: `GIT_HISTORY_MAX_DIFF_FILES=2000`
- Very large commit workflows: `GIT_HISTORY_MAX_DIFF_FILES=6000`

If your repositories regularly include very large commits (for example 5000+ changed files), raise `GIT_HISTORY_MAX_DIFF_FILES` intentionally based on your infrastructure limits:

```bash
GIT_HISTORY_MAX_DIFF_FILES=6000
GIT_HISTORY_MAX_DIFF_BYTES=10485760
```

Higher limits can increase API payload size, response latency, and browser rendering load. Raise these values gradually and monitor server memory/CPU and Git History page responsiveness.
