> ## Documentation Index > Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt > Use this file to discover all available pages before exploring further. # Core concepts > Understand how RBS organizes your code: branch-based servers, workspaces, packages, targets, and collaboration ## 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: 1. **Spins up an RBS server** for that branch. 2. **Clones the repository** and checks out the branch. 3. **Deploys all workers automatically** — CI workers, schedulers, job workers, and build workers. 4. **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. ```python theme={null} # 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. ```python theme={null} # 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: ```bash theme={null} # 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`: ```python theme={null} py_binary( name = "app", srcs = ["main.py"], deps = [":utils", ":models"], # Same-package dependencies ) ``` ### Cross-package dependencies Reference targets in other packages with `//package:target`: ```python theme={null} 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`: ```python theme={null} 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}` | ```python theme={null} 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: ```python theme={null} native.task( name = "build", command = ["echo", "Building on " + platform.name], ) ``` ### Platform constraints Restrict targets to specific platforms: ```python theme={null} 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. ## Next steps Learn the full syntax for BUILD.rbs and WORKSPACE.rbs files. Set up your first language SDK.