Introduction
Celler is a self-hosted binary cache for Nix. Push your build results to it, and Nix on your other machines and in CI downloads them instead of building them again.
Celler is working towards a stable release. Until then, the configuration and APIs may still change between releases. We are looking for more testers!
Important
Upgrading from Attic or an older Celler? The configuration format has changed. See the changelog and the Attic migration guide.
Features
- Works with plain Nix: Nix pulls from a Celler cache like from any other binary cache.
The
cellerclient pushes store paths and sets up Nix for you. - Many caches, one server: Create a private cache for yourself, one for your team, and a public one for your project. Caches are isolated: what happens in one cache can’t affect the others.
- Stores everything once: If the same data is pushed to several caches, Celler stores it only once. Optional chunking also deduplicates data shared between similar store paths.
- Fits any size: From a single-machine setup with local storage to several API servers in front of S3-compatible storage, Celler scales to any size.
- Signing keys stay on the server: The server signs store paths when Nix downloads them. People who push to a cache never see its signing key.
- Automatic cleanup: Celler can delete store paths that haven’t been used for a while. You choose how long to keep them, per cache.
Where to Go Next
- Try it out: The Tutorial runs a Celler server on your machine in about 15 minutes.
- Use a cache someone else runs: See the User Guide.
- Run your own server: See the Admin Guide.
- Ask questions or share feedback: Chat with us on Matrix in #celler:chat.x86.lol.
About the Name
Celler is Catalan for a wine cellar, the place where you store all your valuable wines. Celler is where you store your valuable build results.
And of course, Celler is a fork of Attic, the self-hosted Nix binary cache by Zhaofeng Li.
Tutorial
In this tutorial, you run a Celler server on your own machine, create a binary cache, push a store path to it, and pull it back. You don’t need NixOS, S3, or a database server: everything lives in a single directory.
You need:
- Nix with flakes enabled
- Two terminal windows (or tabs)
This setup is for trying Celler out. To run Celler for real, follow Deploying to NixOS afterwards.
Get Celler
You use two terminals in this tutorial:
- The server terminal runs the Celler server.
- The client terminal is where you run all other commands.
Open both terminals, and in each one, start a shell that has celler, cellerd, and openssl:
$ nix shell github:celler-cache/celler nixpkgs#openssl
Start the Server
In the server terminal, create a directory for the server’s data:
$ mkdir celler-demo
$ cd celler-demo
Celler uses signed tokens (JWTs) to decide who may do what. Generate a key pair to sign them. The server only needs the public key; you keep the private key to create tokens:
$ openssl genrsa -out private-key.pem 4096
$ openssl rsa -in private-key.pem -pubout -out public-key.pem
writing RSA key
Create server.toml with the following content:
listen = "[::]:8080"
# Keep the database in a SQLite file in this directory.
[database]
url = "sqlite://server.db?mode=rwc"
# Store the cached files in the storage/ directory.
[storage]
type = "local"
path = "storage"
# Accept tokens signed with our private key.
[jwt]
rs256-public-key-file = "public-key.pem"
All options are described in the server configuration reference.
Start the server:
$ cellerd -f server.toml
Celler 0.1.0 (release)
Running migrations...
* Migrating NARs to chunks...
* Migrating NAR schema...
Starting API server...
Listening on [::]:8080...
Leave the server running. Use the client terminal for the rest of the tutorial.
Create a Cache
In the client terminal, go to the celler-demo directory, because it contains the private key.
Then create a token for a user called alice.
It allows her to create the cache hello, configure it, push to it, and pull from it:
$ cd celler-demo
$ celler admin make-token --signing-key private-key.pem --sub alice --validity '3 months' \
--pull hello --push hello \
--create-cache hello --configure-cache hello --configure-cache-retention hello
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...
Log in to the server with this token.
local is the name the client uses to refer to this server:
$ celler login local http://localhost:8080 eyJ...
✍️ Configuring server "local"
Now create the cache:
$ celler cache create hello
✨ Created cache "hello" on "local"
Push to the Cache
Push the celler package itself to the cache:
$ celler push hello $(which celler)
⚙️ Pushing 1 paths to "hello" on "local" (0 already cached, 6 in upstream)...
✅ h6pjy7d28mj6wihhn4fz2kqx7x9wy4my-celler-0.1.0 (50.09 MiB, 21.54 MiB/s)
celler push uploads the store path together with everything it depends on (its closure).
Here, it skipped six dependencies because they are already available from cache.nixos.org (“in upstream”).
You can change this behavior per cache.
Pull from the Cache
Configure Nix to use the new cache:
$ celler use hello
Configuring Nix to use "hello" on "local":
+ Substituter: http://localhost:8080/hello
+ Trusted Public Key: hello:HE3fhNGlAymSg6uGGrMMZGC20Of10/p8aZClxFzJ4rE=
+ Access Token
This adds the cache, its public key, and your access token to ~/.config/nix/nix.conf and ~/.config/nix/netrc.
celler is already in your Nix store, so Nix would not download it again.
To see the download happen, let Nix fetch it into a separate store in the nix-demo directory:
$ nix-store --store $PWD/nix-demo -r $(which celler)
copying path '/nix/store/h6pjy7d28mj6wihhn4fz2kqx7x9wy4my-celler-0.1.0' from 'http://localhost:8080/hello'...
warning: you did not specify '--add-root'; the result might be removed by the garbage collector
/nix/store/h6pjy7d28mj6wihhn4fz2kqx7x9wy4my-celler-0.1.0
The copying path ... from 'http://localhost:8080/hello' line shows that Nix downloaded it from your cache.
Note
To pull into your real
/nix/storeon a multi-user Nix installation, your user must be trusted by the Nix daemon, or the cache must be configured system-wide. See the User Guide.
Make the Cache Public
So far, only someone with a token can read from the cache:
$ curl http://localhost:8080/hello/nix-cache-info
{"code":401,"error":"Unauthorized","message":"Unauthorized."}
Make it public, so that anyone can pull from it without a token:
$ celler cache configure hello --public
✅ Configured "hello" on "local"
$ curl http://localhost:8080/hello/nix-cache-info
WantMassQuery: 1
StoreDir: /nix/store
Priority: 41
Pushing still requires a token with push permission.
Clean Up Old Paths
Without limits, a binary cache grows forever. You can set a retention period: store paths that nobody has pushed or pulled for that long are deleted by the garbage collector.
Set the retention period to one second, so we don’t have to wait:
$ celler cache configure hello --retention-period '1s'
✅ Configured "hello" on "local"
The server runs garbage collection every 12 hours. Instead of waiting, run it once by hand:
$ cellerd -f server.toml --mode garbage-collector-once
The store path is gone from the cache:
$ curl http://localhost:8080/hello/h6pjy7d28mj6wihhn4fz2kqx7x9wy4my.narinfo
{"code":404,"error":"NoSuchObject","message":"The requested object does not exist."}
Reset the retention period to the server default, which is to keep everything:
$ celler cache configure hello --reset-retention-period
✅ Configured "hello" on "local"
Clean Up
When you are done, stop the server with Ctrl+C in the server terminal.
Then remove the celler-demo directory.
Nix makes the files in nix-demo read-only, so make them writable first:
$ cd ..
$ chmod -R u+w celler-demo
$ rm -rf celler-demo
celler use changed your Nix configuration.
Remove the http://localhost:8080/hello substituter and the hello:... key from ~/.config/nix/nix.conf.
Otherwise Nix keeps trying to reach the stopped server.
If you do the tutorial again, the new cache gets a new signing key, but Nix may still remember the old one for a while.
If Nix reports that a path is not signed by any of the keys in 'trusted-public-keys', delete ~/.cache/nix.
Summary
You have:
- Run a Celler server with local storage
- Created a token and a cache
- Pushed a store path and pulled it back with Nix
- Made the cache public
- Removed old paths with garbage collection
What’s Next
- User Guide: use caches that someone else runs.
- Deploying to NixOS: run Celler as a service.
- Concepts: how Celler stores, deduplicates, and protects your data.
celler admin make-token --help: all token permissions, including wildcards like--push 'alice-*'.
User Guide
Logging In
You should have received an celler login command from an admin like the following:
$ celler login central https://celler.domain.tld/ eyJ...
The celler client can work with multiple servers at the same time.
To select the foo cache from server central, use one of the following:
foo, if thecentralserver is configured as the defaultcentral:foo
To configure the default server, set default-server in ~/.config/celler/config.toml.
Enabling a Cache
To configure Nix to automatically use cache foo:
$ celler use foo
This adds the binary cache to your ~/.config/nix/nix.conf and configures the credentials required to access it.
If you wish to configure Nix manually, you can view the binary cache endpoint and the cache public key:
$ celler cache info foo
Public: true
Public Key: foo:WcnO6s4aVkB6CKRaPPpKvHLZykWXASV6c+/Ssg8uQEY=
Binary Cache Endpoint: https://celler.domain.tld/foo
Store Directory: /nix/store
Priority: 41
Upstream Cache Keys: ["cache.nixos.org-1"]
Retention Period: Global Default
On NixOS, you can configure the cache declaratively in your system configuration with the above information:
{
nix.settings = {
substituters = [
"https://celler.domain.tld/foo"
];
trusted-public-keys = [
"foo:WcnO6s4aVkB6CKRaPPpKvHLZykWXASV6c+/Ssg8uQEY="
];
};
}
Disabling a Cache
To configure Nix to no longer use a cache, remove the corresponding entries from the list of substituters and trusted-public-keys in ~/.config/nix/nix.conf
Pushing to the Cache
To push a store path to cache foo:
$ celler push foo /nix/store/...
Other examples include:
$ celler push foo ./result
$ celler push foo /run/current-system
Admin Guide
Note
This section is still pretty barebones. Please contribute if you can help improve it.
This section describes how to set up and administer a Celler Server. For a quick start, read the Tutorial.
- Deploying to NixOS - Deploying to a NixOS machine
- Chunking - Configuring Content-Defined Chunking data deduplication in Celler
- Migration from Attic - Migrating from Attic to Celler
Deploying to NixOS
Celler provides a NixOS module that allows you to deploy the Celler Server on a NixOS machine.
Prerequisites
- A machine running NixOS
- (Optional) A dedicated bucket on S3 or a S3-compatible storage service
- You can either set up Garage or use a hosted service like Backblaze B2 and Cloudflare R2.
- (Optional) A PostgreSQL database
Generating the Credentials File
The RS256 JWT secret can be generated with the openssl utility:
$ nix shell nixpkgs#openssl
$ openssl genrsa -out private-key.pem 4096
$ openssl rsa -in private-key.pem -pubout -out public-key.pem
Keep the private-key.pem file in a secure location. You need it to sign tokens using celler admin make-token.
The public key will be part of the server configuration.
Importing the Module
You can import the module in one of two ways:
- Ad-hoc: Import the
nixos/cellerd.nixfrom the repository. - Flakes: Add
github:celler-cache/celleras an input, then importceller.nixosModules.cellerd.
Configuration
{
services.cellerd = {
enable = true;
# Replace with absolute path to your environment file
environmentFile = "/etc/cellerd.env";
settings = {
listen = "[::]:8080";
jwt = {
rs256-public-key-file = ./public-key.pem;
};
# Chunking is off by default. To enable it, see the Chunking page.
};
};
}
settings accepts all options from the server configuration reference.
Unless you configure them, the module uses SQLite and local storage in /var/lib/cellerd.
After the new configuration is deployed, the Celler Server will be accessible on port 8080. It’s highly recommended to place it behind a reverse proxy like NGINX to provide HTTPS.
Chunking
Celler can split uploaded NARs into chunks with the FastCDC algorithm, so that data shared between NARs is stored only once. This saves storage space, but makes Celler slower and can get it throttled by S3 providers.
Important
Only enable chunking if you need the storage savings. If you enable it, start with the recommended values.
All chunking options are described in the server configuration reference.
Why Chunking Has a Cost
Without chunking, Celler can usually let clients download store paths directly from the storage backend, using pre-signed URLs. The Celler server doesn’t have to handle the data itself.
With chunking, the Celler server downloads every chunk of a NAR from the storage backend and puts the NAR back together for the client. This is much more work for the server.
Every chunk is also a separate request to the storage backend. The smaller the chunks, the more requests Celler sends. Hosted S3 providers limit how many requests you can send. If Celler hits that limit, downloads become very slow or fail.
Enabling and Disabling Chunking
Chunking is off unless the server configuration has a [chunking] section.
To enable it, add the section, for example with the
recommended values. To disable it again, remove the
section.
This only affects new uploads. NARs that are already chunked stay chunked. Celler still stores identical NARs only once, even with chunking disabled.
Recommended Values
These values have proven to work well in a stable setup:
[chunking]
# Only chunk NARs that are 4 MiB or larger.
nar-size-threshold = 4194304 # 4 MiB
min-size = 2097152 # 2 MiB
avg-size = 8388608 # 8 MiB
max-size = 16777216 # 16 MiB
Using Smaller Chunks
You can experiment with smaller chunks. They deduplicate better, so Celler needs less storage space. In exchange, Celler sends more requests to the storage backend, which makes it slower. With a hosted S3 provider, small chunks will cause throttling.
If you run your own S3 server, such as Garage, or use local storage, nobody throttles your requests. Smaller chunks can be a good trade-off there, as long as the performance is good enough for you.
For example, these values use chunks that are about 64 times smaller than the recommended ones:
[chunking]
nar-size-threshold = 131072 # 128 KiB
min-size = 65536 # 64 KiB
avg-size = 131072 # 128 KiB
max-size = 262144 # 256 KiB
Measure how fast downloads are and how much storage you save before you settle on smaller values.
Changing Values Later
Choose your values before you upload a lot of data. If you change them later, new uploads are split at different points, so they share few chunks with existing data. Deduplication will be worse for a while.
Migration from Attic
This guide explains how to migrate from Attic to Celler.
Migration Guide
Caution
The migration process is not regularly tested. Use at your own risk and please backup your database before proceeding.
Note
The Celler server’s API is deliberately not compatible with the Attic CLI tool. Use the Celler CLI instead.
Step 0: Back Up Your Database
Before proceeding, make sure to backup your database.
Step 1: Adapt Server Configuration
Adapt your NixOS configuration to use Celler instead of Attic:
- Point your Flake input to
github:celler-cache/celler. - Rename
services.atticdtoservices.cellerd.
JWT secrets are not configured via environment variables in Celler. Existing BASE64-encoded RS256 private keys have to be decoded via base64 -d. See the deployment guide for how to convert it to a public key and add it to the configuration.
Similarly, HS256 keys can be decoded via base64 -d and passed to services.cellerd.settings.jwt.hs256-secret-key in the server config.
Step 2: Adapt Client Configuration
Client configuration needs to be adapted as well.
- Point your Flake input to
github:celler-cache/celler. - Replace the
atticpackage withcellerin your client configuration.
Concepts
This section explains how Celler works and why it is designed the way it is. You don’t need it to use Celler, but it helps when you plan a deployment or tune it.
- Architecture: how caches, the global store, and the server components fit together
- Deduplication and Compression: how Celler avoids storing the same data twice
- Security Model: tokens, signing, and how caches are isolated from each other
Architecture
Caches Are Views of a Global Store
A Celler server hosts many binary caches. Each cache looks like an ordinary Nix binary cache to Nix, but the caches don’t store data themselves. All data lives in two global stores shared by every cache on the server:
Cache "alice" Cache "team" Cache "ci" ← store path metadata, per cache
│ │ │ │
▼ ▼ ▼ ▼
┌──────────────────────────────────────────────┐
│ Global NAR Store │ ← one entry per unique NAR
└──────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌──────────────────────────────────────────────┐
│ Global Chunk Store │ ← the actual bytes, in S3 or on disk
└──────────────────────────────────────────────┘
- Cache: holds the metadata of the store paths pushed to it: store path, references, deriver, and so on. Each entry points to a NAR in the global NAR store.
- Global NAR Store: one entry per unique NAR (the archive format Nix uses for store paths), identified by its hash. A NAR is made of one or more chunks.
- Global Chunk Store: the stored data. Chunks are identified by their hash and stored in the configured storage backend.
When you push a store path that already exists on the server, possibly in another cache, Celler only adds a reference from your cache to the existing NAR. See Deduplication and Compression.
Because the global stores contain only content-addressed data without any metadata, caches can’t affect each other. See Security Model.
Server Components
cellerd has two long-running components:
- API server: serves the binary caches to Nix, and handles uploads and cache management from the
cellerclient. It keeps no state of its own, so you can run several API servers behind a load balancer. - Garbage collector: periodically deletes data that is no longer needed. Only run one garbage collector per server.
Both use a database (SQLite or PostgreSQL) for metadata, and a storage backend (local directory or S3) for chunks.
By default, cellerd runs in monolithic mode, which runs both components in one process.
For bigger setups, run them separately with --mode api-server and --mode garbage-collector.
With several API servers, use PostgreSQL and S3, so that all servers share the same database and storage.
Garbage Collection
Each cache can have a retention period (or use the server’s default-retention-period).
Because the data is shared between caches, garbage collection happens in three steps:
- Cache: Store paths that were neither pushed nor pulled within the retention period are removed from the cache. This only removes the reference to the NAR; no storage is freed yet.
- Global NAR Store: NARs that no cache references anymore are deleted.
- Global Chunk Store: Chunks that no NAR references anymore are deleted from the storage backend. Only this step frees storage space.
A NAR that was removed from one cache stays available in all other caches that reference it.
Deduplication and Compression
Nix stores lots of similar data. Two versions of the same package often differ in only a few files, and the same package often ends up in several caches. Celler deduplicates on two levels so it stores this data only once.
NAR-Level Deduplication
Every NAR is identified by its hash. If someone uploads a NAR that the server already has, in any cache, Celler doesn’t store it again. It only adds a reference from the cache to the existing NAR.
This happens on the server and is invisible to the client. By default, the client still has to upload the full NAR to prove that it has the data. See Proof of Possession.
Chunk-Level Deduplication
If chunking is enabled, new NARs are split into chunks with the FastCDC algorithm. FastCDC places chunk boundaries based on the content, so a small change in a file only affects the chunks around the change. Chunks that already exist are not stored again.
When Nix downloads a chunked NAR, cellerd reads its chunks from the storage backend and streams them to the client as one NAR.
NARs smaller than nar-size-threshold are stored as a single chunk; NAR-level deduplication still applies to them.
Chunking is optional and costs performance. See Chunking for the trade-offs.
Why Chunk Whole NARs Instead of Individual Files?
Celler splits the entire uncompressed NAR, ignoring the boundaries of the files inside it.
The NARs that benefit the most from deduplication, such as VSCode or Zoom, often contain thousands of small files.
Storing each file separately would mean fetching thousands of objects from the storage backend to rebuild a single NAR, which is slow and expensive.
Chunking the whole NAR lets small files share a chunk and keeps the number of chunks manageable.
casync takes the same approach.
The Tvix store protocol, in contrast, chunks individual files. Celler’s design is driven by making good use of existing platforms, such as S3, and their practical limits.
Compression
The server compresses each chunk before writing it to the storage backend (zstd by default, see [compression]).
Deduplication uses the hash of the uncompressed chunk, together with the compression type.
If you change the compression type, new uploads don’t reuse chunks stored with the old type.
NAR-level deduplication isn’t affected.
┌───────────────────────────────────►Chunk Hash
│
│
├───────────────────────────────────►Chunk Size
│
┌───────┴────┐ ┌──────────┐ ┌───────────┐
Chunk Stream──►│Chunk Hasher├─►│Compressor├─►│File Hasher├─►File Stream─►S3
└────────────┘ └──────────┘ └─────┬─────┘
│
├───────►File Hash
│
│
└───────►File Size
Missing or Corrupt Chunks
If a chunk is deleted from the database, every NAR that uses it becomes unavailable and the server responds with an error (503). This fixes itself once someone uploads any NAR that contains the chunk again.
At the moment, Celler can’t detect on its own whether a chunk in the storage backend is corrupt or missing. Telling temporary storage errors apart from permanent ones is difficult.
Security Model
Authentication with Tokens
Clients authenticate with JSON Web Tokens (JWTs). A token contains everything the server needs to know: who the user is, when the token expires, and which caches it may access with which permissions. The server checks the token’s signature and doesn’t store anything about users or sessions. That’s why API servers can be replicated freely.
Permissions are granted per cache name pattern, for example --push 'alice-*'.
A token only has the permissions it was created with.
For example, a token that can push and pull can’t create caches.
The available permissions are: pull, push, delete store paths, create caches, configure caches, configure retention, and destroy caches.
See celler admin make-token --help in the celler CLI reference.
Tokens are signed either with an RSA key pair (RS256) or with a shared secret (HS256). With RS256, the server only has the public key, so a compromised server can’t be used to create new tokens.
Because tokens are not stored on the server, you can’t revoke a single token. Give tokens a limited validity.
Managed Signing
Nix only accepts store paths from a binary cache if they are signed by a key it trusts. In Celler, each cache has its own signing key, which the server keeps. The server signs store paths when they are downloaded.
Users who push to a cache never have access to the signing key. They can add paths to the cache, but can’t sign anything on their own.
Isolation Between Caches
Caches on the same server don’t trust each other. The metadata of a store path, such as its name, references, and deriver, belongs to a single cache. The global stores only contain data identified by its hash, without any metadata.
So if someone uploads a path with wrong or malicious metadata, only their own cache is affected.
Proof of Possession
When a client uploads a NAR that the server already has, it still has to upload the full NAR. The server hashes the data and throws it away instead of storing it again.
This prevents a user from getting access to a NAR in another cache just by knowing its hash. Without this check, anyone who knows the hash of a private NAR on the server could add it to their own cache and download it.
You can turn this off with require-proof-of-possession = false in the server configuration.
Uploads of NARs that the server already has then complete immediately.
Only do this if all users of the server trust each other.
FAQs
Does It Replace Cachix?
No, it does not. Cachix is an awesome product and the direct inspiration for the user experience of Celler. It works at a much larger scale than Celler and is a proven solution. Numerous open-source projects in the Nix community use Cachix to share publicly-available binaries.
Celler provides a similar user experience at a much smaller scale (personal or team use).
What Happens If a User Uploads a Path That Is Already on the Server?
The user still uploads the full path to prove they have it, but the server doesn’t store it again. It adds a reference from the user’s cache to the existing data. See Deduplication and Compression and Proof of Possession.
What Happens If a User Uploads a Path with Incorrect or Malicious Metadata?
It only affects their own cache. See Isolation Between Caches.
How Is Authentication Handled?
With signed tokens (JWTs) that contain the user’s permissions. See Authentication with Tokens.
How Does Deduplication Work?
On two levels: whole NARs and chunks of NARs. See Deduplication and Compression.
What Happens If a Chunk Is Corrupt or Missing?
NARs that contain it become unavailable until someone uploads the chunk again. See Missing or Corrupt Chunks.
Reference
This section contains detailed listings of options and parameters accepted by Celler:
celler CLI
The following are the help messages that will be printed when you invoke any sub-command with --help:
celler
Celler binary cache client Usage: celler <COMMAND> Commands: login Log into a Celler server use Configure Nix to use a binary cache push Push closures to a binary cache cache Manage caches on a Celler server watch-store Watch the Nix Store for new paths and upload them to a binary cache admin Commands for managing the Celler server help Print this message or the help of the given subcommand(s) Options: -h, --help Print help -V, --version Print version
celler login
Log into a Celler server Usage: celler login [OPTIONS] <NAME> <ENDPOINT> [TOKEN] Arguments: <NAME> Name of the server <ENDPOINT> Endpoint of the server [TOKEN] Access token [env: CELLER_TOKEN=] Options: --set-default Set the server as the default -h, --help Print help -V, --version Print version
celler use
Configure Nix to use a binary cache Usage: celler use <CACHE> Arguments: <CACHE> The cache to configure. This can be either `servername:cachename` or `cachename` when using the default server. Options: -h, --help Print help (see a summary with '-h') -V, --version Print version
celler push
Push closures to a binary cache Usage: celler push [OPTIONS] <CACHE> [PATHS]... Arguments: <CACHE> The cache to push to. This can be either `servername:cachename` or `cachename` when using the default server. [PATHS]... The store paths to push Options: --stdin Read paths from the standard input --no-closure Push the specified paths only and do not compute closures --ignore-upstream-cache-filter Ignore the upstream cache filter -j, --jobs <JOBS> The maximum number of parallel upload processes [default: 5] -h, --help Print help (see a summary with '-h') -V, --version Print version
celler watch-store
Watch the Nix Store for new paths and upload them to a binary cache Usage: celler watch-store [OPTIONS] <CACHE> Arguments: <CACHE> The cache to push to. This can be either `servername:cachename` or `cachename` when using the default server. Options: --ignore-upstream-cache-filter Ignore the upstream cache filter -j, --jobs <JOBS> The maximum number of parallel upload processes [default: 5] -h, --help Print help (see a summary with '-h') -V, --version Print version
celler cache
Manage caches on a Celler server Usage: celler cache <COMMAND> Commands: create Create a cache configure Configure a cache destroy Destroy a cache info Show the current configuration of a cache help Print this message or the help of the given subcommand(s) Options: -h, --help Print help -V, --version Print version
celler cache create
Create a cache. You need the `create_cache` permission on the cache that you are creating. Usage: celler cache create [OPTIONS] <CACHE> Arguments: <CACHE> Name of the cache to create. This can be either `servername:cachename` or `cachename` when using the default server. Options: --public Make the cache public. Public caches can be pulled from by anyone without a token. Only those with the `push` permission can push. By default, caches are private. --priority <PRIORITY> The priority of the binary cache. A lower number denotes a higher priority. <https://cache.nixos.org> has a priority of 40. [default: 41] --upstream-cache-key-name <NAME> The signing key name of an upstream cache. When pushing to the cache, paths signed with this key will be skipped by default. Specify this flag multiple times to add multiple key names. [default: cache.nixos.org-1] -h, --help Print help (see a summary with '-h') -V, --version Print version
celler cache configure
Configure a cache. You need the `configure_cache` permission on the cache that you are configuring. Usage: celler cache configure [OPTIONS] <CACHE> Arguments: <CACHE> Name of the cache to configure Options: --regenerate-keypair Regenerate the signing keypair. The server-side signing key will be regenerated and all users will need to configure the new signing key in `nix.conf`. --public Make the cache public. Use `--private` to make it private. --private Make the cache private. Use `--public` to make it public. --priority <PRIORITY> The priority of the binary cache. A lower number denotes a higher priority. <https://cache.nixos.org> has a priority of 40. --upstream-cache-key-name <NAME> The signing key name of an upstream cache. When pushing to the cache, paths signed with this key will be skipped by default. Specify this flag multiple times to add multiple key names. --retention-period <PERIOD> Set the retention period of the cache. You can use expressions like "2 years", "3 months" and "1y". --reset-retention-period Reset the retention period of the cache to global default -h, --help Print help (see a summary with '-h') -V, --version Print version
celler cache destroy
Destroy a cache. Destroying a cache causes it to become unavailable but the underlying data may not be deleted immediately. Depending on the server configuration, you may or may not be able to create the cache of the same name. You need the `destroy_cache` permission on the cache that you are destroying. Usage: celler cache destroy [OPTIONS] <CACHE> Arguments: <CACHE> Name of the cache to destroy Options: --no-confirm Don't ask for interactive confirmation -h, --help Print help (see a summary with '-h') -V, --version Print version
celler cache info
Show the current configuration of a cache Usage: celler cache info <CACHE> Arguments: <CACHE> Name of the cache to query Options: -h, --help Print help -V, --version Print version
celler admin make-token
Generate a new token. For example, to generate a token for Alice with read-write access to any cache starting with `dev-` and read-only access to `prod`, expiring in 2 years: $ celler admin make-token --signing-key key.pem --sub "alice" --validity "2y" --pull "dev-*" --push "dev-*" --pull "prod" Usage: celler admin make-token [OPTIONS] --signing-key <SECRET_KEY> --sub <SUB> --validity <VALIDITY> Options: --signing-key <SECRET_KEY> The signing key to use for the token. For RS256 specify the path of a PEM file containing the secret key. For HS256 specify a file that contains the raw secret key (not BASE64-encoded). --signing-algorithm <SIGNING_ALGORITHM> The signing algorithm to use for the token [default: rs256] [possible values: rs256, hs256] --sub <SUB> The subject of the JWT token --issuer <ISSUER> The `iss` claim of the JWT --audience <AUDIENCE> The `aud` claim of the JWT. Can be specified multiple times to allow multiple audiences. --validity <VALIDITY> The validity period of the JWT token. You can use expressions like "2 years", "3 months" and "1y". --dump-claims Dump the claims without signing and encoding it --pull <PATTERN> A cache that the token may pull from. The value may contain wildcards. Specify this flag multiple times to allow multiple patterns. --push <PATTERN> A cache that the token may push to. The value may contain wildcards. Specify this flag multiple times to allow multiple patterns. --delete <PATTERN> A cache that the token may delete store paths from. The value may contain wildcards. Specify this flag multiple times to allow multiple patterns. --create-cache <PATTERN> A cache that the token may create. The value may contain wildcards. Specify this flag multiple times to allow multiple patterns. --configure-cache <PATTERN> A cache that the token may configure. The value may contain wildcards. Specify this flag multiple times to allow multiple patterns. --configure-cache-retention <PATTERN> A cache that the token may configure retention/quota for. The value may contain wildcards. Specify this flag multiple times to allow multiple patterns. --destroy-cache <PATTERN> A cache that the token may destroy. The value may contain wildcards. Specify this flag multiple times to allow multiple patterns. -h, --help Print help (see a summary with '-h') -V, --version Print version
cellerd CLI
The following are the help messages that will be printed when you invoke any sub-command with --help:
cellerd
Nix binary cache server Usage: cellerd [OPTIONS] Options: -f, --config <CONFIG> Path to the config file -l, --listen <LISTEN> Socket address to listen on. This overrides `listen` in the config. --mode <MODE> Mode to run Possible values: - monolithic: Run all components - api-server: Run the API server - garbage-collector: Run the garbage collector periodically - db-migrations: Run the database migrations then exit - garbage-collector-once: Run garbage collection then exit - check-config: Check the configuration then exit [default: monolithic] --tokio-console Whether to enable tokio-console. The console server will listen on its default port. -h, --help Print help (see a summary with '-h') -V, --version Print version
Server Configuration
cellerd reads its configuration from a TOML file.
It uses the file given with -f/--config.
Without that flag, it reads $XDG_CONFIG_HOME/celler/server.toml (usually ~/.config/celler/server.toml).
On NixOS, you don’t write this file yourself.
The services.cellerd.settings option generates it, using the same names as below.
See Deploying to NixOS.
To check a configuration file without starting the server, run:
$ cellerd -f server.toml --mode check-config
Unknown options at the top level are rejected, so typos are caught early.
Minimal Example
[database]
url = "sqlite:///var/lib/cellerd/server.db?mode=rwc"
[storage]
type = "local"
path = "/var/lib/cellerd/storage"
[jwt]
rs256-public-key-file = "/etc/cellerd/public-key.pem"
The sections [database], [storage], and [jwt] are required.
Everything else is optional.
Top-Level Options
| Option | Type | Default | Description |
|---|---|---|---|
listen | string | "[::]:8080" | Address and port to listen on. The --listen command-line flag overrides it. |
allowed-hosts | list of strings | [] (all allowed) | Accepted values of the HTTP Host header. Set this in production. |
api-endpoint | string | derived from the Host header | Public URL of the API, shown to clients. Must end with /, e.g. "https://cache.example.com/". Set this in production. |
substituter-endpoint | string | same as api-endpoint | Public URL of the binary cache that Nix downloads from, if different from api-endpoint. |
soft-delete-caches | bool | false | Mark deleted caches as deleted instead of removing them from the database. The names of soft-deleted caches can’t be reused. |
require-proof-of-possession | bool | true | Require clients to upload the full data even if the server already has it. See Security Model. |
max-nar-info-size | integer (bytes) | 1048576 (1 MiB) | Maximum size of the metadata a client sends with an upload. |
Warning
If
allowed-hostsandapi-endpointare not set, the server trusts theHostheader that clients send. Behind a reverse proxy, set both to your public hostname and URL.
[database]
| Option | Type | Default | Description |
|---|---|---|---|
url | string | required | Database connection URL. See below. |
heartbeat | bool | false | Send a query to the database every minute to keep the connection alive. |
Celler supports SQLite and PostgreSQL:
# SQLite. mode=rwc creates the file if it doesn't exist.
url = "sqlite:///var/lib/cellerd/server.db?mode=rwc"
# PostgreSQL over a Unix socket
url = "postgresql:///cellerd?host=/run/postgresql"
# PostgreSQL over TCP
url = "postgresql://user:password@db.example.com/cellerd"
SQLite is enough for a single server. Use PostgreSQL if you run several API servers.
[storage]
Where Celler stores the cached data.
The type option selects the storage backend.
Local Storage
| Option | Type | Default | Description |
|---|---|---|---|
type | string | "local" | |
path | string | required | Directory to store files in. |
[storage]
type = "local"
path = "/var/lib/cellerd/storage"
S3 Storage
Works with Amazon S3 and S3-compatible services, such as Garage, MinIO, Cloudflare R2, and Backblaze B2.
| Option | Type | Default | Description |
|---|---|---|---|
type | string | "s3" | |
region | string | required | The region of the bucket. |
bucket | string | required | The name of the bucket. |
endpoint | string | AWS | URL of the S3 service. Set this for anything other than Amazon S3. |
credentials.access_key_id | string | from environment | Access key ID. |
credentials.secret_access_key | string | from environment | Secret access key. |
[storage]
type = "s3"
region = "us-east-1"
bucket = "my-celler-bucket"
endpoint = "https://s3.example.com"
If you leave out credentials, Celler reads them from the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.
This keeps secrets out of the configuration file.
On NixOS, put them in the file set by services.cellerd.environmentFile.
Note that the option names under credentials use underscores, unlike the other options.
To use an endpoint over plain http://, set the environment variable AWS_ALLOW_HTTP=true.
[jwt]
How the server checks the tokens that clients send.
Set exactly one of rs256-public-key-file and hs256-secret-key-file.
| Option | Type | Default | Description |
|---|---|---|---|
rs256-public-key-file | path | PEM file with an RSA public key. Tokens must be signed with the matching private key. | |
hs256-secret-key-file | path | File with a shared secret (raw bytes, not Base64). Tokens must be signed with the same secret. | |
token-bound-issuer | string | none | If set, tokens must have this iss (issuer) claim. |
token-bound-audiences | list of strings | none | If set, tokens must have an aud (audience) claim that contains one of these values. |
RS256 is recommended: the server only has the public key, so a compromised server can’t be used to create new tokens.
Create tokens with celler admin make-token and the matching private key or secret.
[chunking]
How uploaded NARs are split into chunks for deduplication. Without this section, chunking is disabled. For recommended values and trade-offs, see Chunking.
All values are in bytes. If the section is present, all four options are required.
| Option | Description |
|---|---|
nar-size-threshold | Only chunk NARs that are at least this large. 0 disables chunking; 1 chunks all NARs. |
min-size | Preferred minimum chunk size. |
avg-size | Preferred average chunk size. |
max-size | Preferred maximum chunk size. |
Changes only affect new uploads.
[compression]
How chunks are compressed in storage.
| Option | Type | Default | Description |
|---|---|---|---|
type | string | "zstd" | One of "none", "zstd", "brotli", "xz". |
level | integer | depends on type | Compression level. Defaults: zstd 8, brotli 5, xz 2. |
Changing the compression only affects new uploads.
After changing type, new uploads don’t reuse chunks stored with the old type, so deduplication is worse for a while.
[garbage-collection]
| Option | Type | Default | Description |
|---|---|---|---|
interval | duration | "12 hours" | How often to run garbage collection. "0s" disables automatic runs; you can still run cellerd --mode garbage-collector-once. |
default-retention-period | duration | "0s" (keep forever) | Delete store paths that were neither uploaded nor downloaded for this long. Caches can override it with celler cache configure --retention-period. |
Durations are strings like "30s", "12 hours", "3 months", or "1y".
Full Example
listen = "[::]:8080"
allowed-hosts = ["cache.example.com"]
api-endpoint = "https://cache.example.com/"
[database]
url = "postgresql:///cellerd?host=/run/postgresql"
[storage]
type = "s3"
region = "auto"
bucket = "celler"
endpoint = "https://<account-id>.r2.cloudflarestorage.com"
[jwt]
rs256-public-key-file = "/etc/cellerd/public-key.pem"
[chunking]
nar-size-threshold = 4194304 # 4 MiB
min-size = 2097152 # 2 MiB
avg-size = 8388608 # 8 MiB
max-size = 16777216 # 16 MiB
[compression]
type = "zstd"
[garbage-collection]
interval = "12 hours"
default-retention-period = "3 months"