Development Setup

OpenFlows is a Rust project that runs on top of a self-hosted Coder deployment. The fastest way to get productive is to build from source and bring up the local Coder and Redis stack with Docker Compose. Once the stack is running, you can iterate in either local mode (Git worktrees, in-memory state) or Coder mode (ephemeral workspaces, Redis-backed SharedStore).

This guide covers the prerequisites, the build process, the Docker Compose runtime, the update-binaries.sh script, and the day-to-day developer workflow. Follow it in order; the commands later assume the earlier steps are complete.

Prerequisites

The project is tested on Linux and macOS. Windows is supported via WSL2. You do not need a running Coder deployment to start - the Docker Compose file in the repository includes one.

Build from Source

The repository is a Cargo workspace. The main binary lives in the openflows crate and depends on the core orchestration library. Building the entire workspace is the best way to verify that your environment is correct.

# Clone the repository
git clone https://github.com/openflows/openflows.git
cd openflows

# Verify the Rust toolchain
rustc --version   # should be >= 1.70.0
cargo --version   # should be >= 1.70.0

# Build the full workspace
cargo build

# For a faster dev build, skip optimization
cargo build

A full build fetches dependencies, compiles the PocketFlow engine, the Redis SharedStore driver, the Coder transport, the GitHub MCP client, and the TUI. On a modern machine with a warm cache, this takes under two minutes. On the first build, expect five to ten minutes depending on network speed.

Bootstrap the Configuration

After the workspace builds, run the bootstrap command to create the initial tenant configuration, the .env file, and the default registry.json. This is the same entry point used by the setup wizard in production.

cargo run -p openflows --bin openflows -- bootstrap

The bootstrap command will ask for your Coder URL, your Redis URL, and the path to the registry file. In local mode you can accept the defaults. In Coder mode, point the Coder URL to the Compose service at http://localhost:3000 and Redis to redis://localhost:6379.

Docker Compose for Local Coder and Redis

The repository includes a docker-compose.dev.yml file that brings up the dependencies needed for Coder mode. It is not required for local mode, but it is the only way to run integration tests that exercise the full workspace lifecycle.

# Start the runtime stack
docker compose -f docker-compose.dev.yml up -d

# Verify Coder is healthy
open http://localhost:3000
# or
curl -s http://localhost:3000/healthz

# Verify Redis is listening
redis-cli -h localhost -p 6379 ping
# → PONG

The first Coder startup will prompt you to create the initial admin user. Complete that setup, then create a Coder template from the coder-template/ directory. The template installs the agent CLI module and mounts the repositories that the agents will work on.

Update Binaries with update-binaries.sh

The update-binaries.sh script builds release binaries and copies them into the paths expected by the Coder template and the integration tests. It is the canonical way to publish your local build to the runtime environment.

# Build and install binaries into the runtime paths
./update-binaries.sh

# The script outputs:
# - target/release/openflows
# - target/release/openflows-setup
# - target/release/openflows-tui
# and copies them to the Coder template's bin/ directory for workspace provisioning.

Run this script after every meaningful change before you run integration tests or provision a Coder workspace. The Coder template does not build from source; it expects the binaries to be prebuilt and available in the shared mount.

Local vs Coder Mode

OpenFlows supports two developer modes. The mode is selected by the workspace_provider field in registry.json and by whether Redis is configured. There is no other toggle.

// Local mode: worktrees on disk, in-memory store
{
  "workspace_provider": "local",
  "agents": { "forge": { "instances": 1 } }
}

// Coder mode: ephemeral workspaces, Redis-backed store
{
  "workspace_provider": "coder",
  "coder_module": "claude-code",
  "agents": { "forge": { "instances": 2 } }
}

In local mode, FORGE uses Git worktrees on the developer machine. It is fast and requires no Docker, but it does not exercise workspace provisioning, Coder external auth, or the Coder AI Gateway. Use it for unit tests, skill development, and registry tweaks.

In Coder mode, every agent gets a fresh Coder workspace. This is the production shape and the only mode that validates the full lifecycle: provision, plan, implement, review, PR, CI, merge, and teardown. Use it for integration tests, end-to-end validation, and any change that touches WorkspaceTransport or the Coder API.

Day-to-Day Dev Workflow

A typical change looks like this. Adjust the exact test commands based on the crate you are touching, but never skip the test step before opening a PR.

1. Start Docker Compose if you will run Coder mode or integration tests.
2. Check out a branch named forge-{slot}/{ticket-id}.
3. Make the change and add or update tests.
4. Run unit tests: cargo test -p openflows-core or cargo test --workspace.
5. Run ./update-binaries.sh if you are testing Coder mode.
6. Run integration tests against the local Coder deployment.
7. Run cargo fmt and cargo clippy --workspace to catch style issues.
8. Commit with a conventional commit message and push.

Adding a Tenant Repository

To test against a real repository, add it to a tenant with the CLI. The tenant owns the GitHub integration, and one tenant can watch multiple repositories.

cargo run -p openflows --bin openflows -- tenant add owner/repo --name my-team

# Verify the tenant appears in the registry
cargo run -p openflows --bin openflows -- tenant list

Common Issues

• Rust version too old - Run rustup update and rebuild.
• Coder health check fails - Wait for the database migrations to finish; first boot can take 30–60 seconds.
• Redis connection refused - Ensure the redis container is running and the port is not bound by another service.
• Binary not found in workspace - Run ./update-binaries.sh after every build.
• GitHub auth fails - Verify the OAuth App callback URL, the Coder external auth provider configuration, and that the user has authorized the app.