Install & run Cordane

Overview

Cordane has two pieces:

• The hub — the control plane you open in a browser: the board, terminals, and live app previews.
• Workers — the machines where agents, dev servers, and your code actually run. A worker dials out to the hub, so it can be anywhere: your laptop, a VPS, a lab box behind a firewall.

You choose where the hub lives — we host it for you (managed cloud), or you run it yourself (self-host). Either way, your workers stay on your machines, so your code and secrets never leave your hardware.

Get started

Two ways to run the hub. Pick one, then connect a worker.

Self-host quickstart

You need a small Linux box with Docker and ports 80/443 open. Everything is prebuilt — there is no toolchain to install and nothing to compile.

1. Get the stack

git clone https://github.com/cordane/cordane.git
cd cordane/deploy
cp .env.example .env

2. Fill in five values

Open .env and set:

• EXTERNAL_URL and CONTROL_HOST — your hub’s URL and hostname.
• CORDANE_SECRET_KEY — generate with openssl rand -base64 32. Back this up; it is not in your database backups.
• CORDANE_GITHUB_CLIENT_ID / CORDANE_GITHUB_CLIENT_SECRET — a GitHub OAuth app, described below.

Point an A record at the box for your hostname (and a wildcard *. record if you want preview subdomains). On Cloudflare, keep DNS grey-cloud / DNS-only — Caddy terminates TLS itself and proxying would break the streaming connections.

3. Start it

docker compose up -d
docker compose logs -f cordane   # watch it boot

Open your EXTERNAL_URL and sign in with GitHub. The first account to sign in becomes the admin — do that yourself before sharing the address. Then connect a worker.

Wildcard certificates, backups to any S3-compatible bucket, a no-DNS-token “simple mode”, and how to use a DNS provider other than Cloudflare are all covered in deploy/README.md.

Connect a worker

A worker is any Linux or macOS machine you point Cordane at. This is identical whether your hub is managed or self-hosted.

1. Get a join token

In your hub, open Workers → Add worker and copy the one-time join command (it contains a crdjt_… token).

2. Install the worker

On the machine you want to enroll, install the cordane binary straight from your hub:

# installs the cordane binary for this OS/arch
curl -fsSL https://<your-hub>/install.sh | sh

3. Join it to your hub

cordane worker join https://<your-hub> --token crdjt_…

It enrolls and starts running immediately. To run it again later (e.g. after a reboot), use cordane worker run. Within a few seconds the worker shows up Online on your board.

What a worker needs

• OS: Linux or macOS.
• git — required (Cordane creates a git worktree per ticket).
• Docker — optional, only for running agents in a sandboxed container.
• Your agent CLIs — install the agents you use (e.g. claude, codex) on the worker. Their API keys live on the worker and never touch the hub.

Sign in with GitHub

Cordane authenticates only through GitHub — no passwords. The first person to sign in becomes the admin; after that you manage roles from Settings → Users.

Managed cloud: sign-in is already configured — just click Continue with GitHub.

Self-host operators register a GitHub OAuth app once:

• GitHub → Settings → Developer settings → OAuth Apps → New OAuth App.
• Set the Authorization callback URL to <your-hub-url>/api/v1/auth/github/callback.
• Give the hub the client ID and secret.

Using Cordane

Once a worker is online, here’s the loop:

• Create a project — point it at a git repo and give it setup + start scripts (install deps, run migrations, boot the dev server) plus a saved terminal layout.
• Start a ticket — Cordane cuts a fresh git worktree on its own branch from the latest main, reserves a block of ports, and runs your agent there.
• …or schedule it — give a ticket a start time and the hub starts it for you then, with nobody watching. You pick that time in your own time zone, so 07:00 means 07:00 where you are, whatever the hub runs on — the branch and the diff are waiting when you sit down.
• See it live — the dev server the agent starts is reachable through the hub’s reverse proxy on its own subdomain (auth on by default), so you click through the real change before merging.
• Review — the board shows the diff and how far the branch is ahead of / behind main; merge when you’re happy.
• Run many at once — every ticket is isolated in its own worktree and ports, so parallel tickets never collide.

Requirements

Worker (every setup)

• Linux or macOS, with git. Docker optional (sandboxed agents).
• Enough CPU/RAM/disk for your own builds and agent runs — the heavy work happens here, so size it to your project.

Hub (self-host)

• A small Linux VPS (1–2 vCPU) with Docker, ports 80/443 open.
• A domain for automatic wildcard HTTPS — or run on localhost for solo use.
• A GitHub OAuth app (see Sign in with GitHub).

Managed cloud has no hub requirements — we run it.

Updating & support

Keep a worker current with a one-liner — it self-updates from your hub to a compatible version:

cordane worker upgrade            # download & apply the update
cordane worker upgrade --check    # just check if one is available

Managed-cloud hubs are upgraded for you. To update a self-hosted hub, pull the current :stable images and restart:

docker compose pull && docker compose up -d

Your hub shows admins an “update available” banner under Settings → Version when a newer release is out. It never touches your box — you run the command. Set CORDANE_UPDATE_CHECK=off to disable the check.

Stuck? Open an issue on GitHub or email contact@cordane.ai.