Deploying to agents


Start by getting your agent running.

Get Deploy Activate Auth Token

  1. Click “Start a Deployment” on your workspace

  2. Write the description of the token, for an example “github actions CD”

  3. Click “Generate”

  4. Copy the token and save it

Write Deploy specification

The following deploys NixOS to the agent named myagent in file deploy.nix:

  pkgs = import <nixpkgs> {};
in pkgs.writeText "cachix-deploy.json" (builtins.toJSON {
  agents = {
    virtualbox = (pkgs.nixos {
      fileSystems."/" = { device = "/dev/disk/by-label/nixos"; };
      boot.loader.grub.devices = ["/dev/sda"];
      boot.loader.grub.enable = true;
      networking.hostName = "myagent";

To fully grasp the JSON specification see the reference.

Activate the deployment

Assuming you’ve created a binary cache called mycache:

  • you have a write token to replace CACHE-TOKEN

  • previously generated token to replace ACTIVATE-TOKEN.

The following snippet will build your machine, push binaries to mycache and deploy your agent:


spec=$(nix-build deploy.nix)
cachix push mycache $spec
cachix deploy activate $spec