Core concepts

Branch-based servers

RBS provisions a dedicated build server for every active branch in your project. When you start working on a branch, the platform:

Spins up an RBS server for that branch.
Clones the repository and checks out the branch.
Deploys all workers automatically — CI workers, schedulers, job workers, and build workers.
Connects your editor to the server via the RBS extension.

┌──────────────────────────────────────────────────────┐
│                    RBS Platform                       │
│                                                       │
│  main branch ────→ [RBS Server] ← CI workers (auto)  │
│                       ↑                               │
│                    Dev A (editor)                      │
│                                                       │
│  feature/auth ──→ [RBS Server] ← CI workers (auto)   │
│                       ↑  ↑                            │
│                  Dev B   Dev C  (collaborating)        │
│                                                       │
│  feature/pay ───→ [RBS Server] ← CI workers (auto)   │
│                       ↑                               │
│                    Dev D (editor)                      │
└──────────────────────────────────────────────────────┘

Collaboration

Multiple developers can connect to the same branch server simultaneously. Everyone sees:

The same build state and outputs.
The same test results and logs.
Real-time updates when teammates run builds.

Server lifecycle

Event	What happens
Developer starts working on a branch	Server is provisioned, repo cloned, workers deployed.
Teammate joins the same branch	Connects to the existing server.
All developers disconnect	Server idles (configurable timeout).
Branch is merged or deleted	Server is decommissioned.
Push to branch (no active editor)	CI workers run automatically.

Built-in Git server

RBS includes an integrated Git server. You can host your repositories directly on the platform — no GitHub, GitLab, or Bitbucket required.

Push and pull with standard Git commands.
Branch management from the dashboard or editor.
Webhooks and triggers for CI/CD workflows.
Access control with team-based permissions.

If you prefer to use an external Git host, RBS can import and mirror repositories from GitHub, GitLab, and other providers.

Workspace

Every RBS project starts with a workspace — defined by a WORKSPACE.rbs file at the repository root. This file configures project-wide settings, toolchains, and external dependencies.

# WORKSPACE.rbs
config_setting(key = "project_name", value = "my-app")
config_setting(key = "version", value = "1.0.0")

# Register toolchains (managed by the server)
load("@rbs//python/toolchain.rbs", "python_toolchain")
python_toolchain(name = "python", version = "3.11.0")

# Declare external dependencies
load("@rbs//python/dependencies.rbs", "py_repository")
py_repository(name = "requests_lib", package = "requests", version = "2.31.0")

When the RBS server starts, it reads WORKSPACE.rbs and sets up the entire build environment — downloading toolchains, resolving dependencies, and preparing workers.

Packages

A package is any directory within a workspace that contains a BUILD.rbs file. Each package defines its own set of build targets.

my-app/
├── WORKSPACE.rbs
├── BUILD.rbs               # Root package
├── services/
│   ├── api/
│   │   └── BUILD.rbs       # Package: services/api
│   └── worker/
│       └── BUILD.rbs       # Package: services/worker
└── libs/
    └── common/
        └── BUILD.rbs       # Package: libs/common

Packages provide logical grouping for related targets. You can reference targets across packages using labels.

Targets

A target is a single buildable unit declared in a BUILD.rbs file — a binary, library, test, container image, or any custom rule. Every target has a unique name within its package.

# services/api/BUILD.rbs
load("@rbs//python/rules.rbs", "py_binary", "py_test")

py_binary(
    name = "server",
    srcs = ["main.py", "routes.py"],
    main = "main.py",
    deps = [":handlers"],
)

py_test(
    name = "server_test",
    srcs = ["test_main.py"],
    deps = [":server"],
)

Labels

Labels uniquely identify targets across a workspace. RBS supports two syntax styles:

Traditional syntax

//package/path:target_name

Label	Meaning
`//services/api:server`	Target `server` in `services/api`
`//:hello`	Target `hello` in root package
`//...`	All targets in all packages
`:server`	Target `server` in current package

Natural syntax

RBS also supports a more intuitive syntax:

# package target
rbs build services/api server

# Multiple targets in same package
rbs build services/api server server_test

# Root package targets
rbs build hello

Dependencies

Targets can depend on other targets. RBS automatically builds dependencies in the correct order using a dependency graph (DAG).

Local dependencies

Reference targets in the same package with :name:

py_binary(
    name = "app",
    srcs = ["main.py"],
    deps = [":utils", ":models"],   # Same-package dependencies
)

Cross-package dependencies

Reference targets in other packages with //package:target:

py_binary(
    name = "app",
    srcs = ["main.py"],
    deps = [
        "//libs/common:utils",       # Cross-package dependency
        ":local_lib",                 # Same-package dependency
    ],
)

External dependencies

Reference packages managed by RBS from your WORKSPACE.rbs:

py_binary(
    name = "app",
    srcs = ["main.py"],
    deps = [
        "@external://requests:2.31.0",   # External pip package
    ],
)

Output directory

RBS places all build outputs in the .rbs/ directory on the server, organized by platform:

.rbs/
├── bin/linux-amd64/           # Compiled binaries
├── out/linux-amd64/           # General outputs
├── testlogs/linux-amd64/      # Test logs and coverage reports
├── toolchains/                # Managed toolchains
└── external-deps/             # Cached external dependencies

Build outputs are accessible from your editor and via the RBS dashboard.

Output path variables

In BUILD.rbs files, use the built-in output_path variable to reference output directories:

Variable	Path
`output_path.bin`	`.rbs/bin/{platform}`
`output_path.out`	`.rbs/out/{platform}`
`output_path.testlogs`	`.rbs/testlogs/{platform}`

native.task(
    name = "generate_report",
    command = ["sh", "-c", "echo 'Report' > " + output_path.out + "/report.txt"],
    outputs = [output_path.out + "/report.txt"],
)

Platform detection

RBS servers run on Linux by default. You can use the platform variable in your BUILD.rbs files:

native.task(
    name = "build",
    command = ["echo", "Building on " + platform.name],
)

Platform constraints

Restrict targets to specific platforms:

native.task(
    name = "linux_only",
    command = ["echo", "Linux specific"],
    target_compatible_with = ["@platforms//os:linux"],
)

Hermetic builds

RBS ensures hermetic builds — every dependency, toolchain, and runtime is managed by the platform. This means:

No local dependencies: You don’t need Python, Node.js, or Java installed on your machine.
Reproducible: The same build always produces the same output, regardless of who runs it.
Consistent across branches: Every branch server starts from a clean, identical base.
Portable: Your project works identically in development and production.

Getting Started

Examples

Branch-based servers

Collaboration

Server lifecycle

Built-in Git server

Workspace

Packages

Targets

Labels

Traditional syntax

Natural syntax

Dependencies

Local dependencies

Cross-package dependencies

External dependencies

Output directory

Output path variables

Platform detection

Platform constraints

Hermetic builds

Next steps

RBS DSL reference

Language SDKs

​Branch-based servers

​Collaboration

​Server lifecycle

​Built-in Git server

​Workspace

​Packages

​Targets

​Labels

​Traditional syntax

​Natural syntax

​Dependencies

​Local dependencies

​Cross-package dependencies

​External dependencies

​Output directory

​Output path variables

​Platform detection

​Platform constraints

​Hermetic builds

​Next steps

RBS DSL reference

Language SDKs

Branch-based servers

Collaboration

Server lifecycle

Built-in Git server

Workspace

Packages

Targets

Labels

Traditional syntax

Natural syntax

Dependencies

Local dependencies

Cross-package dependencies

External dependencies

Output directory

Output path variables

Platform detection

Platform constraints

Hermetic builds

Next steps