Docs

Install & run Cordane

Cordane runs AI coding agents on machines you own, driven from one browser tab. This guide gets you from zero to a worker on your board.

Cordane is in private beta. Managed cloud and self-hosting are rolling out to testers — request access and we’ll get you started. Connecting a worker (below) is the same in every setup.

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.

Recommended in beta

Managed cloud

We run the hub for you at your-team.cordane.app — TLS, backups, and upgrades handled. Nothing to install for the hub.

1. Request access → we provision your hub.
2. Open it and sign in with GitHub.
3. Connect a worker.

Private beta

Self-host

Run the hub on your own box or a cheap VPS. Public install packages are on the way — for now, request access and we’ll set you up.

You’ll want: a small Linux VPS with Docker, a domain for automatic HTTPS (or localhost for solo use), and a GitHub OAuth app (below).

Self-host packages aren’t public yet. During private beta we set self-hosters up directly. If you need self-host access, mention it when you request access.

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:

on your worker machine

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

3. Join it to your hub

enroll + start

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.

Workers dial out to the hub over a single outbound connection — no inbound ports, no VPN, no SSH config. Run one inside a corporate firewall and nothing needs opening.

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.
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. Self-host install packages are in private beta.

Updating & support

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

on your worker machine

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

Managed-cloud hubs are upgraded for you. Self-hosted hub updates ship with your deployment.

Stuck, or want self-host access? Request beta access or email contact@cordane.ai.