This flake packages the
T3 Code desktop app and CLI for x86_64 and aarch64 Linux. It includes every supported agent provider, plus a few useful agent tools. This is a community project, not affiliated with or endorsed by the T3 Code team or any provider's vendor.
- Always up to date. T3 Code's releases on the latest and nightly channels are detected, tested and published automatically, within minutes of upstream.
- All supported agents: Codex, Claude, Cursor, Grok, fx, OpenCode, Antigravity, Kiro, Muse and pi.
- One line to install.
programs.t3code.enable = true;installs the app and every provider. - Tested before it's published. Automatic tests must pass for the flake to update.
- A binary cache. Free packages on the latest channel are cached and are ready to run after download.
- Update notifications. T3 Code tells you as soon as it sees a newer version of a provider.
- Nix stays in charge. Built-in updaters are disabled. When you see the update icon and t3code-nix has published that version, run
nix flake update t3code-nixand rebuild.
- Quick start
- Setup
- Packages
- The NixOS module
- Running the server
- Binary cache
- Unfree packages
- NixOS stable
- When something isn't working:
t3code-nix doctor, and reporting problems - Channels, pinning and rolling back
- Following new releases
- Details
- Maintainer notes
Try t3code-nix without touching your config:
nix run github:boltflake/t3code-nix # downloads and opens the T3 Code app, with all 10 agent providers
nix run github:boltflake/t3code-nix#t3 -- serve # starts a T3 Code server
nix run github:boltflake/t3code-nix#codex # runs one agent (Codex) in the terminalFlake
Add t3code-nix and its module:
{
inputs.t3code-nix.url = "github:boltflake/t3code-nix";
# Don't add `inputs.t3code-nix.inputs.nixpkgs.follows`: see "Binary cache".
outputs = { nixpkgs, t3code-nix, ... }: {
nixosConfigurations.my-machine = nixpkgs.lib.nixosSystem {
modules = [
./configuration.nix # your existing system configuration
t3code-nix.nixosModules.default
{
programs.t3code = {
enable = true;
# Optional: uncomment what you need
# providers = [ "codex" "claude" ]; # install only these providers (default: all ten)
# excludeProviders = [ "grok" ]; # or leave some out
# channel = "nightly"; # T3 Code nightly (default: latest)
# nixpkgs = "stable"; # NixOS stable's libraries (default: unstable)
# cli.enable = true; # include the headless `t3` CLI
# server.enable = true; # keep T3 Code running in the background for your phone, laptop or browser
# server.lan = true; # reachable on your local network and tailnet
# server.openFirewall = true; # open its port (3773) in the firewall
# Agent Tools:
# agentTools.agent-browser.enable = true; # a headless browser CLI for agents (lets agents open, click and screenshot web pages)
# agentTools.boat.enable = true; # boat.dev's sandbox CLI for agents
};
}
];
};
};
}For a machine with no desktop, run T3 Code as a server, without the desktop app:
{
inputs.t3code-nix.url = "github:boltflake/t3code-nix";
# Don't add `inputs.t3code-nix.inputs.nixpkgs.follows`: see "Binary cache".
outputs = { nixpkgs, t3code-nix, ... }: {
nixosConfigurations.my-server = nixpkgs.lib.nixosSystem {
modules = [
./configuration.nix # your existing system configuration
t3code-nix.nixosModules.default
{
programs.t3code = {
# No `enable = true`: the desktop app isn't installed.
server.enable = true; # keep T3 Code running in the background, with `t3` on PATH
server.users = [ "amber" ]; # your user name
server.lan = true; # reachable on your local network and tailnet
server.openFirewall = true; # open its port (3773) in the firewall
# Optional: uncomment what you need
# providers = [ "codex" "claude" ]; # bundle only these (default: all ten)
# agentTools.agent-browser.enable = true; # lets agents open, click and screenshot web pages
# agentTools.boat.enable = true; # boat.dev's sandbox CLI for agents
};
# Start the server at boot, without anyone logging in:
users.users.amber.linger = true;
}
];
};
};
}Then pair your devices with t3 pair (see Running the server).
All module options are documented in The NixOS module.
If your system isn't a flake yet
Flakes are not enabled by default on NixOS.
-
Turn them on: add this line to your
configuration.nix:nix.settings.experimental-features = [ "nix-command" "flakes" ];
-
Rebuild:
sudo nixos-rebuild switch
-
Turn your system into a flake with T3 Code:
sudo nix run github:boltflake/t3code-nix#init sudo nixos-rebuild switch
This creates
/etc/nixos/flake.nixwith T3 Code enabled. It follows the same NixOS branch your channel does, so your system stays on its NixOS release, though the first rebuild can bring that branch's newer updates. An existingflake.nixis never overwritten. To see the file first, runsudo nix run github:boltflake/t3code-nix#init -- --dry-run.Its configuration is named after your host, so a plain
nixos-rebuild switchbuilds it. If/etc/nixosis a git repository,initadds the file to it (or tells you the command, when the repository is another user's). It prints the rebuild command to run; use that one if it differs.nix run github:boltflake/t3code-nix#init -- --helplists its options, and the file's comments show the options for the providers, the server and the agent tools.To go back, delete
flake.nix(andflake.lock); if you've rebuilt with it, rebuild again (or boot the previous generation).nix flake init -t github:boltflake/t3code-nixgives you the same template to fill in yourself.
To try a single command without changing your configuration, put --extra-experimental-features 'nix-command flakes' after nix instead.
Without flakes
You don't need flakes to use t3code-nix. Everything the flake has (the
app, the NixOS module and the overlay) also works with the classic Nix
tools: nix-env, nix-shell, nix-build, or an import in your
configuration.nix.
# Install the T3 Code app for your user (run it again to update):
nix-env -f https://github.com/boltflake/t3code-nix/archive/main.tar.gz -iA t3code
# Or try the t3 CLI in a temporary shell, without installing anything:
nix-shell -p '(import (fetchTarball "https://github.com/boltflake/t3code-nix/archive/main.tar.gz") { }).t3'# configuration.nix
let
t3code-nix = import (fetchTarball "https://github.com/boltflake/t3code-nix/archive/main.tar.gz") { };
in
{
imports = [ t3code-nix.nixosModules.default ];
programs.t3code.enable = true;
}- The packages for your machine are right at the top:
t3code(the app),t3,codexand the rest. To get another machine type's packages, pass it in the{ }, for example{ system = "aarch64-linux"; }. - For anything else the flake has,
t3code-nix.flakehas it all. - Your own nixpkgs config and overlays don't apply to them, so they're the flake's builds, which the binary cache holds.
- For a fixed version, use a commit's tarball
(
…/archive/<commit>.tar.gz), or the tarball of at3code-v*tag.
Where to see what the flake has at this moment:
- The status page: every
pinned package's version on
main, when t3code-nix published it and, where upstream's release time is known, how long after it (measured or estimated); the median delivery time over the last 30 days, once there are enough deliveries to count; and each package's update status, such as a newer version found and what it's waiting for, a version being tested, or an update held and why. A version changed since your last visit gets a lightning strike and a small bolt beside it (only the bolt if your system asks for reduced motion). - The GitHub Releases: one per T3 Code version on the latest channel, listing every package in that set (see Following new releases).
t3code-nix doctoron your machine: the versions your build bundles, and which copy of each provider T3 Code will use there.versions/in the repository: one pin file per upstream download (T3 Code's app and CLI for each channel, each provider, boat and agent-browser), with its version and files; the nixpkgs pins for NixOS stable and agent-browser's browsers; andstable/, the set NixOS stable uses. The preview browser's pin is inside each T3 Code pin file.
| Package | What it is |
|---|---|
t3code (default) |
T3 Code desktop app, latest channel, with all ten providers. Its free parts (the app, codex, fx, opencode, pi) come from the binary cache. The six unfree providers and the preview browser are downloaded from their vendors |
t3code-nightly |
the same, nightly channel (the nightly app itself isn't in the binary cache) |
t3 / t3-nightly |
T3 Code's headless CLI and server, with all ten providers |
t3code-free, t3-free |
the latest channel's app and headless CLI with only the four free providers (codex, fx, opencode, pi) and no preview browser. Comes ready-made from the binary cache (and its libraries from cache.nixos.org), with nothing to build or patch. |
t3code-unwrapped, t3-unwrapped (+ -nightly) |
the same without providers or the preview browser |
chrome-headless-shell (+ -nightly) |
the browser T3 Code's HTML previews use, at the version its release pins, patched for NixOS (unfree) |
t3code and t3 bundle all ten providers. Pick some, or leave some out, by
name:
t3code.override { providers = [ "codex" "claude" ]; }
t3code.override { excludeProviders = [ "grok" "muse" ]; }The names are T3 Code's own: codex, claudeAgent (or claude), cursor,
grok, fx, opencode, antigravity, kiro, muse, pi. This flake's
package names (claude-code, cursor-agent, kiro-cli) work too.
providers also takes packages, mixed with names if you like
(providers = [ pkgs.codex "opencode" ]), for a provider built some other
way.
Signing in is per provider and depends on its backend. Most need their
own account, set up once with the provider's own command (for example
codex login) or from T3 Code. Some can also run against a local model.
| Package | What it is |
|---|---|
codex |
Codex: OpenAI's coding agent (daemon auto-start and self-update off) |
fx |
fx: Vercel's native coding agent |
opencode |
OpenCode: an open-source coding agent built for the terminal |
pi |
pi: a minimal terminal coding agent |
claude-code |
Claude Code: Anthropic's coding agent (unfree) |
cursor-agent |
Cursor Agent: Cursor's coding agent; installs agent and cursor-agent (unfree) |
grok |
Grok Build: xAI's coding agent (unfree) |
antigravity |
Antigravity: Google Antigravity's CLI, agy (unfree) |
kiro-cli |
Kiro CLI: Kiro's coding agent for the terminal (unfree) |
muse |
Muse Code: Meta's coding agent (unfree) |
| Package | What it is |
|---|---|
doctor |
t3code-nix doctor: tells you why something isn't working (see below) |
init |
sets up a NixOS system that isn't a flake yet as one with T3 Code (see Setup) |
Agent tools, not part of T3 Code:
| Package | What it is |
|---|---|
boat |
boat: boat.dev's cloud sandboxes from the command line (self-update off) |
agent-browser |
agent-browser: Vercel's headless browser CLI for agents. It drives ungoogled-chromium from nixos-unstable by default. You can choose chromium or google-chrome instead, and also take the browser from the newest NixOS release with browserChannel = "stable" (see Agent tools). |
The browsers come from nixpkgs. This flake holds each one at a pinned version and moves it forward automatically when nixpkgs gets a newer one and this flake's tests pass with ungoogled-chromium (Chromium and Chrome are tested too; a failure there opens an issue); the current versions are on the status page.
What each package is built from is in docs/acceptance-matrix.md.
programs.t3code's options:
| Option | Default | What it does |
|---|---|---|
enable |
false |
installs package for every user |
channel |
"latest" |
"latest" or "nightly": T3 Code's release channel; picks the default package and the CLI |
nixpkgs |
"unstable" |
"unstable" or "stable": build on nixos-unstable's libraries, or on the current stable NixOS release's (NixOS stable). It applies to the app, the CLI, the server, the doctor and the agent tools. It doesn't change which T3 Code you get (that's channel), and "stable" can't be combined with channel = "nightly" |
providers |
null (the package's own) |
which providers to bundle, by name, as in Agent providers |
excludeProviders |
[ ] |
providers to leave out, by name |
providersOnPath |
true |
puts the bundled providers on PATH too, at low priority |
electron |
null (the package's own: "auto") |
which Electron the desktop app runs on: "auto", "bundled", "nixpkgs" or an Electron package (see The desktop app's Electron) |
acpRuntimes |
null (the package's own: none) |
runtimes for agents T3 Code installs from the ACP registry: "nodejs", "uv" (see ACP registry agents) |
agentTools.boat.enable |
false |
installs boat, with or without the app |
agentTools.agent-browser.enable |
false |
installs agent-browser, with or without the app |
agentTools.agent-browser.package |
this flake's agent-browser |
which agent-browser: an .override { … } of it, or pkgs.agent-browser from the overlay |
agentTools.agent-browser.browserChannel |
null (the package's own) |
"unstable" or "stable": which of this flake's browser pins its browser comes from |
agentTools.agent-browser.browser |
null (the package's own: "ungoogled-chromium") |
"ungoogled-chromium", "chromium" or "google-chrome": which browser it drives (see Agent tools) |
cli.enable |
false |
installs the headless t3 too (t3-nightly on the nightly channel), bundling what the app bundles, with its shell completions |
cli.allowUpstreamService |
false |
lets this flake's t3 run the commands for upstream's own service, which it refuses |
server.* |
off | a T3 Code server as a systemd user service: see Running the server |
package |
this flake's t3code (t3code-nightly on the nightly channel) |
what to install: t3code-free, t3, an .override { … } of one, or pkgs.t3code from the overlay |
binaryCache |
true |
adds the binary cache and its key to nix.settings |
claudeCodePolicy |
true |
when claude-code is bundled, writes the policy drop-in /etc/claude-code/managed-settings.d/10-t3code-nix.json with claude's update switches, so a project's or your own .claude/settings.json can't turn its self-updater back on (see Provider updates); machine-wide, beside any managed-settings.json of your own |
runtimeCompat |
false |
turns on programs.nix-ld with the libraries T3 Code's own downloads need; works on its own, without enable (see T3 Code over SSH) |
programs.t3code = {
enable = true;
providers = [ "codex" "claude" ];
cli.enable = true;
};- The CLI from
cli.enablethen bundles what the app ends up with: the same providers, and the preview browser only if the app has it. - A
packagethat has no providers to pick (an-unwrappedone, or nixpkgs' ownt3code) can't take them. Setting them then stops the rebuild, before anything is built, with a message saying so.
- A package: take one from the flake
(
t3code-nix.packages.${system}.t3code). - Home Manager: put the package in
home.packages(home.packages = [ t3code-nix.packages.${pkgs.stdenv.hostPlatform.system}.t3code ];). There's no Home Manager module. - The overlay,
t3code-nix.overlays.default, puts every package underpkgs.t3code-nix(pkgs.t3code-nix.t3,pkgs.t3code-nix.codex), and the app and most providers at the top level too. Which ones, and why, is under The overlay.
programs.t3code.server runs this flake's t3 serve as a systemd user
service, t3code-server, so your other devices can reach this machine.
- It has the same channel and providers as the app.
- It needs no nix-ld, and its version comes from the flake like everything else.
- It works without
enable, so a headless machine gets the server andt3but not the desktop app.
For example, a server for amber that the other devices on your network can reach:
programs.t3code.server = {
enable = true;
users = [ "amber" ];
lan = true;
openFirewall = true;
};
# Start at boot and keep running after logout, not only while amber is
# logged in:
users.users.amber.linger = true;Starting at boot is NixOS's own users.users.<name>.linger, not an
option here: it's a choice about the user account, and NixOS already has
the one place for it. Without it, the server runs while the user is logged
in.
| Option | Default | What it does |
|---|---|---|
server.enable |
false |
the t3code-server user service, and its t3 on PATH |
server.users |
[ ] (every user that isn't a system user) |
whose session runs it. Each server listens on port, so on a machine with several users, name one |
server.home |
null (~/.t3) |
its T3 home, T3CODE_HOME (%h is the home folder; no other % specifier) |
server.port |
3773 |
T3CODE_PORT |
server.host |
null (127.0.0.1) |
T3CODE_HOST: an address to listen on, for any client (not with lan) |
server.lan |
false |
T3CODE_LAN: also accept the local network and tailnet (private addresses only; not with host) |
server.openFirewall |
false |
opens port in the firewall, for lan or host (Tailscale Serve and T3 Connect need no open port) |
server.tailscaleServe.enable, .port |
false, 443 |
serve it on the tailnet with Tailscale Serve (needs services.tailscale and tailscale set --operator=<user>) |
server.logLevel |
null (Info) |
T3CODE_LOG_LEVEL: All, Trace, Debug, Info, Warn, Error, Fatal or None |
server.environmentFile |
null |
a file of NAME=value lines, read at start and kept out of the Nix store, for secrets or other T3CODE_* settings (an absolute path, or under %h/). Its values win over the options; set the home with server.home, not T3CODE_HOME here, since t3code-nix doctor only knows server.home |
Pairing. To use the server from another device (a phone, a laptop, a
browser), pair it: run t3 pair on this machine and open the code or link
it gives you on the other device.
The other device must be able to reach the server, and by default it can't: the server listens only on this machine (127.0.0.1). Make it reachable in one of these ways first:
server.lan = true: devices on your local network and tailnetserver.host: an address of your choice, for any client that reaches itserver.tailscaleServe.enable = true: over HTTPS on your tailnet- T3 Connect (below): from anywhere, through T3's relay, with no port open
Until then, t3 pair and t3 status suggest t3 up or t3 connect;
this flake's t3 refuses those (see
Upstream's own service).
T3 Connect reaches the server through T3's relay with your T3 account, from anywhere, with no port open. Once per T3 home:
t3 connect link # sign in: open the link it prints
systemctl --user restart t3code-server # connects on start
t3 connect status # "Other devices can reach this machine"With server.home set, add --base-dir with that home to both t3
commands, with %h written as your home folder (for example
--base-dir ~/.t3-server).
Through the overlay, T3 Connect uses your nixpkgs' cloudflared, which must be 2025.6.1 or newer.
t3 connect unlink turns it off (then restart the server to close the
tunnel), and t3 connect logout signs out.
Logs. The server logs to the user journal
(journalctl --user -u t3code-server), pairing details included, so
whoever can read your journal can read those too.
Upgrades. A rebuild doesn't restart a running server, since that would
end any agent turns it's running. The new version starts the next time the
server does (at boot, or at login without linger), or when you run
systemctl --user restart t3code-server.
Before a new version of the server first starts, the service copies the
database (~/.t3/userdata/statev2.sqlite, with SQLite's online backup) to
~/.t3/t3code-nix-backups/statev2-<previous version>-<time>.sqlite, and
keeps the newest three. <previous version> is the version this service
last started, or unknown when the service first starts on a database
that was already there. With server.home set, these paths are under that
home instead of ~/.t3.
-
Each copy is the size of the database, which can be several GB (
du -h ~/.t3/userdata/statev2.sqlite). -
A new version may migrate the database so that an older one won't open it. If a rollback to an older generation leaves the server failing, put back the copy from the version you rolled back to (changes since then are lost), with that copy's file name in the
cpline:systemctl --user stop t3code-server cp "$HOME/.t3/t3code-nix-backups/statev2-<version>-<time>.sqlite" ~/.t3/userdata/statev2.sqlite rm -f ~/.t3/userdata/statev2.sqlite-wal ~/.t3/userdata/statev2.sqlite-shm systemctl --user start t3code-server
-
If a copy fails, the server doesn't start (
systemctl --user status t3code-serversays why), and the next start tries again.
The desktop app runs a server of its own on ~/.t3. So while
t3code-server uses that home, the desktop app on the same machine says
"This T3 home is unavailable" and quits. On a machine that runs both,
either:
- start the app with another
T3CODE_HOME, and pair it with the server like any other device, or - give the server its own
home, and pass--base-dirto thet3commands meant for it (with%hwritten as your home folder, for example--base-dir ~/.t3-server).
T3 Code can also install a server of its own: t3 service install, t3 up
and plain t3 connect set up t3code.service in ~/.config/systemd/user.
That service runs T3 Code's own download from ~/.t3/runtime, not this
flake's build: it has none of the bundled providers, updates itself outside
Nix, and on NixOS starts only with
runtimeCompat. So this flake's t3
refuses those commands, and t3 update. The rest of t3 connect (link,
login, status, unlink, logout, publish) works for t3code-server.
If upstream's service is already installed, remove it with
t3 service uninstall before turning on t3code-server: only one server
can run on a T3 home (see One server per T3 home).
t3 service protect doesn't work on NixOS (/etc/systemd is read-only);
set that kind of protection in NixOS instead, with systemd.slices,
systemd.services."user@" and
systemd.user.services.t3code-server.serviceConfig.
Using upstream's service on purpose. Set enable, cli.enable,
cli.allowUpstreamService and runtimeCompat (without the module:
t3.override { allowUpstreamService = true; } and programs.nix-ld with
the libraries runtimeCompat lists in nixos/module.nix). Leave
server.enable off, or give the two servers different homes and ports.
A public Cachix cache holds the free packages
of the latest channel: t3code-unwrapped, t3-unwrapped, codex, fx,
opencode, pi, and with them all of t3code-free and t3-free. It
also holds the agent tools boat and agent-browser (their nixos-unstable
builds).
It holds free software only. So what comes from where depends on the package you install:
| You install | From this cache | From each vendor, patched on your machine where needed | Put together on your machine |
|---|---|---|---|
t3code (the default) or t3 |
the app itself, and Codex, fx, OpenCode and pi | Claude Code, Cursor Agent, Grok, Antigravity, Kiro, Muse, and the preview browser | the small wrapper that bundles them |
t3code-free or t3-free |
everything | nothing | nothing |
t3code-nightly or t3-nightly |
Only Codex, fx, OpenCode and pi | the nightly app, the six unfree providers and the preview browser | the wrapper |
- "Patched on your machine" means downloading the vendor's ready-made program and, where it needs that, adjusting it to run on NixOS (Grok and Muse are static programs, used as they are). It takes seconds per package; nothing is compiled.
- The libraries all of these use come from cache.nixos.org as usual.
- Choosing
providerschanges the wrapper, which is then put together on your machine; the providers you keep come from the same places as above. - It's on Cachix's free plan for open-source projects: 5 GB, and when that fills, the least recently used entries are removed. A full set for both systems is about 1.3 GB compressed (measured for T3 Code 0.1.9 on x86_64 and doubled; libraries already on cache.nixos.org aren't stored again), so the cache has room for several releases. Which ones stay is decided by use, not age. A package that has gone is downloaded from its vendor and patched on your machine again.
Three ways to use it:
-
The NixOS module adds it whenever it installs anything: the app, the server or an agent tool (
programs.t3code.binaryCache, on by default). It takes effect from the rebuild after the one that turns it on. -
nix runand other flake commands are offered it by this flake'snixConfig. Nix asks first (or pass--accept-flake-config), and then uses it only if you're intrusted-usersor the machine already trusts this cache. Otherwise it prints a warning and builds without the cache, so add it by hand instead. -
By hand, on NixOS:
nix.settings = { substituters = [ "https://t3code-nix.cachix.org" ]; trusted-public-keys = [ "t3code-nix.cachix.org-1:FwZvqgRcnUjCSEUmdosysof1pTedbm/TTmlk8IeDsJA=" ]; };
Elsewhere, the same two values go in
/etc/nix/nix.confasextra-substitutersandextra-trusted-public-keys; then restart the daemon (sudo systemctl restart nix-daemon).
Don't make this flake follow your nixpkgs. With
inputs.t3code-nix.inputs.nixpkgs.follows = "nixpkgs";the packages would be built on your nixpkgs instead of the one this flake pins (all but the NixOS stable set and agent-browser's browsers, which have pins of their own).
- The cache holds only what the pinned one produces. Unless yours is at the same revision, the store paths differ and the cache has none of them.
- Leaving the input alone means your lock file pins two nixpkgs: yours and this flake's. Unless they're the same revision, T3 Code uses its own copy of the libraries it needs (glibc, GTK, Mesa and so on), next to your system's: several hundred MB, downloaded ready-made from cache.nixos.org.
Seven of the packages this flake bundles are unfree:
claude-codecursor-agentgrokantigravitykiro-climusechrome-headless-shell, the preview browser (and its-nightlybuild)
The flake's own packages (nix run, t3code-nix.packages.${system}.*, and
what the module installs by default) allow exactly these seven, plus Google
Chrome for agent-browser (below). Nothing else. You don't need
allowUnfree for them.
Google Chrome isn't bundled: agent-browser uses it only when you choose it
(browser = "google-chrome", see Agent tools), and
choosing it is the opt-in.
Through the overlay, your own nixpkgs config decides, Google Chrome
included. For an all-free install, use t3code-free or t3-free (see
T3 Code). They're on the latest channel only.
programs.t3code.nixpkgs picks the libraries T3 Code is built on (Mesa,
GTK, nss, glibc, …). It doesn't change which T3 Code you get: that's
channel.
nixpkgs |
Libraries | Channels | Binary cache |
|---|---|---|---|
"unstable" (default) |
the nixos-unstable this flake pins |
latest and nightly | yes |
"stable" |
the newest NixOS release, at the revision this flake pins and tests (versions/nixpkgs-stable.json) |
latest only | no |
programs.t3code = {
enable = true;
nixpkgs = "stable";
};Without the module, the set is t3code-nix.legacyPackages.<system>.stable
(.t3code, .t3, .agent-browser, …); without flakes, with
t3code-nix imported as above, it's
t3code-nix.stable.t3code.
When to use it. The default packages work on a NixOS stable system too.
Choose "stable" if:
- the desktop app has graphics problems. With
"stable", its Mesa and GBM come from the same release as your system's GPU driver (/run/opengl-driver); unstable's can drift far enough from it to fail. (Not tested on every GPU.) - you'd rather have libraries that change less often, or nothing from unstable at all.
It follows this flake's pin, not your system: unless your system is at the same revision, you still get a second copy of the libraries.
What's different.
- Not cached. The binary cache holds only the default packages, so this set is patched and put together on your machine. Its libraries still come from cache.nixos.org. The only thing compiled is wrap-buddy, a small tool OpenCode is patched with (seconds).
- It can lag. When a new release fails a check on NixOS stable (on
either system), the stable set stays on the last versions that passed.
It catches up the next time everything passes there: after a fix in
nixpkgs, or with a later T3 Code release. The
status page says when the set is
behind, a
stable-behindissue says why, and each release's notes say whether NixOS stable has it. - agent-browser takes its browser (ungoogled-chromium by default) from this flake's NixOS stable browser pin instead of the unstable one (see Agent tools).
- A
packageyou set yourself (oragentTools.agent-browser.package) still wins.nixpkgsthen still picks the CLI, the server and the doctor, and the providers follow the app.
What it isn't.
- A rollback: to stay on an older T3 Code, pin a tag (see Channels, pinning and rolling back).
- Your own nixpkgs: for that, see the overlay (and
why not
follows).
programs.t3code.enable (or server.enable) installs t3code-nix doctor, which checks the usual reasons T3 Code or a provider misbehaves
on NixOS, usually in a few seconds (asking claude about its machine
policy can take up to 30). Without the module, run
nix run github:boltflake/t3code-nix#doctor. That one doesn't know your
configuration: it checks the default packages, and can't tell whether you
meant to run the server.
$ t3code-nix doctor
t3code-nix doctor (T3 Code 0.1.9, latest channel)
Electron 44.10.2 from nixpkgs (bundled: 44.10.1; auto: nixpkgs 44.10.2 >= bundled 44.10.1)
Providers (looked up on this terminal's PATH; T3 Code takes yours from your login
shell, which is usually the same, and falls back to the ones it bundles):
OK antigravity 1.5.6 (bundled)
WARN claude-code: T3 Code uses your claude, installed outside Nix (/home/me/.local/bin/claude; version not checked), not the bundled 2.1.322
→ if it's an old self-installed copy (a provider's own updater puts them in your home, for example in ~/.local/bin, ~/.grok/bin or ~/.opencode/bin), delete it so the bundled one is used
OK codex 0.167.2 (bundled)
OK cursor-agent: built into T3 Code (its SDK); nothing to find on PATH
…
(A binary path set in T3 Code's own provider settings comes before all of this.)
This system:
OK binary cache: https://t3code-nix.cachix.org is set up
PROBLEM upstream's service is installed (/home/me/.config/systemd/user/t3code.service), and without nix-ld its downloaded T3 Code can't start
→ `t3 service uninstall`, or `systemctl --user disable --now t3code.service` and delete …
…
Each line is OK, WARN or PROBLEM; WARN and PROBLEM lines say
what to do under them (→). It exits with 1 if there's a problem.
It only reads: it writes nothing of yours and needs no sudo. It runs no
provider except claude's own doctor, in a throwaway home, to ask whether
a machine policy keeps claude's updates off (claude may contact its servers
and run npm config there). Versions come from store paths, and a provider
installed outside Nix is reported as "version not checked".
A security problem goes in a private report, never an issue: see SECURITY.md. For anything else:
- Run
t3code-nix doctorfirst, and do what itsWARNandPROBLEMlines say. - If that doesn't fix it, open an issue
with the doctor's output, the t3code-nix commit you're on, what you
did, and what happened. With flakes,
nix flake metadata /etc/nixos(or your flake's folder) lists each input with its commit; without them, give the tarball URL or commit you import. The output shows paths in your home folder; edit out anything you'd rather not share.
A problem in T3 Code itself, one that also happens without Nix, belongs upstream.
Channels. The latest channel ("latest", upstream's name for its
non-nightly releases) is the default. For nightly, set
programs.t3code.channel = "nightly", or use the -nightly packages.
Nightly gets T3 Code's nightly builds only, never a latest-channel
release, even one newer than the newest nightly.
These are T3 Code's own release channels; the libraries underneath are a
separate choice (see NixOS stable).
Both apps can be installed together (programs.t3code installs one; add
the other package yourself). They share ~/.t3, so nightly can migrate the
database ahead of latest; start one with its own T3CODE_HOME to keep them
apart.
Pinning. main moves with every release. To stay on one set of
versions, point the input at a tag or a commit instead:
inputs.t3code-nix.url = "github:boltflake/t3code-nix/t3code-v<version>"; # a latest-channel release
# or any commit (for example, to pin a nightly published between release tags):
# inputs.t3code-nix.url = "github:boltflake/t3code-nix/<commit>";Each T3 Code version on the latest channel gets a t3code-v<version> tag, on the commit
that first published it, with every package as it was there. Its
GitHub Release lists them.
Rolling back.
-
The whole system: boot an older generation from the boot menu, or run
sudo nixos-rebuild switch --rollback. -
Only t3code-nix: in your flake's folder, lock it to an older tag or commit, then rebuild:
cd /etc/nixos sudo nix flake lock --override-input t3code-nix 'github:boltflake/t3code-nix/t3code-v<version>' # or a commit: 'github:boltflake/t3code-nix/<commit>' sudo nixos-rebuild switch # or as you usually rebuild, e.g. --flake /etc/nixos#nixos
The lock file keeps that until your next
nix flake update. To stay there, pin the input as above. -
Without flakes: import an older tag's or commit's tarball (
…/archive/t3code-v<version>.tar.gzor…/archive/<commit>.tar.gz) instead ofmain's, then rebuild. -
The server: restart it after rolling back (see Running the server), and if it then fails, put back its database copy.
An older set may not download any more. Every package is the vendor's own file, and a pin stays fetchable only as long as the vendor keeps that file. The binary cache can stand in for the free packages while it still holds them. Booting an older generation needs none of this: its packages are still in your store.
Each T3 Code version on the latest channel gets a GitHub Release here, named
T3 Code <version>, on its t3code-v* tag.
- It lists every package at that commit, and what changed since the previous release, with links to the release notes where upstream has them.
- It shows how to pin exactly that set.
- A release's tag pins the set as it was first published. Later provider
updates, and nightlies, land on
mainwithout a release. - GitHub's Latest marker is on the release for the version
mainships now. If upstream pulls a release,maingoes back to the version before it, and the marker moves with it.
To hear about them, use Watch → Custom → Releases on the repository page, or subscribe to the feed at https://github.com/boltflake/t3code-nix/releases.atom.
nixpkgs. The nixpkgs this flake pins (for the libraries the apps load
and the helpers around them) moves to the newest nixos-unstable with
each new T3 Code on the latest channel, and at least once a week. A move
waits until everything it needs from nixpkgs is on cache.nixos.org, so you
never build any of it yourself, and it's tested like any release.
t3code and t3 come with all ten providers T3 Code supports. Two things
about how T3 Code uses them:
- Your own installs come first. When T3 Code starts, it reads
PATHfrom your login shell and searches it before the providers this flake bundles. So if you've installed, say, codex yourself, T3 Code uses your codex, and the bundled ones are only used for providers you don't have. Cursor is the exception: T3 Code runs it through its own SDK and looks up no command, so the bundledcursor-agent(and any of your own) is for the terminal only. - T3 Code enables only Codex and Claude by default. The other eight (Cursor, Grok, fx, OpenCode, Antigravity, Kiro, Muse, pi) are installed, but you switch each one on once in T3 Code's settings.
The module also puts them on your PATH (providersOnPath), at low
priority, so your own package of the same command wins.
~/.t3/bin/t3, which the desktop app writes, doesn't bundle the
providers and breaks after garbage collection; use this flake's t3 instead.
T3 Code's "update provider" notice still works: it tells you when a newer
version of a provider is out. Once t3code-nix has published it (the
status page shows what it has),
run nix flake update t3code-nix and rebuild to get it. The notice comes
from the provider's own release feed, so it can show a version this flake
hasn't published yet.
Providers mostly can't update themselves here, with the two exceptions
below. Their own update and self-install commands (claude update,
codex update, pi update --self and so on) print a short message and do
nothing, because they'd install a second copy outside Nix that can shadow
this one and may not run on NixOS. If T3 Code
shows an Update button, pressing it shows that message.
claude's settings files. The wrapper turns claude's self-update off,
but a settings file can turn it back on: a repository's
.claude/settings.json (or your own ~/.claude/settings.json) can set
the update switches in its env block, and claude would then update
itself into ~/.local. Only a claude machine policy ranks above every
settings file. The NixOS module writes one (claudeCodePolicy, on by
default) whenever T3 Code, its server or its CLI bundles claude. Without
the module, or for this flake's claude-code installed on its own, write
the same file yourself. Make it a copy (mode), not a link into the
store, since claude's own doctor flags a policy reached through a link:
environment.etc."claude-code/managed-settings.d/10-t3code-nix.json" = {
mode = "0444";
text = builtins.toJSON {
env = {
DISABLE_UPDATES = "1";
DISABLE_AUTOUPDATER = "1";
DISABLE_INSTALLATION_CHECKS = "1";
};
};
};t3code-nix doctor asks the bundled claude whether a machine policy keeps
its updates off: it warns when none does, reports a problem when claude
can't read a policy file, and warns when T3 Code would use a claude
installed outside Nix.
Codex's daemon updater. In codex's TUI, the /daemon menu's "Install
latest public stable" and "Use this CLI build" run codex's daemon updater
directly, where no wrapper can refuse them
(openai/codex#41188). They
install only into a daemon package that's already there, in
~/.codex/packages/app-server-daemon (or the same folder under
$CODEX_HOME). A codex with the daemon's auto-start on leaves one behind,
and so does a ~/.codex copied from another machine. t3code-nix doctor
warns about that folder and about the background server and update loop
it runs (even once the folder is deleted), and says how to stop each
before you delete it.
t3code-nix.overlays.default puts every package under pkgs.t3code-nix.
The app and the providers are also added at the top level, but never over
a different program nixpkgs has under the same name. With this flake's
pinned nixpkgs, that gives:
| Packages | At the top level of pkgs? |
|---|---|
t3code, t3code-nightly, t3code-free, t3code-unwrapped (+ -nightly) |
yes (t3code replaces nixpkgs' own, the same program, and comes with its CLI: see below) |
codex, claude-code, kiro-cli, agent-browser |
yes, replacing nixpkgs' own (the same programs); the overlay's agent-browser uses your nixpkgs' browsers (ungoogled-chromium by default) |
cursor-agent, grok, pi, boat |
yes (nixpkgs has nothing by those names) |
opencode |
no: nixpkgs' opencode-desktop builds from nixpkgs' own opencode, so that stays (the apps bundle this flake's either way) |
fx, muse, antigravity |
no: nixpkgs' are different programs (a JSON viewer, a MIDI sequencer, and a deprecated alias of the Antigravity IDE, antigravity-ide) |
t3, t3-nightly, t3-free, t3-unwrapped (+ -nightly) |
no: the CLI's packages aren't offered at the top level (and nixpkgs' t3 is a tee) |
doctor, init, chrome-headless-shell (+ -nightly) |
no, only under pkgs.t3code-nix |
Anything that isn't at the top level is still there as
pkgs.t3code-nix.<name>, for example pkgs.t3code-nix.t3. If your
nixpkgs gains a different program under one of these names, it keeps it.
The top-level pkgs.t3code has the programs nixpkgs' package has
(bin/t3, bin/t3code-desktop), so a module that runs them works with it:
Home Manager's own programs.t3code, whose server.enable runs
${package}/bin/t3 serve, for one. Its arguments are this flake's, though
(below).
- It's the app with its CLI inside,
pkgs.t3code-nix.t3code.override { withCli = true; }:bin/t3code,bin/t3code-desktop(nixpkgs' name for the app) andbin/t3, the CLI with the same providers, wrapped as thet3package is. It's bigger for it (about 5.4 GB on disk with every provider, against 4.9 GB for the app alone). - The
t3inside is the CLI's own release, which this flake updates separately from the app, so for a while after a release it can be a different version. - It takes this flake's arguments, not nixpkgs':
providers = [ "claude" "codex" ]rather thanenableClaude = true, which fails with a message saying so. nixpkgs'enableGit,enableGitHuband the like putgitandghon T3 Code'sPATH; this one doesn't (they come from your system). For nixpkgs' arguments, use nixpkgs' ownt3code, from a nixpkgs without this overlay. - Installing it next to another
t3gives two: nixpkgs' (atee), or this flake'spkgs.t3code-nix.t3. With nixpkgs't3, or ours with other providers or another channel, at the same priority (the default) a Home Manager build fails on the collision and on NixOS one of them wins silently;nix profilerefuses even an identical one. Install only one, give one a higher priority (lib.hiPrio, or--priorityfornix profile), or install the app without its CLI:pkgs.t3code.override { withCli = false; }. withCli = trueworks ont3code-nightlyandt3code-freetoo (the nightly has not3code-desktop). Home Manager's own server needs it if you point itsprograms.t3code.packageat one of them.- With the NixOS module and
package = pkgs.t3code, the app'st3is installed with the app. Withcli.enableor the server, the module's ownt3is installed too, at high priority, so it wins over the app's, and the server always runs the module's.
The overlay builds on your own nixpkgs. Your nixpkgs config
(allowUnfree) decides which unfree packages you can build, and the
binary cache has those builds only if your nixpkgs is at the revision this
flake pins.
The desktop app is upstream's own app (app.asar and the rest of
resources/, unchanged apart from pointing its native libraries at
nixpkgs), running packaged as on any Debian machine. Only the Electron it
runs on can change:
electron |
What you get |
|---|---|
"auto" (default) |
nixpkgs' electron_N-bin when it can stand in for upstream's: the same major version and the same release or newer. Otherwise upstream's bundled Electron |
"bundled" |
upstream's bundled Electron, always |
"nixpkgs" |
nixpkgs' electron_N-bin, under the same conditions as "auto", but never upstream's. Where "auto" would fall back for one of those reasons, evaluation stops with an error that says why and what to use instead. If nixpkgs' Electron failed t3code-nix's tests for this release, it's still used, with a warning |
| a package | the Electron you pass. It must be the bundled major version, though an older patch release is fine. Take nixpkgs' electron_N-bin, where N is that major, from the same nixpkgs the app is built on (t3code-nix.inputs.nixpkgs.legacyPackages.<system>, or the overlay's pkgs): mixing two nixpkgs revisions in one app can break it |
The status page shows which
Electron the current releases run; t3code-nix doctor shows yours.
# With the module: upstream's Electron, or a specific one
programs.t3code.electron = "bundled";
# or (use the bundled major the status page shows):
# programs.t3code.electron =
# t3code-nix.inputs.nixpkgs.legacyPackages.${pkgs.stdenv.hostPlatform.system}.electron_44-bin;
# Without the module, on the package:
t3code-nix.packages.${system}.t3code.override { electron = "bundled"; }- Why
"auto"prefers nixpkgs': Electron security fixes reach you with this flake's nixpkgs (see its schedule), instead of waiting for the next T3 Code release. Upstream tested its release on its own Electron patch, so the app may run a newer patch of the same major than upstream did. If you report a bug upstream, include your Electron version, or check it with"bundled"first.t3code-nix doctorshows which Electron you have and why. - When nixpkgs' Electron fails t3code-nix's tests and upstream's
passes, that release ships on upstream's Electron instead, until a new
T3 Code release or a nixpkgs update gives nixpkgs' another try; an issue
says so, and the status page and the release notes show it.
"nixpkgs"still builds on it if you ask, with a warning. - The
t3CLI is unaffected: its Node is built into the program.
T3 Code takes HTML preview screenshots and recordings with a headless
Chrome (Chrome for Testing's chrome-headless-shell). It downloads that
into ~/.t3/tools/ on first use, and the download can't run on NixOS
without nix-ld.
So t3code and t3 bring the same Chrome build their release pins,
patched to run on NixOS. On each start they link it where T3 Code looks
for it: ~/.t3/tools/chrome-headless-shell/<platform>/<version> (or under
T3CODE_HOME, or t3 --base-dir). T3 Code then never downloads it.
- A copy of that same version it downloaded before is replaced by the link; other versions are left alone.
- On hosts that restrict user namespaces (Ubuntu 23.10 and later) nothing
is linked: there T3 Code's own download and
t3 browser setupwork as they do upstream. - It adds about 290 MB to
t3code(about 400 MB tot3, which otherwise needs fewer system libraries). - Leave it out with
t3code.override { withPreviewBrowser = false; }; a link an earlier start made stays until you delete it. - It's unfree: the archive ships as Google Chrome, under Google's terms.
To be fully free, use
t3code-freeort3-free, which leave it out already. If you pick free providers with an override instead, also setwithPreviewBrowser = false.
Besides T3 Code and its providers, the flake ships a few agent tools:
command-line tools that the agents T3 Code runs use themselves. They're
not included as part of t3code or t3.
# With the module:
programs.t3code.agentTools.boat.enable = true;
programs.t3code.agentTools.agent-browser.enable = true;
# Or without it, as plain packages:
environment.systemPackages = [
t3code-nix.packages.${pkgs.stdenv.hostPlatform.system}.boat
t3code-nix.packages.${pkgs.stdenv.hostPlatform.system}.agent-browser
];boat runs boat.dev cloud sandboxes (
boat run,
boat new, boat exec). Its update check is off and boat self-update
says it's installed by Nix. Sign-in is boat's own (boat login), kept in
~/.config/ascii/boat/config.json, which this flake never touches. If
boat's own installer put a copy in ~/.ascii/bin, remove it and its shell
startup lines so this one runs.
agent-browser drives a headless browser for agents (open,
snapshot, click, fill, screenshot), with its dashboard, MCP
server and skills built in. It drives ungoogled-chromium by default;
plain Chromium and Google Chrome are one option away:
programs.t3code.agentTools.agent-browser.browser = "google-chrome"; # or "chromium"
t3code-nix.packages.${system}.agent-browser.override { browser = "google-chrome"; } # without the module| Browser | What it's for |
|---|---|
ungoogled-chromium (default) |
everyday agent work, with nothing from Google on its own |
chromium |
plain Chromium, without ungoogled's patches |
google-chrome |
checking a site in Google's Chrome, for example with Widevine (DRM video), which the Chromiums refuse. Unfree; downloaded from Google |
The browsers come from their own pinned nixpkgs, separate from the one
your system uses, so they usually mean another nixpkgs download. It
follows nixos-unstable by default (the browser-unstable pin), or the
newest NixOS release (browser-stable) with the module's
browserChannel = "stable" (or .override { browserChannel = "stable"; }).
Each pin moves when a browser's version changes, and at least weekly. The
status page shows each browser's version. The
NixOS stable set uses browser-stable by default.
- Any other browser:
agent-browser.override { browser = pkgs.brave; }(itsmeta.mainProgramruns; for a package without one, setAGENT_BROWSER_EXECUTABLE_PATH), or your ownAGENT_BROWSER_EXECUTABLE_PATH(or--executable-path, or--cdp), which wins over the package's. agent-browser upgrade(a second copy from a package manager),installanddoctor --fix(each downloads Chrome for Testing, which can't start on NixOS) say it's installed by Nix;installpoints tobrowser = "google-chrome". Plaindoctorworks.- What leaves the machine: when it starts a browser, agent-browser
reads Google's Chrome release feed (
chromereleases.googleblog.com) and warns if the browser is behind a release with security fixes, so a pin that falls behind says so.AGENT_BROWSER_NO_VERSION_CHECK=1turns that off. Beyond that, the browsers fetch what the agent opens; Chromium and Chrome also contact Google services on their own, ungoogled-chromium doesn't. Choosing Chrome also downloads it from Google. - User namespaces: Chromium's sandbox needs unprivileged user
namespaces. Where they're restricted (Ubuntu 23.10 and later), the
wrapper says so when you run it. Turn the restriction off with
sudo sysctl kernel.apparmor_restrict_unprivileged_userns=0, and to keep it, put the linekernel.apparmor_restrict_unprivileged_userns = 0in a file in/etc/sysctl.d/; or allowusernsfor this Chromium's path in an AppArmor profile. The wrapper never turns the sandbox off.
T3 Code's voice dictation works with nothing to set up. Its server runs the speech engine that comes with each release (transcribe-cpp, on the CPU or a Vulkan GPU). T3 Code downloads the speech models itself, from Hugging Face, when you choose one in its settings; they range from 35 MB to many GB. Each release is tested here: the engine's libraries resolve in the app and the CLI, its worker starts, and it transcribes a short spoken clip.
Codex's own voice mode (/voice in codex's terminal UI) is a different
thing, and it doesn't work out of the box on NixOS: it stops with "voice audio
devices could not open". Its audio helper has its own copy of ALSA, which
looks for its configuration in /usr/share/alsa and /usr/lib/alsa-lib.
NixOS has neither, and codex starts the helper with a fixed environment,
so a setting from outside can't point it elsewhere. This flake leaves the
fix to codex
(openai/codex#61732); until
then, codex's /voice is a known gap on NixOS.
Besides its ten providers, T3 Code can install agents from the public
ACP registry while it runs. This flake
doesn't package those agents, but it can give T3 Code what its installer
needs. An agent from npm needs npm and node on T3 Code's PATH, and
one from uv needs uv; without them T3 Code says the agent's runner is
missing. Agents shipped as a downloaded program need no runner, but may
need runtimeCompat to start on NixOS.
# With the module:
programs.t3code.acpRuntimes = [ "nodejs" ];
# Or without it, on the package:
t3code-nix.packages.${pkgs.stdenv.hostPlatform.system}.t3code.override { acpRuntimes = [ "nodejs" ]; }| Value | Adds | Added to t3's closure (x86_64) |
For |
|---|---|---|---|
[ ] (default) |
nothing | 0 | agents shipped as a program (with runtimeCompat if they need it) |
[ "nodejs" ] |
Node, with npm | about 142 MB | npm agents |
[ "uv" ] |
uv and Python | about 200 MB | uv agents |
[ "nodejs" "uv" ] |
all of it | about 342 MB | npm and uv agents |
- They go at the end of T3 Code's
PATH, after the providers. T3 Code puts your login shell'sPATHfirst, so your own Node or uv always wins; these only fill a gap. The agents' own shell commands can see them too when you have none of your own. uvcomes with a full Python, so uv uses it instead of downloading one (a downloaded Python can't start on NixOS without nix-ld).- An npm agent whose install downloads a program of its own may still need
runtimeCompat. - With the module,
acpRuntimesapplies to the app and to the CLI and server it installs.
runtimeCompat is for T3 Code servers that still come from T3 Code's own
download: mainly the one another machine installs here, and upstream's own
service if you use it on purpose. When T3 Code on
another machine connects to this one over SSH, it installs and runs its own
server here, which can't start on NixOS otherwise. For a server on this
machine, use server instead.
programs.t3code.runtimeCompat = true;It turns on programs.nix-ld, with the libraries that server needs. It
works on its own, without enable or server.enable. It's
off by default because nix-ld changes how every unpatched program on the
system starts. It's also best effort: this flake doesn't pin what T3 Code
downloads.
x86_64-linux and aarch64-linux.
Setting up the watcher and cache, the issues the update runs open, and the rules for changing providers are in MAINTAINING.md.
This repository is licensed under the MIT license. The packaged
programs are not part of this repository. Each packaged program's
meta.license gives its vendor's license: unfree for the seven
proprietary ones, which are under their vendors' terms.
Thanks to sadjow/codex-cli-nix, numtide/llm-agents.nix and LikelyLucid/t3code-nix for showing the way.
T3 Code, the providers and boat are their owners' products, and their names and logos belong to them; they appear here only to say what this flake packages. Packaging problems belong in this repository's issues, not upstream's.