# RaftRun docs, in full > Every page of the RaftRun docs as Markdown, in reading order. The index is https://raftrun.com/llms.txt. --- # Introduction > What RaftRun runs for you: GitHub Actions jobs, and Docker hosts for your laptop and coding agents. Source: https://raftrun.com/docs RaftRun gives your team machines for two jobs. **GitHub Actions runners** run your workflow jobs on a fresh Ubuntu machine each, billed by the second. **Docker hosts** give each person a remote Docker engine for their laptop, their CI and their coding agents, which starts when they connect and stops when they leave. Both live in one workspace, with one plan, one invoice and one set of people. ## GitHub Actions runners Install the RaftRun GitHub App on your organisation, then change a job's `runs-on` line. Nothing else in the workflow changes. `.github/workflows/ci.yml` ```diff jobs: build: - runs-on: ubuntu-latest + runs-on: raft-ubuntu-24.04 ``` - Each job gets its own Ubuntu 24.04 x64 machine with root and Docker, from half a vCPU to 16. It is deleted when the job ends. - Billing starts when the machine picks up the job and stops when the job ends. Queueing and start-up are free. - A cache for `actions/cache`, outbound traffic rules, limits, log search and analytics come with every plan. ## Docker hosts Point `docker` at your host and builds, containers and compose stacks run there instead of on your laptop. It reaches the host over SSH, so there is nothing to install beyond Docker itself. `your terminal` ```sh export DOCKER_HOST=ssh://my-laptop@ssh.raftrun.com:2222 docker compose up -d ``` - A host starts on the first command and stops after 10 minutes without a connection. Stopped, it costs nothing and keeps its images and volumes. - Published ports are private. You open them on your own machine through an SSH tunnel, and the dashboard shows which services are running and healthy. - Give each project folder its own host, so projects, and the coding agents working in them, never share containers or ports. ## Where to start - [Quickstart](https://raftrun.com/docs/quickstart): Sign in, connect GitHub, change one line, and watch your first job run. - [Get a Docker host](https://raftrun.com/docs/docker): A remote Docker engine that starts when you connect and stops when you leave. - [Runner sizes](https://raftrun.com/docs/actions/runners): The runs-on labels, what each machine has, and how to pick a size. - [Limitations](https://raftrun.com/docs/limitations): What RaftRun doesn't do yet. Check this before you move a workflow. --- # Quickstart > Sign in, connect GitHub, change one line, and watch your first job run. Source: https://raftrun.com/docs/quickstart About five minutes from nothing to your first job on RaftRun. You need a Google account and admin rights on the GitHub organisation or account whose repositories you want to run. ### 1. Sign in Open the [dashboard](https://raftrun.com/overview) and sign in with Google. Your first sign-in creates a workspace with you as its admin. If someone invited you, open their invitation link instead and you join their workspace. ### 2. Connect GitHub In **Settings**, press **Connect a GitHub account**. GitHub asks where to install the RaftRun app: choose the organisation, and all repositories or just the ones you pick. You come back to Settings with the account listed. > The app reads workflow job events and registers runners. A job that doesn't ask for a RaftRun label keeps running where it does today, so installing it changes nothing on its own. ### 3. Choose a plan On **Plan & billing**, pick a plan for the people in your workspace. Machine time is billed per minute on the same invoice, and a monthly spending cap of $50 is on by default. See [Plans and billing](https://raftrun.com/docs/workspace/billing). ### 4. Change one line Pick a job and point its `runs-on` at a RaftRun label. `.github/workflows/ci.yml` ```diff jobs: test: - runs-on: ubuntu-latest + runs-on: raft-ubuntu-24.04 steps: - uses: actions/checkout@v4 - run: make test ``` `raft-ubuntu-24.04` is 2 vCPU and 4 GB. Need more? `raft-ubuntu-24.04-4`, `-8` and `-16` are bigger; [Runner sizes](https://raftrun.com/docs/actions/runners) lists them all. ### 5. Push and watch Push the change. The job shows on GitHub as usual, and on the **Jobs** page of the dashboard with its size, time in the queue, duration, CPU and memory, steps and logs. A machine usually picks the job up well within a minute. ## A Docker host too On **Docker hosts**, create one with a name and your SSH public key, then point Docker at it. The full walk-through is in [Get a Docker host](https://raftrun.com/docs/docker). `your terminal` ```sh ssh-keyscan -p 2222 ssh.raftrun.com >> ~/.ssh/known_hosts export DOCKER_HOST=ssh://my-laptop@ssh.raftrun.com:2222 docker run --rm hello-world ``` ## Next - [Move a workflow](https://raftrun.com/docs/actions/migrate): What changes, what stays the same, and how to move jobs over safely. - [Cache](https://raftrun.com/docs/actions/cache): Make actions/cache save and restore on RaftRun, with your own retention and storage. - [Run services](https://raftrun.com/docs/docker/services): Run a compose stack on the host and see which services are up, healthy and listening. - [Team and roles](https://raftrun.com/docs/workspace/team): Invite people, choose what each may do, and set their Docker host rules. --- # Runner sizes > The runs-on labels, what each machine has, and how to pick a size. Source: https://raftrun.com/docs/actions/runners Put one of these labels in a job's `runs-on`. Every size runs Ubuntu 24.04 on x64, with Docker. Jobs run as root. | Label | vCPU | Memory | Disk | Per minute | Per hour | | --- | --- | --- | --- | --- | --- | | `raft-ubuntu-24.04-xsmall` | 0.5 | 1 GB | 20 GB | $0.000075 | $0.0045 | | `raft-ubuntu-24.04-small` | 1 | 2 GB | 20 GB | $0.00015 | $0.009 | | `raft-ubuntu-24.04` | 2 | 4 GB | 20 GB | $0.0003 | $0.018 | | `raft-ubuntu-24.04-4` | 4 | 8 GB | 40 GB | $0.0006 | $0.036 | | `raft-ubuntu-24.04-8` | 8 | 16 GB | 100 GB | $0.0012 | $0.072 | | `raft-ubuntu-24.04-16` | 16 | 32 GB | 200 GB | $0.003333 | $0.20 | `raft-ubuntu-latest` is an alias for `raft-ubuntu-24.04`, and `raft-ubuntu-latest-4` and the others work the same way. ## Pick a size - **Lint, small tests, deploy scripts:** `raft-ubuntu-24.04-xsmall` (half a vCPU, 1 GB) or `raft-ubuntu-24.04-small` (1 vCPU, 2 GB). A job that mostly waits on the network gains nothing from more cores. - **Builds and test suites:** `raft-ubuntu-24.04-4` or `-8`. Compilers and test runners that use every core finish about twice as fast for each doubling, so the cost stays close to the same. - **Big Docker builds or large images:** `-4` or larger, for the disk. The two smallest have 20 GB. - **Not sure:** start with `raft-ubuntu-24.04`. After a few runs, [Analytics](https://raftrun.com/docs/actions/insights#size-suggestions) tells you which jobs ran out of memory and should go up, and which idled and can go down. ## What is on the machine A clean Ubuntu 24.04 with Docker, git, curl and the GitHub Actions runner. It is not GitHub's runner image, which preinstalls dozens of languages and tools. Install what a job needs with the usual setup actions; they download in seconds and, with [the cache](https://raftrun.com/docs/actions/cache) on, restore dependencies from the last run. `steps` ```sh steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 22 - run: npm ci && npm test ``` Each machine runs one job and is then deleted. Nothing carries over between jobs, including from one job of a matrix to the next. ## Spread a suite across machines A matrix runs each entry on its own machine at once. Four 4 vCPU shards often finish sooner, for the same cost, than one 16 vCPU job. `.github/workflows/test.yml` ```yaml jobs: test: strategy: matrix: shard: [1, 2, 3, 4] runs-on: raft-ubuntu-24.04-4 steps: - uses: actions/checkout@v4 - run: npm test -- --shard=${{ matrix.shard }}/4 ``` How many run at once is capped by your workspace's concurrency limit; the rest wait in the queue. See [Limits and timeouts](https://raftrun.com/docs/actions/limits). ## Billing By the second, from when a machine picks up the job until the job ends, with no one-minute minimum. Time in the queue and while the machine starts are free. A 3 minute 20 second job on `raft-ubuntu-24.04-4` costs 200 seconds at its per-minute price. --- # Move a workflow > What changes, what stays the same, and how to move jobs over safely. Source: https://raftrun.com/docs/actions/migrate A job moves to RaftRun when its `runs-on` names a RaftRun label. Steps, actions, secrets, environments, artifacts and the GitHub checks UI all stay the same; GitHub still runs the workflow, RaftRun only provides the machine. ## Move one workflow first ### 1. Check the limitations Windows, macOS, Arm64 and GPU jobs can't move yet, and neither can jobs that need GitHub's preinstalled tools without installing them. The full list is on [Limitations](https://raftrun.com/docs/limitations). ### 2. Change runs-on in one workflow Pick a busy workflow with a clear pass or fail, such as tests on pull requests. Match the size to what it uses today: `ubuntu-latest` on GitHub is 4 vCPU and 16 GB for public repositories and 2 vCPU and 8 GB for private ones. ### 3. Compare After a day, **Analytics** shows its durations and failure rate, and suggests a size from the CPU and memory it really used. Then move the next workflow. ## Switch with a variable To move many workflows, or to move back quickly, read the label from a repository or organisation variable. Set `RUNNER` to `raft-ubuntu-24.04` under **Settings → Secrets and variables → Actions → Variables** on GitHub, and clear it to go back. `.github/workflows/ci.yml` ```yaml jobs: build: runs-on: ${{ vars.RUNNER || 'ubuntu-latest' }} ``` ## Service containers and container jobs Both work as they do on GitHub, because every machine has Docker. Service containers start next to the job: `.github/workflows/test.yml` ```yaml jobs: test: runs-on: raft-ubuntu-24.04-4 timeout-minutes: 20 services: postgres: image: postgres:17 env: POSTGRES_PASSWORD: postgres ports: ["5432:5432"] steps: - uses: actions/checkout@v4 - run: make test ``` A job can run inside a container image too. The cache works from inside it. `.github/workflows/build.yml` ```yaml jobs: build: runs-on: raft-ubuntu-24.04 container: node:22 steps: - uses: actions/checkout@v4 - run: npm ci && npm run build ``` ## Things that behave differently - **Tools are not preinstalled.** Add `actions/setup-node`, `setup-python`, `setup-go` and the like. See [what is on the machine](https://raftrun.com/docs/actions/runners). - **Set `timeout-minutes`.** GitHub stops a job at its timeout and RaftRun deletes the machine at once. Without one, a hung job runs until your workspace's longest job. See [Limits and timeouts](https://raftrun.com/docs/actions/limits). - **No fixed IP addresses.** If a deploy target allowlists GitHub's IP ranges, it won't recognise RaftRun machines. - **The cache is opt-in.** Until an admin turns it on, `actions/cache` uses GitHub's cache as before. See [Cache](https://raftrun.com/docs/actions/cache). - **Jobs queue past your concurrency limit.** New workspaces start at 4 jobs at once for their first 30 days on RaftRun's machines. --- # Cache > Make actions/cache save and restore on RaftRun, with your own retention and storage. Source: https://raftrun.com/docs/actions/cache With the cache on, `actions/cache`, and the setup actions that use it, save to and restore from RaftRun's storage instead of GitHub's. Your workflows don't change: the same steps, keys and restore keys work as they are. > **Beta** > > The cache is off until an admin turns it on. If a restore misbehaves, turn it off and jobs go back to GitHub's cache on their next run. ## Turn it on In the dashboard, open **Settings → Cache**, switch on **Accelerated cache**, and save. The next job on a RaftRun machine uses it. `.github/workflows/test.yml` ```yaml steps: - uses: actions/checkout@v4 - uses: actions/cache@v4 with: path: ~/.cargo/registry key: cargo-${{ hashFiles('Cargo.lock') }} restore-keys: cargo- - run: cargo test ``` Setup actions with a `cache` option go through the same cache: `steps` ```sh steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 22 cache: npm ``` ## How entries are shared - **By repository.** Every branch and pull request of a repository sees the same entries. GitHub limits a branch to its own and its base branch's entries; RaftRun does not. - **Exact key first, then restore keys,** newest match first, as on GitHub. - **Entries are never overwritten.** Saving a key that already exists is skipped, so put a hash of your lockfile in the key. > **Shared across branches** > > A pull request's branch can restore what the default branch saved, and the default branch can restore what a pull request saved. Don't cache anything secret, and don't trust a cache to be clean in a release build. ## Storage and retention - Entries unused for the retention period are deleted. It is 14 days unless you change it in **Settings → Cache**. - On RaftRun's storage you get your plan's allowance (Solo 10 GB, Team 50 GB, Business 150 GB), plus any extra you buy at $10 a month per 100 GB. When it is full, the least recently used entries are deleted. Nothing is billed by surprise. - The **Cache** page lists entries by repository, with their size and when they were last used. Clear a whole repository or one entry there. ## Rust builds RaftRun machines can cache Rust builds for you. It works through [mbx](https://mr-boxington.jdx.dev), which stores each crate's compiled output and restores it when the same crate is built again with the same inputs, on any machine. Turn on **Cache Rust builds** in [Settings](https://raftrun.com/settings): your machines then come with mbx and Rust installed, and plain `cargo` builds through the cache. Your workflows stay as they are. `.github/workflows/test.yml` ```yaml steps: - uses: actions/checkout@v4 - uses: dtolnay/rust-toolchain@stable - run: cargo test --workspace ``` - **By repository.** Each repository has its own cache. No other repository or workspace can read it or write to it. - **Written from pushes to the default branch.** Only a push to the repository's default branch saves outputs; pull requests and other runs read without writing. - **The first build of a repository fills it.** mbx finds outputs through what it recorded for your `Cargo.lock`, so the first build compiles everything, and later ones, on any machine, restore what didn't change. - **Kept for 30 days, within your size limit.** Outputs are removed 30 days after they were saved, and the oldest go first once the workspace passes the size you set. The next push to the default branch saves them again. - **A cache problem never fails a build.** If the cache can't be reached, cargo compiles everything itself. - **Your own AWS credentials come first.** The machine hands mbx its key the way EC2 hands out an instance role's. Once a step exports AWS credentials, as `aws-actions/configure-aws-credentials` does, mbx uses those instead, and later steps build without the cache. Build before that step, or in a separate job. > **Release builds** > > Build what you publish without the cache: run `~/.cargo/bin/cargo build --release`, which goes straight to Cargo. ## Use your own bucket Keep the cache in any S3-compatible bucket you own, such as AWS S3, Cloudflare R2, Tigris or Backblaze B2. It costs nothing on RaftRun's side and the size cap is yours to set. ### 1. Make a key for that bucket only It needs to read, write and delete objects in the bucket, and nothing else. ### 2. Connect it On the **Cache** page, press **Use your own bucket** and give the endpoint, region, bucket and key. RaftRun writes, reads and deletes a test object before saving, then stores the secret encrypted. New entries go to your bucket from then on. Entries already saved stay usable until they expire. --- # Outbound traffic > Allow or deny the hosts and networks your jobs may reach. Source: https://raftrun.com/docs/actions/egress Egress rules decide which addresses a job's machine may connect to. Use them to block a package mirror you don't trust, or to lock jobs down to GitHub and a short list of hosts. An admin sets them in **Settings → Egress rules**, and they apply to every job in the workspace from its next start. ## How a connection is decided Each outgoing connection is checked in this order, and the first match wins: 1. Loopback, the machine talking to itself, is always allowed. 2. Your **deny** rules. 3. Your **allow** rules. 4. The **default policy**: allow or deny. With the default set to deny, GitHub (including `ghcr.io` and the Actions services), RaftRun itself and the cache's storage stay reachable, so jobs can still check out code, report progress and use the cache. ## Rule types | Type | Example | Matches | | --- | --- | --- | | Hostname | `registry.npmjs.org` | The addresses that name resolves to when the job starts. Subdomains are separate names. | | IP address | `203.0.113.10` | That one address. | | CIDR block | `10.0.0.0/8` | Every address in the range. | ## Allow only what jobs need ### 1. Add allow rules first For example `registry.npmjs.org`, `pypi.org`, `files.pythonhosted.org`, `registry-1.docker.io`, and your deploy target. ### 2. Set the default to deny Save it. Jobs that start from now on get the new rules; running jobs keep theirs. ### 3. Watch the next runs A blocked connection shows in the job's log as a timeout or "connection refused". Search the logs for it and add the host that was missing. ## What rules don't do - **They cover IPv4.** With a deny default, IPv6 is blocked outright. - **Hostnames are resolved once, at the start of the job.** A service whose addresses change from minute to minute, such as some CDNs, may need a CIDR rule instead. - **They are a guard rail, not a sandbox.** A job runs as root and can change the machine's firewall. They stop mistakes and unwanted dependencies, not a hostile workflow. --- # Limits and timeouts > Jobs at once, the longest a job may run, and the monthly spending cap. Source: https://raftrun.com/docs/actions/limits Three limits keep a stuck job or a busy day from turning into a surprise bill. Admins set them; jobs past a limit wait, they don't fail. | Limit | Where | Default | What happens | | --- | --- | --- | --- | | Jobs at once | Settings → Limits | 20 | Further jobs wait in the queue until one finishes. | | Longest job | Settings → Limits | 60 minutes | The job's machine is deleted, finished or not. | | Monthly spending cap | Plan & billing | $50 | New jobs wait once this month's machine time reaches it. | A workspace new to RaftRun's machines can run 4 jobs at once for its first 30 days, whatever the setting says. Write to us if you need more sooner. ## Timeouts When a job reaches its `timeout-minutes`, GitHub stops it, and RaftRun deletes its machine within seconds. The workspace's longest job is the outer limit: a machine is deleted then, whatever the job set, also when GitHub never reports the job finished. `.github/workflows/e2e.yml` ```yaml jobs: e2e: runs-on: raft-ubuntu-24.04-4 timeout-minutes: 25 steps: - uses: actions/checkout@v4 - run: npm run e2e ``` Set `timeout-minutes` on every job, close to how long it really takes. GitHub's own default is 6 hours, and a hung test costs machine time until something stops it. ## The spending cap - It counts jobs and Docker hosts on RaftRun's machines this calendar month. The plan itself is not counted. - When it is reached, running jobs finish and new ones wait in the queue. Raise the cap, or wait for the month to turn, and they start. - 0 means no cap. --- # Jobs, logs and analytics > Follow jobs live, search logs, and find the jobs that are slow, failing or the wrong size. Source: https://raftrun.com/docs/actions/insights Every job that asks for a RaftRun label is tracked from the moment GitHub queues it. The dashboard shows it live, keeps its logs for 30 days, and adds it to analytics when it finishes. ## Jobs The **Jobs** page lists the latest jobs across every connected repository, searchable and filterable by status. Open one to see its size, time in the queue, duration, timeout, branch and commit, the machine it ran on, a CPU and memory chart sampled every 5 seconds, its steps with their timings, and its log. A job that is waiting says why, for example that the workspace is at its jobs-at-once limit or its spending cap. Waiting jobs start by themselves once the reason clears. ## Search logs **Logs** searches the log lines of every job from the last 30 days by keyword. Use it to find which runs hit a flaky test, a timeout or a failed download, and jump from a line to its job. ## Analytics Filter by repository, workflow and time range. Charts and tables cover: - jobs completed per day, and the share that failed; - average and 95th percentile duration per day; - the five slowest jobs, and the jobs that fail most; - average CPU against peak memory, one dot per job, to spot the wrong size at a glance. The slowest jobs, the failures and the sizing table export as CSV or JSON. ## Size suggestions Once a job has run 3 times, analytics compares what it used with what it asked for: | Suggestion | When | | --- | --- | | Size up | Its memory peaked at 90% or more, or its CPU averaged 85% or more. Running out of memory is the usual cause of jobs killed with exit code 137. | | Size down | Its CPU never passed 50% and its memory stayed under 40%. One size down halves memory, so it needs that headroom. | Change the job's `runs-on` to the suggested label; the next runs show whether it helped. ## Usage **Usage** shows the minutes billed this month, per day and by size, and what they cost. Minutes are counted by the second with no one-minute minimum. Each Docker host shows its own minutes and cost for the month on the Docker hosts page. --- # Get a Docker host > A remote Docker engine that starts when you connect and stops when you leave. Source: https://raftrun.com/docs/docker A Docker host is a Linux machine running Docker, reached from your `docker` CLI over SSH. Builds, images, containers and volumes live there, so your laptop stays cool and its disk stays free. It starts when you run a command and stops when you've been away for 10 minutes. You need Docker's CLI on your machine (Docker Desktop, OrbStack, or the plain `docker` client) and an SSH key. ### 1. Have an SSH key The host lets in only the SSH keys registered for it. `your terminal` ```sh # skip if ~/.ssh/id_ed25519.pub already exists ssh-keygen -t ed25519 cat ~/.ssh/id_ed25519.pub ``` ### 2. Create the host In the dashboard, open **Docker hosts** and fill in **Create a Docker host**: a name, a size, and the public key you just printed. The name becomes the user in its address, so `my-laptop` gives `ssh://my-laptop@ssh.raftrun.com:2222`. ### 3. Connect `your terminal` ```sh # once: trust RaftRun's SSH host key ssh-keyscan -p 2222 ssh.raftrun.com >> ~/.ssh/known_hosts # point Docker at your host, in this terminal export DOCKER_HOST=ssh://my-laptop@ssh.raftrun.com:2222 docker run --rm hello-world ``` The first command waits about 15 to 30 seconds while the host starts. After that, commands answer at once. ### 4. Reuse one connection Docker opens a new SSH connection for every command. Add this to `~/.ssh/config` on macOS or Linux to keep one open, which makes each command several times faster. `~/.ssh/config` ``` Host ssh.raftrun.com ControlMaster auto ControlPath ~/.ssh/control-%C ControlPersist 10m ``` ## Keep it on every terminal `export DOCKER_HOST` lasts for one terminal. A Docker context remembers the host for every terminal and every tool that follows Docker's current context. `your terminal` ```sh docker context create raftrun --docker "host=ssh://my-laptop@ssh.raftrun.com:2222" docker context use raftrun ``` `docker context use default` goes back to your local Docker. Working on several projects? Give each folder its own host instead; see [One host per project](https://raftrun.com/docs/docker/projects). ## Things to know - **Bind mounts point at the host's disk,** not your laptop's. `-v $(pwd):/app` mounts an empty folder on the host. `docker build` sends your folder as usual, and to edit code in a running container, sync it in: see [Use your local files](https://raftrun.com/docs/docker/files). - **Published ports are private.** Open them on your machine through SSH; see [Open a service](https://raftrun.com/docs/docker/ports). - **It is x64 Linux.** Images build for `linux/amd64`, also from an Apple silicon Mac. - **It is yours.** Each host belongs to the person who created it, and only their keys get in. ## Permission denied (publickey) Your machine offered SSH keys the host doesn't have. The host's row on the Docker hosts page shows the key it accepts and, after a refusal, the keys that were offered instead. Compare them with the keys on your machine: `your terminal` ```sh # the keys SSH offers, in order ssh -v -p 2222 my-laptop@ssh.raftrun.com true 2>&1 | grep -E "Offering|denied" # the fingerprint of each key you have for f in ~/.ssh/*.pub; do ssh-keygen -lf "$f"; done ``` If one of your keys matches the host's but SSH doesn't offer it, it has a name SSH doesn't try by itself. Name it in `~/.ssh/config`: `~/.ssh/config` ``` Host ssh.raftrun.com IdentityFile ~/.ssh/my_raftrun_key IdentitiesOnly yes ``` If none match, the key was pasted from another machine. Use that machine, or create a host with this machine's key. ## Next - [Run services](https://raftrun.com/docs/docker/services): Run a compose stack on the host and see which services are up, healthy and listening. - [Use your local files](https://raftrun.com/docs/docker/files): Edit on your laptop and see the change in the running container, with compose watch or Mutagen. - [Open a service](https://raftrun.com/docs/docker/ports): Reach a container's port from your machine without putting it on the internet. - [One host per project](https://raftrun.com/docs/docker/projects): Give each project folder its own host, for you and for coding agents. --- # Run services > Run a compose stack on the host and see which services are up, healthy and listening. Source: https://raftrun.com/docs/docker/services With `DOCKER_HOST` or a context pointing at your host, `docker compose` runs your whole stack there. The dashboard shows which services are up, whether they are healthy, what they use, and which ports they publish. ## Run a stack A typical app with a database. Health checks are optional, but they are what makes a service show as healthy or unhealthy. `compose.yaml` ```yaml services: api: build: . ports: ["3000:3000"] environment: DATABASE_URL: postgres://postgres:postgres@db:5432/app depends_on: db: condition: service_healthy healthcheck: test: ["CMD", "curl", "-fs", "http://localhost:3000/health"] interval: 10s retries: 3 db: image: postgres:17 environment: POSTGRES_PASSWORD: postgres POSTGRES_DB: app volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: ["CMD", "pg_isready", "-U", "postgres"] interval: 5s volumes: pgdata: ``` `your terminal` ```sh docker compose up -d --build docker compose ps docker compose logs -f api ``` `build: .` sends the folder to the host and builds there. Named volumes such as `pgdata` live on the host and survive restarts and stops. A bind mount like `./src:/app` would mount the host's disk, not your folder; to edit code live, sync it in with [compose watch or Mutagen](https://raftrun.com/docs/docker/files). ## See what is running On the **Docker hosts** page, press **Stats** on a host. Under the machine's CPU, memory, disk and network, **Containers** lists every running container: | Column | Shows | | --- | --- | | Container | The compose service name, or the container name, with its image underneath. Containers are grouped by compose project. | | Up | How long it has run, as `docker ps` says it, with a dot for its health check: green healthy, amber starting, red unhealthy. | | Ports | Each published port, as the host port and, when different, the container port. Click one to copy the command that opens it on your machine. | | CPU | Its share of the whole machine over the last minute. | | Memory | What it uses now, counted as `docker stats` counts it. | The list refreshes once a minute while the host runs, and a stopped host shows what was running when it stopped. For the live state, use `docker compose ps` and `docker stats` from your terminal; they answer from the host. ## See what fills the disk The **Disk** column shows each host's used and free space; with several hosts, the total for all of them is above the list. Click a host's bar for two views: - **Overview** splits the disk into images, volumes, build cache, containers' own changes, other files and the system's own files, and lists the largest folders, files, images and volumes. - **Browse** walks the disk folder by folder, largest first, with each entry's size, item count and last change. The host scans its disk when the space in use has changed by a GB since the last scan, at most every 30 minutes, and at the lowest priority, pausing while your own work is busy with the disk; press **Rescan** for a fresh look. A stopped host shows its last scan. Only names and sizes are read, never what files hold, and entries under 1 MB are counted in their folder as smaller items. To free space, `docker builder prune` removes unused build cache and `docker image prune` images nothing uses. ## Several stacks on one host Each folder is its own compose project, so two stacks don't replace each other's containers. They do share the host's ports: two services can't both publish 3000. Change one side's host port, such as `"3001:3000"`, or give each project its own host, as in [One host per project](https://raftrun.com/docs/docker/projects). ## When the host stops Containers stop with it, and images and volumes stay. After it starts again, start the stack again with `docker compose up -d`, or give services `restart: unless-stopped` to have them start with the host. --- # Use your local files > Edit on your laptop and see the change in the running container, with compose watch or Mutagen. Source: https://raftrun.com/docs/docker/files On a Docker host, a bind mount such as `./src:/app` mounts a folder on the host's disk, not your laptop's. Your files reach the host only through Docker's own connection, so instead of mounting them you copy them in as you work. Two tools do that well: | | compose watch | Mutagen | | --- | --- | --- | | Direction | Laptop to container | Both ways | | Install | Nothing: part of Docker Compose 2.22 and later | `brew install mutagen-io/mutagen/mutagen` | | Files the container writes | Stay in the container | Come back to your laptop | | Best for | App code with hot reload | Anything that has to work like a real mount: generated code, lockfiles, migrations | ## compose watch Compose copies each file you save into the running container. The image already holds the code from `COPY`, so the container starts in sync and only changes travel. `Dockerfile` ```dockerfile FROM node:22 WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . ``` `compose.yaml` ```yaml services: web: build: . ports: ["3000:3000"] command: npm run dev develop: watch: # a saved file is copied into the running container - action: sync path: ./src target: /app/src ignore: - node_modules/ # a dependency change rebuilds the image - action: rebuild path: package.json ``` `your terminal` ```sh docker compose up --watch ``` Save a file and it is in the container within a second or two; a dev server that reloads on change, such as Vite, Next or nodemon, picks it up from there. New files, folders and deletions come across too. Changing `package.json` rebuilds the image and restarts the service. - **One way only.** Files the container writes, like a regenerated lockfile or build output, don't come back. Use Mutagen if you need them. - **Files arrive owned by your laptop's user id** (often 501 or 502). If the app runs as another user and must write to them, give that user access in the Dockerfile. - **List what not to send** under `ignore`. Dependencies belong in the image, not in the sync. - **The host stays awake while it runs,** as with any attached `docker compose up`. Stop it with Ctrl-C when you're done, and the host stops 10 minutes later. ## Mutagen, both ways [Mutagen](https://mutagen.io) keeps a folder on your laptop and a folder in a container in step, in both directions, through Docker's connection. Keep the code in a volume, with one small container holding it for Mutagen, and mount the volume in your services. ### 1. Start the sync In the project folder, with Docker pointing at your host: `your terminal` ```sh # once per project: a volume for the code, and a small container that holds it docker volume create shop-api-src docker run -d --name shop-api-sync --restart unless-stopped \ -v shop-api-src:/app alpine sleep infinity # keep this folder and the volume in sync, both ways mutagen sync create --name shop-api \ --ignore-vcs --ignore node_modules \ . docker://shop-api-sync/app ``` The first time, Mutagen installs a small agent of about 8 MB in the container, then copies your files. How long that takes depends on your upload speed. After that only changes travel. ### 2. Mount the volume `compose.yaml` ```yaml services: web: image: node:22 working_dir: /app command: sh -c "npm ci && npm run dev" ports: ["3000:3000"] volumes: - src:/app volumes: src: name: shop-api-src external: true ``` ### 3. Work as usual Edit on your laptop and the container sees it; a file the container writes appears in your folder. `your terminal` ```sh mutagen sync list shop-api # state, and any conflicts mutagen sync pause shop-api # stop syncing for now mutagen sync resume shop-api mutagen sync terminate shop-api # end it; both copies stay ``` - **Ignore what's big and rebuilt anyway:** `node_modules`, `target`, `.venv`, build output. Install dependencies inside the container instead. - **A running sync keeps the host awake.** It holds a connection open, and a host with a connection doesn't stop for being idle. Run `mutagen sync pause` when you're done for the day, and `resume` when you're back; the volume keeps the files meanwhile. - **One sync per folder.** With one host per project, name the sync, the volume and the container after the project. ## Uploads are your upload speed Every byte goes up your own internet connection. On a slow uplink, keep the first copy small: build dependencies in the image, ignore generated folders, and leave large data files out of the synced folder. A `.dockerignore` does the same for `docker build`. --- # Open a service > Reach a container's port from your machine without putting it on the internet. Source: https://raftrun.com/docs/docker/ports A port your containers publish is open on the host only. Nobody on the internet can reach it, and neither can you, until you forward it to your own machine over SSH. Then it answers at `localhost` as if the service ran on your laptop. ## Open a port Keep this running in a terminal, then visit `http://localhost:3000`: `your terminal` ```sh ssh -N -L 3000:localhost:3000 -p 2222 my-laptop@ssh.raftrun.com ``` Use your host's name in place of `my-laptop`. The **Stats** window on the Docker hosts page lists each container's published ports; click one to copy this command for that port. It works the same on macOS, Linux and Windows. ## Several ports Add one `-L` for each: `your terminal` ```sh ssh -N -p 2222 my-laptop@ssh.raftrun.com \ -L 3000:localhost:3000 \ -L 5432:localhost:5432 \ -L 8080:localhost:8080 ``` The first number is the port on your machine and the last is the host's. If 5432 is taken on your laptop, `-L 15432:localhost:5432` opens the host's database at `localhost:15432` instead. ## Keep the forwards in your SSH config `~/.ssh/config` ``` Host my-laptop-ports HostName ssh.raftrun.com Port 2222 User my-laptop LocalForward 3000 localhost:3000 LocalForward 5432 localhost:5432 ``` Then `ssh -N my-laptop-ports` opens them all. ## Why not a public address A dev stack usually runs with default passwords, debug pages and seeded data. Putting it on a public URL would hand all of that to anyone who finds the address, so the host's firewall keeps published ports off the internet, and the only way in is through SSH with your key. To show your work to someone, invite them to the workspace or deploy it to a real environment. ## Things to know - A host with a port forward open counts as in use: it doesn't stop for being idle. It stops 10 minutes after you close the last forward. - If the host was stopped, the forward starts it. The first request waits 15 to 30 seconds. - Only TCP can be forwarded. UDP ports show in the dashboard but can't be opened this way. --- # One host per project > Give each project folder its own host, for you and for coding agents. Source: https://raftrun.com/docs/docker/projects When you work on several projects, or run a coding agent in each, give every project folder its own host. Their containers, ports and volumes never meet, two stacks can both use port 3000, and an agent in one folder can't stop the other's database. ## Set up a folder ### 1. Create a host for the project Name it after the project, such as `shop-api`. How many hosts you may have is set by your workspace's admin; see [rules](https://raftrun.com/docs/docker/lifecycle#rules). ### 2. Run its setup in the folder On the Docker hosts page, press **Use in a folder** under the host, pick what runs Docker there (Claude Code, Codex or another agent, or just your terminal), and run the one command it gives you in the project folder. The window ticks off the last step when the host sees your first `docker` command. The command is safe to run twice, and never overwrites a file you already have. It: - creates a Docker context named after the host; - sets `DOCKER_CONTEXT` in `.claude/settings.local.json`, for Claude Code; - adds `export DOCKER_CONTEXT=…` to `.envrc`, for your terminal with [direnv](https://direnv.net); - for another agent, adds a line to `AGENTS.md` telling it to use that context; - keeps the files out of git through `.git/info/exclude`, leaving your `.gitignore` alone. ### 3. Check it `in the project folder` ```sh docker context show # prints shop-api docker version # the Server section answers from the host ``` From then on, every `docker` and `docker compose` command run in that folder, by you or an agent, goes to its host. ## Doing it by hand For your terminal, with direnv: `.envrc` ``` export DOCKER_CONTEXT=shop-api ``` For Claude Code, in the folder's `.claude/settings.local.json`: `.claude/settings.local.json` ```json { "env": { "DOCKER_CONTEXT": "shop-api" } } ``` Codex and other agents don't read Claude Code's settings. Start them from a terminal in the folder, so they inherit `DOCKER_CONTEXT`, and add this to the folder's `AGENTS.md`: `AGENTS.md` ``` Docker runs on a remote host. Use the context in $DOCKER_CONTEXT, which is set for this folder. Never run `docker context use`, and never switch to another context. ``` ## Good to know - A folder's own `DOCKER_CONTEXT` wins over the default context. Set a default once with `docker context use` if you like, but don't switch it while working: it changes every folder without its own at once. - `DOCKER_HOST` beats `DOCKER_CONTEXT`. If your shell profile exports it, remove it there. - A git worktree is a folder of its own. Run the setup in each, pointing at a different host if both run stacks at once. - Two folders can share a host when they never run at the same time. Give each its own `COMPOSE_PROJECT_NAME` and keep their published ports apart. - Each host stops by itself when nobody uses it, so idle projects cost nothing. --- # Starting, stopping and sizes > When a host runs, what it keeps while stopped, and what it costs. Source: https://raftrun.com/docs/docker/lifecycle A Docker host runs only while someone uses it, so you never have to remember to turn it off. ## When it runs | Event | What happens | | --- | --- | | You run a command, or open a port forward | A stopped host starts and reloads its images, in about 15 to 30 seconds. A running one answers at once. | | 10 minutes with no connection | It stops. | | It has run for its run time | It stops: 8 hours by default, set by your admin between 10 minutes and 7 days. If data is still moving through it, from commands, builds, pulls or forwarded ports, it keeps running an hour at a time, up to 12 hours from its start. A connection left open with nothing moving doesn't count. Connect again to start a new stretch. | | 15 minutes before it stops for good | The **Docker hosts** page warns you, with a **Keep running 1 h** button that gives it another hour, past 12 hours too. | | You press Stop now | It stops at once. | | 11 days stopped | The **Docker hosts** page and the **Activity** page warn you. Start it once to keep its images and volumes for another 14 days. | | 14 days stopped | Its images and volumes are deleted. The host itself stays: its next start puts it on a new, empty machine with the same name, keys and address, so your docker context keeps working. | ## What a stop keeps - **Kept:** images and volumes, including database data in named volumes. - **Stopped:** running containers. Start them again, or give them `restart: unless-stopped`. - **Kept, through the host's cache:** build cache from `docker compose build` in a folder set up with **Use in a folder**, and from builds that ask for it. See [Keep the build cache](#build-cache). ## Keep the build cache Docker's own build cache doesn't survive a stop, so each host runs a small cache registry, `raftrun-cache`, whose data is a volume, and volumes are kept. A build that writes its cache there and reads it back skips every step that hasn't changed, also on the first build after a stop. The cache never leaves the host: nothing extra goes over your connection. ### Compose **Use in a folder** sets this up for you. When the folder has a compose file, it writes `compose.override.yaml` with the cache for each service that builds, keeps it out of git, and Compose reads it by itself. Run the setup again after you add a service. If the project already has its own override file, setup leaves it alone; add this to each service that builds, with your project and service name: `compose.override.yaml` ```yaml services: web: build: cache_from: - type=registry,ref=localhost:15555/my-project/web:cache cache_to: - type=registry,ref=localhost:15555/my-project/web:cache,mode=max,ignore-error=true ``` ### docker build Add the two cache flags, with a name of your own for the image: `your terminal` ```sh docker build -t my-app \ --cache-from type=registry,ref=localhost:15555/my-app:cache \ --cache-to type=registry,ref=localhost:15555/my-app:cache,mode=max,ignore-error=true \ . ``` ### Good to know - `RUN --mount=type=cache` folders, such as npm's, pip's or cargo's download cache, are kept too, by the host itself and for every build: at a stop their contents are packed and saved, and at the next start they are put back. Not those that set `uid`, `gid` or `mode`: they start empty after a stop. Together they may use a tenth of the disk. - When the host stops, old cache entries are cleared, and a cache larger than a quarter of the host's disk is dropped and starts again empty. - `raftrun-cache` shows among your containers. If you remove it, it comes back the next time the host starts; builds meanwhile run without a cache rather than fail. ## Sizes and cost Hosts come in the same sizes as runners, at the same prices, billed by the second while running. A stopped host costs nothing. | Size | vCPU | Memory | Disk | Per minute running | Per hour | | --- | --- | --- | --- | --- | --- | | `raft-ubuntu-24.04-xsmall` | 0.5 | 1 GB | 20 GB | $0.000075 | $0.0045 | | `raft-ubuntu-24.04-small` | 1 | 2 GB | 20 GB | $0.00015 | $0.009 | | `raft-ubuntu-24.04` | 2 | 4 GB | 20 GB | $0.0003 | $0.018 | | `raft-ubuntu-24.04-4` | 4 | 8 GB | 40 GB | $0.0006 | $0.036 | | `raft-ubuntu-24.04-8` | 8 | 16 GB | 100 GB | $0.0012 | $0.072 | | `raft-ubuntu-24.04-16` | 16 | 32 GB | 200 GB | $0.003333 | $0.20 | A 4 vCPU host used for 3 hours a day, 20 days a month, runs 3,600 minutes: $2.16. **Change a size** from the size menu on the Docker hosts page. Images and volumes move with it. A running host stops to change size and starts at the new size on the next connection. ## Rules An admin decides, on the **Team** page: - how many hosts each person may have: 1 by default, 0 to turn hosts off for someone; - which sizes they may pick; - the run time before a host stops. The workspace's default rules apply to everyone; rules set for one person override them. Admins and members can have hosts; billers and viewers can't. Lowering a limit never removes hosts someone already has. ## Delete a host Deleting removes its machine, images and volumes for good. Copy out anything you need first, for example with `docker cp` or `docker run --rm -v pgdata:/data alpine tar c /data > pgdata.tar`. --- # Team and roles > Invite people, choose what each may do, and set their Docker host rules. Source: https://raftrun.com/docs/workspace/team A workspace holds your GitHub connections, jobs, Docker hosts, settings and plan. Everyone in it signs in with Google, and has one role that decides what they can see and change. ## Roles | Role | Can | | --- | --- | | Admin | Everything, including settings, GitHub connections and people. | | Member | Sees jobs and logs; runs Docker hosts and emulators, clears cache. | | Biller | Sees usage and the plan only. | | Viewer | Sees jobs, logs and analytics; changes nothing. | Only admins and members can have Docker hosts. A workspace always keeps at least one admin. ## Invite someone ### 1. Create an invitation On **Team**, under **Invite someone**, enter their email address and choose a role. ### 2. Send them the link RaftRun gives you a link to send however you like. It works once, for 7 days, and only for the Google account with that email address. ### 3. They sign in Opening the link and signing in adds them to the workspace with that role. How many people a workspace may have depends on its plan: Solo 1 person, Team up to 10, Business up to 50. Open invitations count too. ## Change a role or remove someone Admins change roles and remove people in the **Members** table on the Team page. Anyone can leave a workspace themselves from the same table. The last admin can't leave or be removed until someone else is an admin. ## Docker host rules per person Each member's row on the Team page has its own Docker host rules: how many hosts, which sizes and how long a host may run before it stops. Without their own rules, they follow the workspace default set further down the page. See [Starting, stopping and sizes](https://raftrun.com/docs/docker/lifecycle#rules). ## Several GitHub organisations One workspace can connect any number of GitHub organisations and personal accounts in **Settings → GitHub connection**. A GitHub account can belong to only one workspace at a time. --- # Plans and billing > What a plan covers, how machine time is billed, and what happens when a payment fails. Source: https://raftrun.com/docs/workspace/billing You pay for two things: a plan for the people in your workspace, and the minutes your jobs and Docker hosts run on RaftRun's machines. Both go on one monthly invoice. There is no free trial. ## Plans | Plan | People | Cache included | Monthly | Yearly | | --- | --- | --- | --- | --- | | Solo | 1 | 10 GB | $9 | $90 | | Team | up to 10 | 50 GB | $19 | $190 | | Business | up to 50 | 150 GB | $49 | $490 | Every plan runs unlimited jobs, repositories and GitHub accounts, and includes the dashboard, analytics, log search and Docker hosts. Yearly is two months free. Choose or change a plan on **Plan & billing**; admins and billers can open it. ## Machine time - Jobs are billed by the second from when a machine picks them up until they end. Queueing and start-up are free, and there is no one-minute minimum. - Docker hosts are billed by the second while running, at the same prices. Stopped hosts are free. - Prices per minute are on [Runner sizes](https://raftrun.com/docs/actions/runners). - A monthly spending cap, $50 by default, holds new jobs once it is reached. See [Limits and timeouts](https://raftrun.com/docs/actions/limits). ## Cache storage Your plan includes cache storage. Buy more in blocks of 100 GB at $10 a month ($100 a year), or keep the cache in [your own bucket](https://raftrun.com/docs/actions/cache#use-your-own-bucket) for free. When storage is full, the least recently used entries make room; it never bills you more by itself. ## If a payment fails The workspace keeps running for 7 days while the card is updated. After that, new jobs wait until the plan is paid. Update the card from **Plan & billing**. --- # Limitations > What RaftRun doesn't do yet. Check this before you move a workflow. Source: https://raftrun.com/docs/limitations If a job needs one of these, keep it where it runs today. Everything else can move with a one-line change. ## Runners - **No Windows or macOS runners.** Jobs that need runs-on: windows-* or macos-* have to stay on GitHub-hosted runners or another provider. - **No Arm64 or GPU runners.** Every runner is x64 without a GPU. Builds for Arm64 can cross-compile or use QEMU emulation, which is slower. - **Up to 16 vCPU and 32 GB of memory.** There are no 32 or 64 vCPU sizes. Memory is 2 GB per vCPU, half of what some other providers give at the same vCPU count. - **20 GB of disk on the three smallest sizes.** Jobs that pull large images or build big artifacts should use raft-ubuntu-24.04-4 (40 GB) or larger. - **Ubuntu 24.04 only, no custom images.** Each job starts from the same Ubuntu 24.04 image. Bringing your own image, or older Ubuntu releases, is not supported yet. - **Caching covers actions/cache and Rust builds.** There is no Docker layer cache yet, and the actions/cache integration is in beta. Rust builds are cached through mbx. - **Egress rules apply to IPv4.** With a deny-all default, IPv6 is blocked outright. A job running as root can change the rules, so treat them as a guard rail, not a sandbox. - **No static outbound IP addresses.** Runner machines do not have fixed IPs, so you cannot allowlist RaftRun in a firewall by address. - **GitHub.com only.** GitHub Enterprise Server is not supported. ## Docker hosts - **No public addresses.** Published ports are reachable only through an SSH port forward. See [Open a service](https://raftrun.com/docs/docker/ports). - **The build cache needs the host's cache to survive a stop.** Compose builds in a folder set up with Use in a folder use it by themselves; plain `docker build` needs two flags. See [Keep the build cache](https://raftrun.com/docs/docker/lifecycle#build-cache). - **No bind mounts from your laptop.** A bind mount uses the host's disk. Sync your files in instead; see [Use your local files](https://raftrun.com/docs/docker/files). - **x64 only.** Arm64 images run only through emulation.