Getting started

This page sets up a Linux workstation to build any SVRBC project. You need two things: Nix, which supplies the pinned tools a build runs, and Bazelisk, which runs the version of Bazel that each repository asks for. Builds then read the shared cache automatically.

Let an AI agent do it

Paste this into a coding agent (Claude Code, Codex, …) running on the machine:

Set up this machine for SVRBC development by following
https://developers.svrbc.org/getting-started exactly. Install Nix and
Bazelisk as written there and verify each step before moving on. The Nix
installer needs sudo and asks questions: open it in a terminal window for me
rather than running it yourself, then check that it worked. If I tell you
this is a trusted workstation, also do the "Trusted workstations" steps; the
AWS sign-in opens a browser tab for me to approve. Never write credentials
into a repository. Finish by building a target in an SVRBC repository and
telling me whether it came from the shared cache.

Pilot

This setup is being piloted on doreancon.org’s asset pipeline. The open questions are listed under Builds and CI.

1. Install Nix

Use the official multi-user (daemon) installer. It needs sudo and asks a few questions, so run it in a real terminal:

sh <(curl -L https://nixos.org/nix/install) --daemon

Open a new terminal afterwards so your shell picks up the Nix profile, then check it:

nix --version

Bazel uses Nix only to fetch tools from nixpkgs at the versions a repository pins. You don’t need to learn Nix to build a project.

2. Install Bazelisk as bazel

Bazelisk is a single binary. It reads .bazelversion in the repository you’re in, then downloads and runs that Bazel release. Install it on your PATH under the name bazel:

version=v1.29.0
url=https://github.com/bazelbuild/bazelisk/releases/download/$version/bazelisk-linux-amd64
mkdir -p ~/.local/bin
curl -fsSL -o ~/.local/bin/bazelisk "$url"
echo "$(curl -fsSL "$url.sha256")  $HOME/.local/bin/bazelisk" | sha256sum -c -
chmod +x ~/.local/bin/bazelisk
ln -sf bazelisk ~/.local/bin/bazel

Check it. Outside a repository this prints the latest Bazel release. Inside one, it prints the version pinned in .bazelversion:

bazel --version

3. Build a project

From the root of any converted repository:

bazel build //...   # build everything
bazel test //...    # run every test

Build only what you need by naming a target, for example bazel build //hymns:2026/psalm-119-he. Bazel works out what that target depends on and builds only that.

On Ubuntu, Bazel reports processwrapper-sandbox instead of linux-sandbox, because AppArmor restricts the user namespaces the Linux sandbox needs. That’s expected.

Nothing else needs to be installed. If a build seems to need a program from your machine’s PATH, that’s a bug in the build. Report it rather than installing the program.

Bazel reads the shared cache at https://bazel-cache.svrbc.org (each repository’s .bazelrc says so), so anything CI has already built comes down instead of being rebuilt. The summary line shows it: … remote cache hit.

Trusted workstations

Only for an SVRBC administrator’s own machine, with full-disk encryption (see Builds and CI for what trusted means). These steps let it upload what it builds to the shared cache. Every other machine stops at step 3.

4. Install the AWS CLI, from nixpkgs:

nix --extra-experimental-features 'nix-command flakes' profile add nixpkgs#awscli2
aws --version

5. Point it at the SVRBC access portal. Add this to ~/.aws/config (create the file if it doesn’t exist):

[sso-session svrbc]
sso_start_url = https://d-906661105f.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access

[profile svrbc]
sso_session = svrbc
sso_account_id = 991299033875
sso_role_name = AdministratorAccess
region = us-west-2

Then sign in. This opens a browser tab to approve, and lasts about a working day:

aws sso login --profile svrbc
aws sts get-caller-identity --profile svrbc    # shows your user name

6. Install bazel-cache-sync from this handbook’s repository (see Tools):

ln -sf ~/projects/developers.svrbc.org/tools/bazel-cache-sync ~/.local/bin/bazel-cache-sync

7. Upload after a build. Build as usual, then:

AWS_PROFILE=svrbc bazel-cache-sync --dry-run   # what would go up
AWS_PROFILE=svrbc bazel-cache-sync

Upload only what you built from committed, reviewed code. Every other machine trusts what you upload.

Next

• Builds and CI: why the setup looks like this, and the rules every repository follows.