### Install Dependencies and Run Docs Server

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/contribute/docs.mdx

Navigate to the 'web' directory, install dependencies using Bun, and start the documentation development server. Access the docs at http://localhost:3001/docs.

```bash
cd web
bun install
bun dev:docs        # docs only — http://localhost:3001/docs
```

--------------------------------

### Complete Example: Stores Configuration

Source: https://github.com/tracemachina/nativelink/blob/main/nativelink-config/examples/README.md

Example configuration for Content Addressable Storage (CAS) and Access Cache (AC) stores, including filesystem and fast/slow store setups with eviction policies.

```json5
  "stores": [
    {
      name: "AC_MAIN_STORE",
      "filesystem": {
        "content_path": "/tmp/nativelink/data-worker-test/content_path-ac",
        "temp_path": "/tmp/nativelink/data-worker-test/tmp_path-ac",
        "eviction_policy": {
          // 1gb.
          "max_bytes": 1000000000,
        }
      }
    },
    {
      name: "WORKER_FAST_SLOW_STORE",
      "fast_slow": {
        // "fast" must be a "filesystem" store because the worker uses it to make
        // hardlinks on disk to a directory where the jobs are running.
        "fast": {
          "filesystem": {
            "content_path": "/tmp/nativelink/data-worker-test/content_path-cas",
            "temp_path": "/tmp/nativelink/data-worker-test/tmp_path-cas",
            "eviction_policy": {
              // 10gb.
              "max_bytes": 10000000000,
            }
          }
        },
        "slow": {
          /// Discard data.
          /// This example usage has the CAS and the Worker live in the same place,
          /// so they share the same underlying CAS. Since workers require a fast_slow
          /// store, we use the fast store as our primary data store, and the slow store
          /// is just a noop, since there's no shared storage in this config.
          "noop": {}
        }
      }
    }
  ]
```

--------------------------------

### Start NativeLink with Configuration

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/metrics/README.md

Start the NativeLink server with your configuration file after setting the necessary environment variables for metrics export.

```bash
nativelink /path/to/config.json
```

--------------------------------

### Complete Example: Scheduler Configuration

Source: https://github.com/tracemachina/nativelink/blob/main/nativelink-config/examples/README.md

Example configuration for a simple scheduler, defining supported platform properties with minimum or exact matching criteria.

```json5
  "schedulers": [
    {
      name: "MAIN_SCHEDULER",
      "simple": {
        "supported_platform_properties": {
          "cpu_count": "minimum",
          "memory_kb": "minimum",
          "network_kbps": "minimum",
          "disk_read_iops": "minimum",
          "disk_read_bps": "minimum",
          "disk_write_iops": "minimum",
          "disk_write_bps": "minimum",
          "shm_size": "minimum",
          "gpu_count": "minimum",
          "gpu_model": "exact",
          "cpu_vendor": "exact",
          "cpu_arch": "exact",
          "cpu_model": "exact",
          "kernel_version": "exact",
          "OSFamily": "priority",
          "container-image": "priority",
          // Example of how to set which docker images are available and set
          // them in the platform properties.
          // "docker_image": "priority",
        }
      }
    }
  ]
```

--------------------------------

### Verify LRE Setup with Kubernetes Example

Source: https://github.com/tracemachina/nativelink/blob/main/local-remote-execution/README.md

This script verifies the LRE setup by deploying a Docker image and a LRE worker using NativeLink's Kubernetes example. Ensure the NATIVELINK_COMMIT is synchronized.

```bash
#!/usr/bin/env bash

set -xeuo pipefail

EVENTLISTENER=$(kubectl get gtw eventlistener -o=jsonpath='{.status.addresses[0].value}')

# Note: Keep this in sync with the commit in `flake.nix` and `MODULE.bazel`.
NATIVELINK_COMMIT=64ed20a40964b8c606c7d65f76af840bcfc837fd

curl -v \
    -H 'Content-Type: application/json' \
    -d '{ \
        "flakeOutput": "github:TraceMachina/nativelink/'"${NATIVELINK_COMMIT}"'#image" \
    }' \
    http://"${EVENTLISTENER}":8080

curl -v \
    -H 'Content-Type: application/json' \
    -d '{ \
        "flakeOutput": "github:TraceMachina/nativelink/'"${NATIVELINK_COMMIT}"'#nativelink-worker-lre-cc" \
    }' \
    http://"${EVENTLISTENER}":8080

```

--------------------------------

### Install Nix

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/contribute/nix.mdx

Use this command to install the experimental Nix installer, which enables flakes by default. This is the recommended way to get Nix for the NativeLink project.

```bash
curl --proto '=https' --tlsv1.2 -sSf \
  -L https://install.determinate.systems/nix | sh -s -- install
```

--------------------------------

### Start NativeLink and Build (LRE Template)

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/rbe/nix-templates.mdx

Starts the NativeLink server and then builds a target using Bazel. The first build incurs compilation cost, subsequent builds are faster due to local caching.

```bash
nativelink ./config/lre.json5
bazel build //hello
```

--------------------------------

### Install Dependencies

Source: https://github.com/tracemachina/nativelink/blob/main/web/README.md

Install project dependencies once at the workspace root.

```bash
cd web
bun install
```

--------------------------------

### Docker Compose: Start Local Metrics Stack

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/deployment/metrics.mdx

Clone the repository, navigate to the metrics deployment directory, and start the local metrics stack using Docker Compose.

```bash
git clone https://github.com/TraceMachina/nativelink
cd nativelink/deployment-examples/metrics
docker-compose up -d
```

--------------------------------

### Build and Run NativeLink Locally, Test with Bazel

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/docker-compose/README.md

Builds the NativeLink binary locally and starts a multi-worker server. It then tests the setup with Bazel, configuring it to use the remote cache and executor. This option is for advanced users who prefer building locally.

```shell
# Build nativelink locally first
cargo build --release

# Start multi-worker server (3 workers, shared CAS)
./target/release/nativelink test-multi-worker-simple.json5

# In another terminal, test with Bazel
bazel build //:nativelink \
  --remote_cache=grpc://127.0.0.1:50051 \
  --remote_executor=grpc://127.0.0.1:50051 \
  --remote_default_exec_properties=cpu_count=1 \
  --jobs=3
```

--------------------------------

### Start Metrics Stack with Docker Compose

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/metrics/README.md

Use this command to start the OpenTelemetry metrics stack using Docker Compose. Ensure you are in the 'deployment-examples/metrics' directory.

```bash
cd deployment-examples/metrics
docker-compose up -d
```

--------------------------------

### Private Server Configuration

Source: https://github.com/tracemachina/nativelink/blob/main/nativelink-config/examples/README.md

Example of how to set available docker images and configure them in platform properties for a private server.

```json
{
  "docker_image": {
    "query_cmd": "docker images --format {{.Repository}}:{{.Tag}}"
  }
}
```

--------------------------------

### Scheduler Configuration Example

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/reference/nativelink-config.mdx

Sets up a 'simple' scheduler with supported platform properties, maximum job retries, and worker timeout. It also defines match modes for properties.

```json5
{
  simple: {
    supported_platform_properties: {
      OSFamily:        "exact",
      container_image: "exact",
      cpu_count:       "minimum",
      // priority: "exact",
    },
    max_job_retries:  3,
    worker_timeout_s: 300,
  },
}
```

--------------------------------

### Install NativeLink with Nix on macOS/Linux

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/getting-started/setup.mdx

Download a basic configuration file and run NativeLink using Nix. This method builds from source and may be slower than Docker.

```bash
curl -O https://raw.githubusercontent.com/TraceMachina/nativelink/main/nativelink-config/examples/basic_cas.json5

nix run github:TraceMachina/nativelink ./basic_cas.json5
```

--------------------------------

### Basic Bazel Build Test with Multi-Worker Setup

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/docker-compose/README.md

Builds a simple target using Bazel, directing it to use two different ports for remote cache and executor, simulating a multi-worker setup. It also shows how to check which worker executed the action.

```shell
# Build a simple target
bazel build //src:hello_world \
  --remote_cache=grpc://127.0.0.1:50051 \
  --remote_executor=grpc://127.0.0.1:50052

# Check which worker executed
docker-compose -f docker-compose-multi-worker.yml logs | grep "Executing action"
```

--------------------------------

### Server Configuration Example

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/reference/nativelink-config.mdx

Defines a server instance with its listener details (HTTP, TLS, advanced settings) and the exposed services like CAS, AC, ByteStream, and Execution.

```json5
{
  name: "main_server",
  listener: {
    http: {
      socket_address: "0.0.0.0:50051",
      tls: { /* optional */ },
      advanced_http: { http2_keep_alive_interval: 10 },
    },
  },
  services: {
    cas:          [{ instance_name, cas_store }],
    ac:           [{ instance_name, ac_store, read_only? }],
    bytestream:   [{ instance_name, cas_store, max_bytes_per_stream? }],
    capabilities: [{ instance_name, remote_execution? }],
    execution:    [{ instance_name, scheduler }],
    worker_api:   { scheduler },
  },
}
```

--------------------------------

### Run Full Development Server

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/contribute/docs.mdx

Start the main development server to preview marketing and documentation content together. The marketing app rewrites the /docs path to the docs app in development. Access the combined preview at http://localhost:3000/docs.

```bash
bun dev             # both apps in parallel
# → http://localhost:3000/docs
```

--------------------------------

### Initialize Project with NativeLink Bazel Template

Source: https://github.com/tracemachina/nativelink/blob/main/templates/README.md

Use this command to initialize a new project with the NativeLink Bazel template. Ensure you have Nix with flakes enabled installed.

```bash
nix flake init -t github:TraceMachina/nativelink#TEMPLATE_NAME
git init
git add .
```

--------------------------------

### Initialize Bazel Template

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/rbe/nix-templates.mdx

Sets up a new directory with the Bazel NativeLink template. This provides a local RBE setup with Bazel pre-configured.

```bash
mkdir my-rbe-test && cd my-rbe-test
nix flake init -t github:TraceMachina/nativelink#bazel
nix develop
```

--------------------------------

### Install direnv for Shell Integration

Source: https://github.com/tracemachina/nativelink/blob/main/CONTRIBUTING.md

Install the direnv utility and hook it into your shell for automatic environment loading when entering directories. This is recommended for NativeLink development.

```bash
nix profile install nixpkgs#direnv

# Add the right hook for your shell: https://direnv.net/docs/hook.html

# Restart your terminal.

# When you `cd` into the nativelink repository, you should see a message
# asking you to run `direnv allow`. Do this and you're good to go.
```

--------------------------------

### Direct to Prometheus: Start Prometheus with OTLP Receiver

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/deployment/metrics.mdx

Start the Prometheus server with the OTLP receiver enabled and configure the out-of-order time window and configuration file.

```bash
prometheus \
  --web.enable-otlp-receiver \
  --storage.tsdb.out-of-order-time-window=30m \
  --config.file=prometheus.yml
```

--------------------------------

### Install Clang via Nix

Source: https://github.com/tracemachina/nativelink/blob/main/CONTRIBUTING.md

Install a recent version of Clang using Nix, which is required for C++ development within the NativeLink environment.

```bash
# Use your distros preferred package manager (pacman, emerge, apt etc), or
# install via nix:
nix profile install nixpkgs#clang
```

--------------------------------

### Complete Example: Worker Configuration

Source: https://github.com/tracemachina/nativelink/blob/main/nativelink-config/examples/README.md

Example configuration for a local worker, specifying the worker API endpoint, CAS store, upload settings, work directory, and platform properties.

```json5
  "workers": [{
    "local": {
      "worker_api_endpoint": {
        "uri": "grpc://127.0.0.1:50061",
      },
      "cas_fast_slow_store": "WORKER_FAST_SLOW_STORE",
      "upload_action_result": {
        "ac_store": "AC_MAIN_STORE",
      },
      "work_directory": "/tmp/nativelink/work",
      "platform_properties": {
        "cpu_count": {
          "values": ["16"],
        },
        "memory_kb": {
          "values": ["500000"],
        },
        "network_kbps": {
          "values": ["100000"],
        },
        "cpu_arch": {
          "values": ["x86_64"],
        },
        "OSFamily": {
          "values": [""]
        },
        "container-image": {
          "values": [""]
        },

```

--------------------------------

### Build with Bazel (Bazel Template)

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/rbe/nix-templates.mdx

Compiles a sample target using Bazel. After starting the NativeLink server, this command should utilize the local RBE cache.

```bash
bazel build //hello
```

--------------------------------

### Download and Run NativeLink with Nix

Source: https://github.com/tracemachina/nativelink/blob/main/README.md

This snippet shows how to download a basic configuration file and then run the NativeLink executable using Nix. Ensure your Nix installation supports flakes and is up-to-date.

```bash
curl -O \
    https://raw.githubusercontent.com/TraceMachina/nativelink/main/nativelink-config/examples/basic_cas.json5

nix run github:TraceMachina/nativelink ./basic_cas.json5
```

--------------------------------

### Start Reclient Reproxy Daemon

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/deployment/chromium.mdx

Initialize the Reclient reproxy daemon, which batches requests to the RE-API server. This should be run before the build process.

```bash
buildtools/reclient/bootstrap --re_proxy=buildtools/reclient/reproxy
```

--------------------------------

### Install NativeLink with Docker on Linux

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/getting-started/setup.mdx

Download a basic configuration file and run the NativeLink Docker image. The server will listen on port 50051.

```bash
# Grab a known-good basic configuration
curl -O https://raw.githubusercontent.com/TraceMachina/nativelink/v1.3.2/nativelink-config/examples/basic_cas.json5

# Run the official image
docker run \
  -v $(pwd)/basic_cas.json5:/config \
  -p 50051:50051 \
  ghcr.io/tracemachina/nativelink:v1.3.2 config
```

--------------------------------

### Install NativeLink with Docker on Windows

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/getting-started/setup.mdx

Download a basic configuration file using PowerShell and run the NativeLink Docker image. This is for x86_64 Windows; ARM64 users should use WSL2.

```powershell
Invoke-WebRequest `
  -Uri "https://raw.githubusercontent.com/TraceMachina/nativelink/v1.3.2/nativelink-config/examples/basic_cas.json5" `
  -OutFile "basic_cas.json5"

docker run `
  -v ${PWD}/basic_cas.json5:/config `
  -p 50051:50051 `
  ghcr.io/tracemachina/nativelink:v1.3.2 config
```

--------------------------------

### Start NativeLink Server (Bazel Template)

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/rbe/nix-templates.mdx

Runs the NativeLink server binary using a specified configuration file. This is typically done in one terminal while builds are run in another.

```bash
nativelink ./config/nativelink.json5
```

--------------------------------

### Run In-Memory Cache Configuration

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/configuration/basic.mdx

Command to start NativeLink with the in-memory cache configuration.

```bash
nativelink ./basic_cas.json5
```

--------------------------------

### Run Documentation Tests with Bazel

Source: https://github.com/tracemachina/nativelink/blob/main/CONTRIBUTING.md

Execute documentation tests using Bazel to ensure the correctness of embedded examples and documentation.

```bash
bazel test doctests
```

--------------------------------

### Deploy NativeLink on Kubernetes

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/rbe/nix-templates.mdx

Creates a local Kubernetes cluster using 'kind', installs the NativeLink Helm chart, and waits for the pods to become ready. This sets up a distributed NativeLink environment locally.

```bash
kind create cluster
helm install nativelink ./chart
kubectl wait --for=condition=Ready pods --all
```

--------------------------------

### Configure Reclient for Remote Caching

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/getting-started/setup.mdx

Set environment variables for Reclient and start the reproxy and rewrapper services. Use RBE_service_no_security=true for local TLS-free development.

```bash
export RBE_service=localhost:50051
export RBE_instance=main
export RBE_service_no_security=true   # only for local TLS-free dev

reproxy &
rewrapper -- <your-compile-command>
```

--------------------------------

### Configure Prometheus Resource Attribute Promotion

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/metrics/README.md

Example configuration to promote custom resource attributes in Prometheus's OTLP receiver.

```yaml
otlp:
  promote_resource_attributes:
    - your.custom.attribute
```

--------------------------------

### Initialize NativeLink LRE Flake Template

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/explanations/lre.mdx

Use this command to start a new project with the NativeLink LRE flake template. This sets up the necessary structure for local remote execution.

```bash
nix flake init -t github:TraceMachina/nativelink#lre
```

--------------------------------

### Build and Run NativeLink Locally with Multi-Worker

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/docker-compose/MULTI_WORKER.md

Build the NativeLink binary locally and start the multi-worker server. This is an advanced option for local testing.

```sh
cargo build --release
./target/release/nativelink test-multi-worker-simple.json5
```

--------------------------------

### Configuring LRE Environment and Prefix

Source: https://github.com/tracemachina/nativelink/blob/main/local-remote-execution/README.md

Customize LRE by inheriting the environment and setting an optional prefix. This example imports the lre-cc environment and prefixes build commands with 'lre'.

```nix
# This is a top-level field, next to `packages` and `apps`, and `devShells`
lre = {
  # In this example we import the lre-cc environment from nativelink and make it
  # available locally.
  inherit (lre-cc.meta) Env;

  # This causes the `build` commands in the `lre.bazelrc` to be prefixed with
  # `lre` so that LRE is disabled by default and may be enabled by passing
  # `--config=lre` to a Bazel build.
  prefix = "lre";
};

```

--------------------------------

### Run NativeLink with Docker and Test with Bazel

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/docker-compose/README.md

Starts a NativeLink instance using a Docker image and then tests it with Bazel, configuring Bazel to use the remote cache and executor. Ensure the Docker image is built and ports are accessible.

```shell
docker run --rm -it \
  -v $(pwd)/test-multi-worker-simple.json5:/config.json5 \
  -p 50051:50051 \
  -p 50052:50052 \
  nativelink:latest /config.json5

# In another terminal, test with Bazel
bazel build //:nativelink \
  --remote_cache=grpc://127.0.0.1:50051 \
  --remote_executor=grpc://127.0.0.1:50051 \
  --remote_default_exec_properties=cpu_count=1 \
  --jobs=3
```

--------------------------------

### Default lre.bazelrc Configuration

Source: https://github.com/tracemachina/nativelink/blob/main/local-remote-execution/README.md

Example of the dynamically generated lre.bazelrc file, showing Bazel flags for LRE toolchain configuration. Note the warning about the environment not being set.

```bash
# These flags are dynamically generated by the LRE flake module.
#
# Add `try-import %workspace%/lre.bazelrc` to your .bazelrc to
# include these flags when running Bazel in a nix environment.

# These are the paths used by your local LRE config. If you get cache misses
# between local and remote execution, double-check these values against the
# toolchain configs in the `@local-remote-execution` repository at the
# commit that you imported in your `MODULE.bazel`.
#
# WARNING: No environment set. LRE will not work locally.

# Bazel-side configuration for LRE.
build --action_env=BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1
build --define=EXECUTOR=remote
build --extra_execution_platforms=@local-remote-execution//generated-cc/config:platform
build --extra_toolchains=@local-remote-execution//generated-cc/config:cc-toolchain

```

--------------------------------

### Basic Bazel Build Test with Multi-Worker

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/docker-compose/MULTI_WORKER.md

Perform a basic Bazel build, directing remote cache and execution to specific ports used by the multi-worker setup. Logs can be checked for worker execution.

```sh
bazel build //src:hello_world \
  --remote_cache=grpc://127.0.0.1:50051 \
  --remote_executor=grpc://127.0.0.1:50052
```

```sh
docker-compose -f docker-compose-multi-worker.yml logs | grep "Executing action"
```

--------------------------------

### Worker Configuration Example (Local)

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/reference/nativelink-config.mdx

Configures a 'local' worker, specifying its connection to the scheduler, CAS and AC stores, upload settings, platform properties, and persistent worker pool details.

```json5
{
  local: {
    worker_api_endpoint: { uri: "grpc://scheduler:50051", timeout: 10 },
    cas_fast_slow_store: "CAS_MAIN_STORE",
    upload_action_result: {
      upload_action_result: { ac_store: "AC_MAIN_STORE" },
    },
    max_action_timeout: 3600,
    platform_properties: {
      OSFamily:        { values: ["linux"] },
      container_image: { query_cmd: "echo nativelink" },
    },
    persistent_workers: {
      max_workers_per_pool: 8,
      idle_timeout_s: 600,
      protocols: ["proto", "json"],
    },
  },
}
```

--------------------------------

### Run NativeLink Docker Image on Linux

Source: https://github.com/tracemachina/nativelink/blob/main/README.md

This snippet shows how to download a configuration file and run the NativeLink Docker image on a Linux x86_64 system. Ensure you have Docker installed and adjust the volume mount path if necessary.

```bash
curl -O \
    https://raw.githubusercontent.com/TraceMachina/nativelink/v1.3.2/nativelink-config/examples/basic_cas.json5

# See https://github.com/TraceMachina/nativelink/pkgs/container/nativelink
# to find the latest tag
docker run \
    -v $(pwd)/basic_cas.json5:/config \
    -p 50051:50051 \
    ghcr.io/tracemachina/nativelink:v1.3.2 \
    config
```

--------------------------------

### Configure Verify Store with Hashing and Size Checks

Source: https://github.com/tracemachina/nativelink/blob/main/nativelink-config/README.md

Example configuration for a Verify store, designed to ensure data integrity during CAS operations. It supports hash verification (e.g., SHA256) and byte size verification.

```json
{
  "stores": [
    {
      "name": "CAS_MAIN_STORE",
      "verify": {
        "backend": {
          "memory": {
            "eviction_policy": {
              // 1gb.
              "max_bytes": 1000000000,
            }
          }
        },
        "verify_size": true,
        // sha256 or blake3
        "hash_verification_function": "sha256",
      }
    },
    {
      "name": "AC_MAIN_STORE",
      "memory": {
        "eviction_policy": {
          // 100mb.
          "max_bytes": 100000000,
        }
      }
    }
  ],
  // Place rest of configuration here ...
}
```

--------------------------------

### Shape A: Single-node cache architecture

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/deployment/on-prem-overview.mdx

Illustrates a basic setup with a single machine running NativeLink's CAS, AC, and server, using local disk for storage. Suitable for small teams or individual CI runners.

```text
              ┌──────────────────────┐
   Bazel ───▶ │   nativelink         │
   Buck2 ───▶ │   cas + ac + server  │ ──▶ /var/lib/nativelink
              └──────────────────────┘
```

--------------------------------

### Configure Fast Slow Store with Memory and S3

Source: https://github.com/tracemachina/nativelink/blob/main/nativelink-config/README.md

Example configuration for a Fast Slow store, using memory for frequently accessed data and AWS S3 for long-term storage. This setup optimizes read performance by caching hot data in memory.

```json
{
  "stores": [
    {
      "name": "CAS_MAIN_STORE",
      "fast_slow": {
        "fast": {
          "memory": {
            "eviction_policy": {
              // 1gb.
              "max_bytes": 1000000000,
            }
          }
        },
        "slow": {
          "experimental_cloud_object_store": {
            "provider": "aws",
            "region": "us-west-1",
            "bucket": "some-bucket-name",
            "key_prefix": "cas/"
          }
        }
      }
    },
    {
      "name": "AC_MAIN_STORE",
      "fast_slow": {
        "fast": {
          "memory": {
            "eviction_policy": {
              // 100mb.
              "max_bytes": 100000000,
            }
          }
        },
        "slow": {
          "experimental_cloud_object_store": {
            "provider": "aws",
            "region": "us-west-1",
            "bucket": "some-bucket-name",
            "key_prefix": "ac/"
          }
        }
      }
    }
  ],
  // Place rest of configuration here ...
}
```

--------------------------------

### Start Multi-Worker Deployment

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/docker-compose/MULTI_WORKER.md

Starts the multi-worker NativeLink deployment in detached mode.

```sh
docker compose -f docker-compose-multi-worker.yml up -d
```

--------------------------------

### Initialize Kubernetes Template

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/rbe/nix-templates.mdx

Sets up a new directory with the Kubernetes template. This includes tools like kind, kubectl, and helm for running NativeLink within a local cluster.

```bash
mkdir my-k8s-test && cd my-k8s-test
nix flake init -t github:TraceMachina/nativelink#kubernetes
nix develop
```

--------------------------------

### Detailed Public Server Configuration

Source: https://github.com/tracemachina/nativelink/blob/main/nativelink-config/examples/README.md

Sets up the 'public' server with listener and services, including CAS, AC, execution, capabilities, and bytestream configurations.

```json5
{
  "stores": [],
  "workers": [],
  "schedulers": [],
  "servers": [{
    "name": "public",
    "listener": {
      "http": {
        "socket_address": "0.0.0.0:50051"
      }
    },
    "services": {
      "cas": [{
        "instance_name": "main",
        "cas_store": "WORKER_FAST_SLOW_STORE"
      }],
      "ac": [{
        "instance_name": "main",
        "ac_store": "AC_MAIN_STORE"
      }],
      "execution": [{
        "instance_name": "main",
        "cas_store": "WORKER_FAST_SLOW_STORE",
        "scheduler": "MAIN_SCHEDULER",
      }],
      "capabilities": [{
        "instance_name": "main",
        "remote_execution": {
          "scheduler": "MAIN_SCHEDULER",
        }
      }],
      "bytestream": [{
        "instance_name": "main",
        "cas_store": "WORKER_FAST_SLOW_STORE",
      }]
    },
  },{
    "name": "private_workers_servers"
  }],
  "global": {},
}
```

--------------------------------

### Run Development Servers

Source: https://github.com/tracemachina/nativelink/blob/main/web/README.md

Run both the marketing site and docs server in parallel using Turborepo. The marketing site proxies requests for /docs/* to the docs server.

```bash
# Run both apps in parallel via Turborepo
bun dev
#   marketing → http://localhost:3000
#   docs      → http://localhost:3001/docs
#   marketing rewrites /docs/* to the docs server so you can browse
#   both apps from http://localhost:3000

# Or run a single app
bun dev:web    # marketing only
bun dev:docs   # docs only
```

--------------------------------

### Start NativeLink Local Worker

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/explanations/lre.mdx

Launch the NativeLink local worker using the provided configuration file. This command starts the CAS, AC, scheduler, and worker bound to localhost.

```bash
nativelink ./nativelink-lre.json5
```

--------------------------------

### Build Multi-Worker Docker Container

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/docker-compose/MULTI_WORKER.md

Builds the Docker container for the multi-worker setup.

```sh
docker compose -f
      docker-compose-multi-worker.yml build
```

--------------------------------

### Configure Collector Memory Limiter

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/metrics/README.md

Example configuration to increase the memory limit for the OpenTelemetry collector.

```yaml
memory_limiter:
  limit_mib: 1024  # Increase from 512
```

--------------------------------

### Configure Prometheus Out-of-Order Samples

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/metrics/README.md

Example configuration to increase the out-of-order time window for Prometheus's TSDB.

```yaml
storage:
  tsdb:
    out_of_order_time_window: 1h  # Increase from 30m
```

--------------------------------

### Enter NativeLink Dev Shell

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/contribute/nix.mdx

Clone the NativeLink repository and enter the Nix development shell. The first run downloads the toolchain, subsequent runs are instant. Inside this shell, you have access to the exact toolchain and binaries required for development.

```bash
git clone https://github.com/TraceMachina/nativelink
cd nativelink
nix develop
```

--------------------------------

### Scheduler Naming Configuration

Source: https://github.com/tracemachina/nativelink/blob/main/nativelink-config/examples/README.md

Defines a scheduler within the NativeLink configuration, starting with assigning a user-supplied name like MAIN_SCHEDULER.

```json5
{
  "stores": [],
  "workers": [],
  "schedulers": [
    {
      name: "MAIN_SCHEDULER"
    }
  ],
  "servers": [],
  "global": {},
}
```

--------------------------------

### Basic Worker Configuration

Source: https://github.com/tracemachina/nativelink/blob/main/nativelink-config/examples/README.md

Defines the worker component of the NativeLink configuration, starting with the 'local' object which is currently the only permitted type.

```json5
{
  "stores": [],
  "workers": [{
    "local": {}
  }],
  "schedulers": [],
  "servers": [],
  "global": {},
}
```

--------------------------------

### Generate All NativeLink Crate Documentation

Source: https://github.com/tracemachina/nativelink/blob/main/CONTRIBUTING.md

Run the `docs` command in the nix flake to generate documentation for all `nativelink-*` crates. Alternatively, use `bazel build docs`.

```bash
docs
```

```bash
bazel build docs
```

--------------------------------

### Defining a Store with Name

Source: https://github.com/tracemachina/nativelink/blob/main/nativelink-config/examples/README.md

Configures a store within the NativeLink deployment, starting with assigning a user-defined name like AC_MAIN_STORE.

```json5
{
  "stores": [
    {
      "name": "AC_MAIN_STORE",
    }
  ],
  "workers": [],
  "schedulers": [],
  "servers": [],
  "global": {},
}
```

--------------------------------

### Build Project

Source: https://github.com/tracemachina/nativelink/blob/main/web/README.md

Build all applications within the workspace using Turborepo, or build a single application.

```bash
# Build everything via Turborepo
bun build

# Or build one app
bun --filter @nativelink/web build
bun --filter @nativelink/docs build
```

--------------------------------

### Commit Message Examples

Source: https://github.com/tracemachina/nativelink/blob/main/CONTRIBUTING.md

Illustrates correct and incorrect commit message formats, emphasizing imperative tone and concise titles.

```bash
# Good.
Add some feature

# Bad - trailing period
Add some feature.

# Bad - not imperative
Adds some feature

# Bad - details should be in the body
Add some complex feature and try to put all info in the title

# Bad - commit should be split
Add some feature and actually some other feature as well
```

--------------------------------

### Show Available Nix Templates

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/rbe/nix-templates.mdx

Lists all available NativeLink Nix flake templates. Use this to see which templates can be initialized.

```bash
nix flake show github:TraceMachina/nativelink
```

--------------------------------

### Configure Collector Batch Processor

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/metrics/README.md

Example configuration to reduce the batch send size for the OpenTelemetry collector's batch processor.

```yaml
processors:
  batch:
    send_batch_size: 512  # Reduce from 1024
```

--------------------------------

### Initial NativeLink Build with Bazel

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/contribute/bazel.mdx

Clones the NativeLink repository and runs all tests using Bazel. The first build may take a significant amount of time due to toolchain and dependency compilation.

```bash
git clone https://github.com/TraceMachina/nativelink
cd nativelink
bazel test //...
```

--------------------------------

### Run NativeLink Server with Bazel

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/contribute/bazel.mdx

Builds and runs the NativeLink server binary using Bazel, passing a configuration file path as an argument. This is for executing the server with specific settings.

```bash
bazel run //nativelink -- /path/to/config.json5
```

--------------------------------

### Build Chromium

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/deployment/chromium.mdx

Compile the Chromium project using the configured build files and Reclient.

```bash
autoninja -C out/Default chrome
```

--------------------------------

### Simple Scheduler Configuration

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/configuration/intro.mdx

Sets up a basic scheduler with supported platform properties for OSFamily, container_image, and cpu_count. This is suitable for most common routing needs.

```json5
schedulers: {
  MAIN_SCHEDULER: {
    simple: {
      supported_platform_properties: {
        OSFamily: "exact",
        container_image: "exact",
        cpu_count: "minimum",
      },
    },
  },
}
```

--------------------------------

### Get Latest OCI Image Tag

Source: https://github.com/tracemachina/nativelink/blob/main/SECURITY.md

Retrieves the tag for the latest OCI image from the main branch. This is useful for deploying the most recent version.

```sh
export LATEST=$(nix eval github:TraceMachina/nativelink#image.imageTag --raw)
```

--------------------------------

### Configure Collector Attribute Processor to Drop Labels

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/metrics/README.md

Example configuration to remove an unnecessary label using the OpenTelemetry collector's attribute processor.

```yaml
processors:
  attributes:
    actions:
      - key: unnecessary_label
        action: delete
```

--------------------------------

### Build Documentation for a Single NativeLink Crate

Source: https://github.com/tracemachina/nativelink/blob/main/CONTRIBUTING.md

Build documentation for a specific crate, such as `nativelink-config`, using Bazel.

```bash
bazel build nativelink-config:docs
```

--------------------------------

### Persist tmpfs Mount Across Reboots

Source: https://github.com/tracemachina/nativelink/blob/main/nativelink-config/examples/README.md

Entry to add to /etc/fstab to ensure the tmpfs mount is available after system restarts. This makes the setup persistent.

```bash
tmpfs /mnt/tmpfs/nativelink tmpfs size=50G,mode=1777 0 0
```

--------------------------------

### High-Availability Scheduler Configuration

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/configuration/production.mdx

Configures the scheduler with essential properties for HA. This setup ensures stateless schedulers can manage in-flight actions and recover from restarts.

```json5
schedulers: {
  MAIN_SCHEDULER: {
    simple: {
      supported_platform_properties: {
        OSFamily:        "exact",
        container_image: "exact",
        cpu_count:       "minimum",
        gpu:             "exact",
      },
      max_job_retries: 3,
      worker_timeout_s: 300,
    },
  },
},

```

--------------------------------

### Access Component Lab

Source: https://github.com/tracemachina/nativelink/blob/main/web/README.md

Open the component lab in the marketing app by running the development server and navigating to the /lab route.

```bash
bun dev:web
# open http://localhost:3000/lab
```

--------------------------------

### OTEL Collector Prometheus Exporter Configuration

Source: https://github.com/tracemachina/nativelink/blob/main/deployment-examples/metrics/README.md

Configure the OpenTelemetry Collector to export metrics using the Prometheus exporter. This setup is used when Prometheus scrapes the collector.

```yaml
exporters:
  prometheus:
    endpoint: "0.0.0.0:9090"

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]
```

--------------------------------

### Prometheus Query for Queued Executions

Source: https://github.com/tracemachina/nativelink/blob/main/web/apps/docs/content/docs/deployment/metrics.mdx

Get the current count of active executions in the 'queued' stage. High values may indicate a bottleneck in the execution pipeline.

```text
sum(nativelink_execution_active_count{execution_stage="queued"})
```