Skip to main content

​
Installation methods

NativeLink can be installed using several methods depending on your platform and preferences. Choose the method that best fits your environment:

Docker

Fast to spin up, works on Linux (x86_64), Windows, and macOS

Nix

Built from source, supports Linux, macOS, and WSL2

Cargo

Build from source using Rust’s package manager

​
Docker installation

The fastest way to get started with NativeLink is using the prebuilt Docker images.
Prebuilt images are currently limited to x86_64 systems. For other architectures, use Nix or build from source.

​
Linux and macOS

1

Download the configuration file

curl -O \
  https://raw.githubusercontent.com/TraceMachina/nativelink/v0.7.5/nativelink-config/examples/basic_cas.json5
2

Run the Docker container

# 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:v0.7.5 \
  config

​
Windows

1

Download the configuration file

Invoke-WebRequest `
  -Uri "https://raw.githubusercontent.com/TraceMachina/nativelink/v0.7.5/nativelink-config/examples/basic_cas.json5" `
  -OutFile "basic_cas.json5"
2

Run the Docker container

docker run `
  -v ${PWD}/basic_cas.json5:/config `
  -p 50051:50051 `
  ghcr.io/tracemachina/nativelink:v0.7.5 `
  config
Adjust the path if you’re not running the command from the directory containing basic_cas.json5.

​
Docker Compose

For more complex deployments with multiple services, use Docker Compose:
1

Clone the repository

git clone https://github.com/TraceMachina/nativelink.git
cd nativelink/deployment-examples/docker-compose
2

Start the services

docker-compose up
This starts:
  • NativeLink CAS server (port 50051)
  • NativeLink scheduler (port 50052)
  • NativeLink executor worker
3

Verify the deployment

# Check CAS endpoint
curl http://localhost:50051/status

# Check scheduler endpoint
curl http://localhost:50052/status
The Docker Compose setup is designed for development and testing. For production deployments, see the Kubernetes deployment guide.

​
Nix installation

Nix provides a reproducible build environment and works on Linux, macOS, and WSL2.
Executables built for macOS are dynamically linked against libraries from Nix and won’t work on systems that don’t have these libraries present.

​
Prerequisites

1

Install Nix

Install Nix using the next-generation installer with flake support:
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
For alternative installation methods, see the Nix installation guide.
2

Verify Nix installation

nix --version
Ensure your Nix version supports flakes (Nix 2.4 or later).
1

Download the configuration file

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

Run NativeLink

nix run github:TraceMachina/nativelink ./basic_cas.json5
This command:
  1. Downloads the NativeLink source from GitHub
  2. Builds NativeLink from source
  3. Runs it with your configuration file
The first run will take longer as Nix builds NativeLink from source. Subsequent runs will use the cached build.
To install NativeLink permanently in your Nix profile: 
nix profile install github:TraceMachina/nativelink
Then run it directly: 
nativelink ./basic_cas.json5

​
Using Nix flakes in your project

Add NativeLink to your flake.nix: 
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nativelink.url = "github:TraceMachina/nativelink";
  };

  outputs = { self, nixpkgs, nativelink }: {
    # Use nativelink in your development shell
    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
      buildInputs = [
        nativelink.packages.x86_64-linux.default
      ];
    };
  };
}

​
Build from source with Cargo

Build NativeLink from source using Rust’s Cargo package manager.

​
Prerequisites

1

Install Rust

Install Rust using rustup:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
NativeLink requires Rust 1.87.0 or later.
2

Verify Rust installation

rustc --version
cargo --version
3

Install system dependencies

Install required system dependencies:
sudo apt-get update
sudo apt-get install -y \
  build-essential \
  pkg-config \
  libssl-dev
1

Clone the repository

git clone https://github.com/TraceMachina/nativelink.git
cd nativelink
2

Build NativeLink

Build the release version:
cargo build --release
The binary will be located at target/release/nativelink.
The release build enables optimizations including LTO (Link Time Optimization) for maximum performance. This may take 10-20 minutes depending on your system.
3

Run NativeLink

./target/release/nativelink ./nativelink-config/examples/basic_cas.json5
4

Optional: Install system-wide

Install the binary to your system:
cargo install --path .
Then run from anywhere:
nativelink ./basic_cas.json5

​
Development builds

For development and testing, use a development build: 
# Standard debug build
cargo build

# Run tests
cargo test --all

# Small optimized build for CI (reduces target/ size from ~12GB to ~1GB)
cargo build --profile=smol

​
Build with Bazel

NativeLink can also be built using Bazel: 
# Build NativeLink
bazel build //src/bin/nativelink

# Run NativeLink
bazel run //src/bin/nativelink -- ./nativelink-config/examples/basic_cas.json5

# Run tests
bazel test //...
For more details on building with Bazel, see the Bazel build guide.

​
Verify your installation

Regardless of installation method, verify that NativeLink is working correctly:
1

Check the version

nativelink --version
Expected output:
nativelink 1.0.0-rc2
2

View help information

nativelink --help
This displays:
  • Available command-line options
  • Usage information
  • Configuration file requirements
3

Start with a test configuration

nativelink ./basic_cas.json5
Look for:
Ready, listening on 0.0.0.0:50051
4

Test the health endpoint

In another terminal:
curl http://localhost:50051/status
A successful response indicates NativeLink is running correctly.

​
Container registry

Prebuilt Docker images are available in the GitHub Container Registry:
  • Registry: ghcr.io/tracemachina/nativelink
  • Tags: See available tags
  • Supported platforms: linux/amd64 (x86_64)

​
Image variants

  • v0.7.5 - Specific version release
  • latest - Latest stable release
  • main - Built from the main branch (development)

​
Build your own image

To build a custom Docker image: 
# Clone the repository
git clone https://github.com/TraceMachina/nativelink.git
cd nativelink

# Build the image
docker build -f deployment-examples/docker-compose/Dockerfile -t nativelink:custom .

# Run your custom image
docker run -v $(pwd)/basic_cas.json5:/config -p 50051:50051 nativelink:custom config

​
Next steps

Configuration

Learn how to configure NativeLink for your use case.

Integration

Connect your build tools to NativeLink.

Deployment

Deploy NativeLink to production.

Contributing

Contribute to NativeLink development.

Build docs developers (and LLMs) love

Get started for freeTalk to us