Skip to main content
NativeLink provides full support for Buck2’s Remote Execution API, enabling distributed builds and caching for Buck2 projects.

​
Prerequisites

  • Buck2 installed (latest stable version)
  • A running NativeLink instance (see Quickstart)
  • Basic understanding of Buck2 build configuration

​
Configuration

Buck2’s remote execution is configured through the .buckconfig file in your project root.

​
Basic Setup

1

Create or update .buckconfig

Add the following remote execution configuration:
.buckconfig
[cells]
root = .

[buck2_re_client]
engine_address = localhost:50051
action_cache_address = localhost:50051
cas_address = localhost:50051
tls = false
instance_name = main

[build]
execution_platforms = root//platforms:platforms
2

Create platform definitions

Define your execution platforms in platforms/BUCK:
platforms/BUCK
load(":defs.bzl", "platforms")

platforms(
    name = "platforms",
)
Create platforms/defs.bzl:
platforms/defs.bzl
def platforms(name):
    native.platform(
        name = "linux-x86_64",
        constraint_values = [
            "ovr_config//os/constraints:linux",
            "ovr_config//cpu/constraints:x86_64",
        ],
    )

    native.platform(
        name = "platforms",
        deps = [":linux-x86_64"],
    )
3

Create .buckroot

Ensure your project has a .buckroot file in the repository root (can be empty):
touch .buckroot
Configure NativeLink to handle Buck2 requests. Here’s a configuration example:
buck2_cas.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: {
          max_bytes: "1gb",
        },
      },
    },
    {
      name: "WORKER_FAST_SLOW_STORE",
      fast_slow: {
        fast: {
          filesystem: {
            content_path: "/tmp/nativelink/data-worker-test/content_path-cas",
            temp_path: "/tmp/nativelink/data-worker-test/tmp_path-cas",
            eviction_policy: {
              max_bytes: "10gb",
            },
          },
        },
        slow: {
          noop: {},
        },
      },
    },
  ],
  schedulers: [
    {
      name: "MAIN_SCHEDULER",
      simple: {
        supported_platform_properties: {
          cpu_count: "minimum",
          cpu_arch: "exact",
          OSFamily: "priority",
          "container-image": "priority",
        },
      },
    },
  ],
  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"],
          },
          cpu_arch: {
            values: ["x86_64"],
          },
          OSFamily: {
            values: [""],
          },
        },
      },
    },
  ],
  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",
      listener: {
        http: {
          socket_address: "0.0.0.0:50061",
        },
      },
      services: {
        worker_api: {
          scheduler: "MAIN_SCHEDULER",
        },
        admin: {},
        health: {},
      },
    },
  ],
}
1

Start NativeLink

nativelink buck2_cas.json5
2

Build with Buck2

Buck2 automatically uses remote execution when configured:
buck2 build //...
3

Verify remote execution

Check Buck2’s output for remote execution indicators:
Action stats:
- Remote executions: 42
- Cache hits: 15

​
Configuration Options

​
Remote Execution Client

The [buck2_re_client] section supports the following options: 
[buck2_re_client]
engine_address = localhost:50051
action_cache_address = localhost:50051
cas_address = localhost:50051
tls = false
instance_name = main

​
Key Configuration Fields

FieldDescription
engine_addressRemote execution scheduler endpoint
action_cache_addressAction cache service endpoint
cas_addressContent Addressable Storage endpoint
tlsEnable TLS (true/false)
instance_nameInstance name for multi-tenant setups
tls_ca_certPath to CA certificate for TLS
tls_client_certPath to client certificate for mTLS
tls_client_keyPath to client key for mTLS

​
Platform Properties

Define execution requirements through platform properties:
platforms/defs.bzl
def platforms(name):
    native.platform(
        name = "linux-x86_64-large",
        constraint_values = [
            "ovr_config//os/constraints:linux",
            "ovr_config//cpu/constraints:x86_64",
        ],
        exec_properties = {
            "cpu_count": "8",
            "memory_kb": "16000000",
        },
    )

​
Testing Your Configuration

1

Clean build

buck2 clean
buck2 build //...
2

Verify cache hits

Rebuild to see cache hits:
buck2 clean
buck2 build //...
Look for cache hit statistics in the output.
3

Check remote execution

Verify actions are executed remotely:
buck2 build //... --show-output

​
Troubleshooting

​
Connection errors

Verify NativeLink is running and accessible: 
grpcurl -plaintext localhost:50051 list

​
TLS handshake failures

Ensure certificates are correctly configured: 
openssl s_client -connect cache.example.com:50051

​
Platform not found

Verify platform definitions exist and are referenced correctly in .buckconfig.

​
Example Project Structure

my-buck2-project/
├── .buckroot
├── .buckconfig
├── platforms/
│   ├── BUCK
│   └── defs.bzl
├── src/
│   └── BUCK
└── tests/
    └── BUCK

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us