Custom Dependencies - Tembo Docs

Start with a setup script

Use a project setup script as the starting point for custom dependencies. Tembo runs the script after cloning your repositories while it builds the project’s prepared environments. Anything the script installs or writes to disk becomes part of those environments. Add your script under Advanced setup when you create or edit a project. See Setup script for details.

tembo.nix is currently in beta and will be available to everyone very soon. If you have beta access, use the sections below to declare system packages and toolchains in your repository.

Prerequisites

You have a repository connected to Tembo.
You know which system packages or language toolchains your project needs.

Create tembo.nix

Create tembo.nix in your repository root with a default dev shell. Tembo uses devShells.x86_64-linux.default in the sandbox.

{
  description = "Tembo Cloud VM Dependencies";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};
      in {
        devShells.default = pkgs.mkShell {
          packages = with pkgs; [
            go
            rustc
            cargo
            jdk
          ];
        };
      }
    );
}

After you commit the file, new Tembo sessions use the dev shell automatically. Agents can then run commands that depend on those packages, such as go test, cargo test, or Java build tools.

Add packages

Add packages to the packages list. For example, this dev shell adds PostgreSQL client tools and pkg-config for projects that compile native dependencies:

{
  description = "Tembo Cloud VM Dependencies";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};
      in {
        devShells.default = pkgs.mkShell {
          packages = with pkgs; [
            postgresql
            pkg-config
            openssl
          ];
        };
      }
    );
}

Configure the shell

Use shellHook when the sandbox needs environment variables for local commands:

{
  description = "Tembo Cloud VM Dependencies";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};
      in {
        devShells.default = pkgs.mkShell {
          packages = with pkgs; [
            nodejs_22
            pnpm
          ];

          shellHook = ''
            export NODE_ENV=development
          '';
        };
      }
    );
}

Keep secrets out of tembo.nix. Add secrets through your sandbox environment variables instead.

How Tembo loads tembo.nix

When Tembo needs your dev shell, it temporarily replaces flake.nix in the repository with the contents of tembo.nix, evaluates the default dev shell, and then restores the original flake.nix. This has a few consequences worth knowing:

tembo.nix must be a complete, self-contained flake. Tembo does not merge it with a flake.nix that your repository already has.
A flake.nix in your repository is left untouched, and Tembo does not use it to build the dev shell. Put everything the sandbox needs in tembo.nix.
Tembo never writes a flake.lock for tembo.nix. Pin nixpkgs to a specific revision in inputs if you need dependency versions to stay stable over time.
Tembo only reads tembo.nix from the root of each cloned repository. Files in subdirectories are ignored.
Unfree packages are allowed, so you can add them without extra configuration.

Dependencies in projects

When a project builds with repository dependency installation enabled, Tembo evaluates tembo.nix once during the build and caches the resulting toolchain in the prepared environment. Sessions started from that project reuse the cached toolchain instead of evaluating the flake again, which is part of why they start faster. Because the toolchain is captured at build time, edits to tembo.nix do not reach project sessions until the environment is rebuilt. Rebuild the project or wait for its daily refresh to pick up the change.

Troubleshooting

Dependencies are missing even though the project build succeeded. If tembo.nix fails to evaluate during a project build, Tembo records the failure and finishes the build without the dependencies rather than failing the whole build. Open the project’s build log and look for the nix develop step. A syntax error, an input that cannot be fetched, or a package name that does not exist in the pinned nixpkgs are the usual causes. Changes to tembo.nix have no effect. Confirm the file is committed and pushed, then rebuild the project environment so the new toolchain is captured.

Tips

Keep tembo.nix focused on system packages and toolchains that your project needs.
Commit the file so Tembo can load it in every new session.
Use projects if installing dependencies still takes meaningful time at the start of each session.

​Start with a setup script

​Prerequisites

​Create tembo.nix

​Add packages

​Configure the shell

​How Tembo loads tembo.nix

​Dependencies in projects

​Troubleshooting

​Tips

Start with a setup script

Prerequisites

Create tembo.nix

Add packages

Configure the shell

How Tembo loads tembo.nix

Dependencies in projects

Troubleshooting

Tips