remote-runner

<!-- GENERATED from docs/api/remote-runner.md by scripts/build-agent-skill.mjs. Do not edit. -->

Remote runner — `RUNNER=REMOTE`

> Builds without a local Docker. A **runner** is one toolchain image this crossbind pins plus a small server that ships inside the CLI. With `RUNNER=REMOTE` and a runner's address and token set, every toolchain step bound for its image (compilers, CMake, SWIG, the linker, cargo, conan) runs on the runner instead of a local container; crossbind neither pulls that image nor starts containers. Your JavaScript never leaves the machine.

Quick start

crossbind runner start                # the web image on port 8787
# crossbind: crossbind-local-runner-web is running. Build against it with:
#   crossbind config set RUNNER REMOTE
#   crossbind config set REMOTE_URL_WEB http://127.0.0.1:8787
#   export CROSSBIND_TOKEN_WEB=<token>

crossbind config set RUNNER REMOTE
crossbind config set REMOTE_URL_WEB http://127.0.0.1:8787
export CROSSBIND_TOKEN_WEB=<token>
crossbind build -p wasm
# crossbind: web steps run on the runner at http://127.0.0.1:8787 (RUNNER=REMOTE from ~/.crossbind.json, address from REMOTE_URL_WEB in ~/.crossbind.json).

crossbind config set RUNNER DOCKER_RUN   # back to the local Docker
crossbind runner delete

For a single build, the environment does the same without changing `~/.crossbind.json`:

CROSSBIND_RUNNER=REMOTE CROSSBIND_REMOTE_URL_WEB=http://127.0.0.1:8787 CROSSBIND_TOKEN_WEB=<token> crossbind build -p wasm

Build on crossbind cloud

Without a runner of your own, sign in and build on crossbind cloud:

crossbind login                       # shows a code to enter on github.com
crossbind config set RUNNER REMOTE
crossbind build -p wasm
# crossbind: web steps run on the runner at https://api.crossbind.dev/runner/web (RUNNER=REMOTE from ~/.crossbind.json, address from crossbind login as octocat).
crossbind usage                       # this month's build minutes, by image

• Under `REMOTE`, a machine that names no runner address (no `REMOTE_URL` or `REMOTE_URL_<IMAGE>`, in `~/.crossbind.json` or the environment) builds every image on crossbind cloud once signed in. Naming any runner keeps every image off the cloud, so your sources go only where you send them. Every image has a cloud runner: web, android, linux and windows.
• A signed-in GitHub account has 60 build minutes a month. A minute counts while your runner is up: from a build's first step until a minute after its last, so the steps of one build share a warm runner. `crossbind usage` shows them by image; they come back on the 1st (UTC). Once they are spent, steps stop with a message saying so; `CROSSBIND_RUNNER=DOCKER_RUN` builds in the local Docker. crossbind cloud also caps the time of everyone together, per day and per month; when either is spent, steps stop with a message saying when time comes back.
• Each account's runner of each image is a Firecracker microVM of its own, stopped and wiped a minute after its last step: nothing passes between accounts, and the first step after a pause uploads its inputs again.
• A cloud runner reaches crates.io, ConanCenter and GitHub, nothing else, and only to download: a Conan recipe whose sources live on another host fails there, and so does a build step that pushes or uploads.
• crossbind cloud runs the toolchain images of the current crossbind release; a build from an older crossbind stops with `toolchain mismatch` until crossbind is upgraded.
• `crossbind login` asks GitHub for no permission and turns away GitHub accounts younger than 30 days. Its token is kept for that cloud address in `~/.crossbind/credentials.json`, readable by you only, and stops working after 90 days unused. `crossbind logout` revokes it, `--all` the token of every machine signed in to the account. `CLOUD_URL` in `~/.crossbind.json`, or `CROSSBIND_CLOUD_URL`, names another cloud.
• crossbind cloud keeps your GitHub id and name, when you signed in, your tokens' hashes and how long your runners were up; no email, and none of your sources once the runner stops. `crossbind account delete --yes` deletes the account and signs out every machine; [crossbind.dev/privacy](https://crossbind.dev/privacy/) says what stays and for how long.

`runner start` runs the runner in the local Docker, which is how you try it out or turn one machine into the build machine of others (`--host 0.0.0.0`, `--port`, `--token`; the token defaults to `$CROSSBIND_RUNNER_TOKEN`, else a new one). `--role android|linux|windows` starts the other images, on ports 8788, 8789 and 8790, so the runners one build needs fit on one machine. Its container is `crossbind-local-runner-<role>`; `runner delete` removes it, and one an older crossbind started as `crossbind-runner-<role>`. To run a runner elsewhere, deploy it.

Deploy a runner

crossbind runner init fly             # or cloudflare, cloudrun, azure; --role android|linux|windows; --dir <folder>

`runner init` writes a folder and prints its deploy steps with a new token. For Fly and Cloudflare its `Dockerfile` starts `FROM` the image this crossbind pins and copies the runner in; Cloud Run and Azure deploy that image straight from GHCR and take the runner from `env.yaml` or `containerapp.yaml`. No runner image is published either way.

| Platform | `runner init` writes | Deploy | URL | |---|---|---|---| | Fly.io | `Dockerfile`, `fly.toml`: one `performance-4x` machine with 16 GB that stops when idle and starts on the next request | `fly launch --copy-config --no-deploy --ha=false`, `fly secrets set CROSSBIND_RUNNER_TOKEN=<token>`, `fly deploy --ha=false` | `https://crossbind-runner-<role>-<random>.fly.dev` | | Cloudflare Containers | `Dockerfile`, `wrangler.jsonc`: one `standard-4` container, `src/worker.js`: a Worker that checks the token, starts the container and forwards to it | `npx wrangler deploy` (builds the image with the local Docker), `npx wrangler secret put CROSSBIND_RUNNER_TOKEN` | `https://c