Skip to content

Installing and signing in

cawdev is the whole interface from a machine — one binary, plain Node, zero dependencies. It is both the terminal you watch sessions in and the daemon that runs them; typing cawdev finds a daemon on this machine or starts one.

Terminal window
npm install -g cawdev-cli
cawdev

The package is cawdev-cli on npm; it needs Node 20 or later and installs one command, cawdev. Working from a checkout instead? npm install -g ./tools from the repository root installs the same thing.

The first time, on a machine with nothing set up

Section titled “The first time, on a machine with nothing set up”

Nothing is created until every question is answered — a setup abandoned halfway leaves no token on the tokens page and no config pointing at half a machine. That is what makes running cawdev again the whole recovery procedure.

  1. Sign in through the browser. No password reaches this process — the CLI asks the platform for a code, opens the sign-in page, and waits for you to approve it there. A password belongs on a page a browser has told you the origin of, not in a full-screen terminal app. If you have added a passkey, the sign-in page offers it, and this sign-in uses it too.

  2. Choose which projects this machine should serve. Only ones where you may run agents are offered. runner:operate needs the Run agents privilege, so a project you can only see would fail the mint afterwards. The list ends with Create a new project on cawdev: a name, a git URL (or an existing checkout, whose origin is then used) and a path. It clones first and creates the project only at the final confirmation, so a clone that fails leaves nothing on the platform.

  3. Say where checkouts should live. One question, not one per project — ~/cawdev unless you say otherwise. It is a picker: the folder beside checkouts this machine already serves, the default, or a path you type with tab completing directories the way a shell does. Each row says what is there already (new folder, will clone here, already a checkout of cawdev).

  4. It clones what isn’t already there, in the foreground, under your own git credentials. The platform never holds a git credential; it only supplies the URL a project was created with.

  5. Say which coding agents are on this machine (Claude Code, Antigravity CLI, Codex CLI; see Agents) and confirm each is signed in. This is the one thing cawdev cannot do for you — a runner whose agent isn’t signed in boots fine and fails every run, which is a worse way to find out than a question.

  6. It mints its own runner:operate token, scoped to exactly the projects you chose, and writes the config. Nothing is typed or pasted. The token is checked against your access at every call, so it stops working if you lose the Run agents privilege on a project.

Run cawdev --setup any time to do this again — adding a project to a machine that already has one is the ordinary reason. For one small change, cawdev config add-project does only that. See The config file. A daemon already running keeps the config it booted with, so it’s told to restart rather than left looking like it took the change.

On a machine that already has a config but no token

Section titled “On a machine that already has a config but no token”

If a runner.config.json exists — checked in, copied from another machine — but holds no token, cawdev skips straight to signing in and minting one for the projects the config already names. Nothing else is asked, because the config already answers it.

Three files under ~/.cawdev/, each 0600, each answering a different question:

File What it holds Why it’s separate
session.json Your browser session — the cookies from signing in This is you. No password, and the daemon’s own token is never in here.
token.json This machine’s runner:operate token, keyed by URL This is what the machine may do. Revoking it in the console stops the machine without touching your session.
runner.config.json Which projects, which checkouts, which agents The one file people copy between machines or check in — and the one that must never carry a credential.

A token can also live in the config — that’s the shape --setup wrote before this three-file split existed, and it’s still read first if present. It’s not how a fresh setup writes one, because a config is the kind of file people keep beside their code and commit.

cawdev the runner here, starting one if there is none
cawdev --runner <name> when this machine runs more than one
cawdev --url <url> which cawdev to sign in to (or CAWDEV_URL)
cawdev --config <path> the runner config to start a daemon from
cawdev --no-start attach only; never launch a daemon
cawdev --watch-only do not sign in; watch without being able to act
cawdev --leave-running leave the daemon running when you quit
cawdev --setup walk the first-machine questions again
cawdev --version this CLI's version, and the platform's

--no-start attaches to a daemon that is already there and refuses to launch one. --watch-only never opens a browser: everything on the socket is readable without signing in, and watching is the larger half of what the terminal is for. Anything that changes something (answering, cancelling, deciding a permission) goes to the platform as you, so it needs a sign-in.

Terminal window
cawdev --version # this CLI's version, and the platform's, needing no sign-in
cawdev config show # this machine's config, token redacted

cawdev warns on startup if this CLI and the platform it’s talking to have drifted apart, and refuses to start the daemon if this CLI is below the platform’s stated minimum.