Nix installation

Run from the flake

The release flake exposes separate packages and apps for the HTTP-only client and the runtime-owning service. Pin a release tag for reproducible deployments. Nix downloads the matching GitHub Actions release archive and patches it for the Nix store; it does not compile Scorch locally.

nix run github:Fractal-Tess/scorch/v0.1.3#scorch -- --help
nix run github:Fractal-Tess/scorch/v0.1.3#scorchd -- --help

Install either package into a profile:

nix profile install github:Fractal-Tess/scorch/v0.1.3#scorch
nix profile install github:Fractal-Tess/scorch/v0.1.3#scorchd

For a standalone daemon with Chromium already in its closure:

nix run github:Fractal-Tess/scorch/v0.1.3#scorchd-with-chromium

Enable both on NixOS

Add Scorch as an input, import its module, install scorch, and start scorchd. The default service binds only to loopback.

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    scorch.url = "github:Fractal-Tess/scorch/v0.1.3";
  };

  outputs = { nixpkgs, scorch, ... }: {
    nixosConfigurations.host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        scorch.nixosModules.default
        ({ ... }: {
          programs.scorch = {
            enable = true;
            apiUrl = "http://127.0.0.1:33000";
          };

          services.scorchd = {
            enable = true;
            address = "127.0.0.1";
            port = 33000;
          };
        })
      ];
    };
  };
}

Apply the host configuration and inspect the service:

sudo nixos-rebuild switch --flake .#host
systemctl status scorchd
curl -fsS http://127.0.0.1:33000/ready | jq
scorch search "rust web extraction" --limit 3

Configure service policy

services.scorchd = {
  enable = true;
  browser = "obscura";
  allowedBrowsers = [ "obscura" "chromium" ];
  browserPath = pkgs.chromium + "/bin/chromium";
  obscuraStealth = true;
  maxConcurrency = 4;
  maxResponseBytes = 5 * 1024 * 1024;
  jobTtlSeconds = 900;
  searchEngines = [
    "bing"
    "duckduckgo"
    "naver"
    "wikipedia"
  ];
  logLevel = "scorch=info";
  logFormat = "json";
};

The module asserts that the default browser belongs to the allowlist and that browser and search-engine lists are non-empty. When Chromium is allowed, browserPath must be set and NixOS user namespaces must remain enabled for Chromium's sandbox; do not add --no-sandbox. Authentication and TLS remain the responsibility of an external gateway.

Load search credentials safely

Do not place API keys directly in a Nix expression: evaluated values can enter the world-readable Nix store. Point the module at a runtime secret managed by sops-nix, agenix, or another provisioner that can write a runtime KEY=value file.

services.scorchd = {
  enable = true;
  searchEngines = [ "bing" "brave" "wikipedia" ];
  environmentFile = "/run/secrets/scorchd.env";
};

# /run/secrets/scorchd.env
SCORCH_BRAVE_SEARCH_API_KEY=replace-at-deploy-time

Google requires both SCORCH_GOOGLE_SEARCH_API_KEY and SCORCH_GOOGLE_SEARCH_ENGINE_ID. The module's general environment option is intended only for non-secret overrides.

Home Manager

Use the Home Manager module when only the user-level client is needed. It does not manage scorchd; run the service through NixOS or another process supervisor.

Inside your flake's outputs function:

homeConfigurations.user = home-manager.lib.homeManagerConfiguration {
  pkgs = nixpkgs.legacyPackages.x86_64-linux;
  modules = [
    scorch.homeManagerModules.default
    {
      home.username = "user";
      home.homeDirectory = "/home/user";
      home.stateVersion = "26.05";
      programs.scorch = {
        enable = true;
        apiUrl = "http://127.0.0.1:33000";
      };
    }
  ];
};

Flake outputs

nix flake show github:Fractal-Tess/scorch/v0.1.3