A declarative, hermetic harness for Nix-defined agents.
nix: package tartarus
Aly Raffauf
(Jun 27, 2026, 9:19 PM EDT)
bbca9abe
85c1492f
+188
-36
+73
-1
flake.lock
+73
-1
flake.lock
···
14
14
"url": "https://flakehub.com/f/NixOS/nixpkgs/0"
15
15
}
16
16
},
17
+
"pyproject-build-systems": {
18
+
"inputs": {
19
+
"nixpkgs": [
20
+
"nixpkgs"
21
+
],
22
+
"pyproject-nix": [
23
+
"pyproject-nix"
24
+
],
25
+
"uv2nix": [
26
+
"uv2nix"
27
+
]
28
+
},
29
+
"locked": {
30
+
"lastModified": 1782093830,
31
+
"narHash": "sha256-6gmEVe69+KlRkZD4PEEV5xAlB9CB0Y9TiuEgQjDrKTQ=",
32
+
"owner": "pyproject-nix",
33
+
"repo": "build-system-pkgs",
34
+
"rev": "430680a19bc85a3bda55f12e4cc1a1aadcf2e478",
35
+
"type": "github"
36
+
},
37
+
"original": {
38
+
"owner": "pyproject-nix",
39
+
"repo": "build-system-pkgs",
40
+
"type": "github"
41
+
}
42
+
},
43
+
"pyproject-nix": {
44
+
"inputs": {
45
+
"nixpkgs": [
46
+
"nixpkgs"
47
+
]
48
+
},
49
+
"locked": {
50
+
"lastModified": 1782089418,
51
+
"narHash": "sha256-LRD1SuQWr49fGq3A+8GLXfsLE2xqIpQA440YDZwms3M=",
52
+
"owner": "pyproject-nix",
53
+
"repo": "pyproject.nix",
54
+
"rev": "43f0b40edd0a74c63f66b7b48d969ae6b740d611",
55
+
"type": "github"
56
+
},
57
+
"original": {
58
+
"owner": "pyproject-nix",
59
+
"repo": "pyproject.nix",
60
+
"type": "github"
61
+
}
62
+
},
17
63
"root": {
18
64
"inputs": {
19
-
"nixpkgs": "nixpkgs"
65
+
"nixpkgs": "nixpkgs",
66
+
"pyproject-build-systems": "pyproject-build-systems",
67
+
"pyproject-nix": "pyproject-nix",
68
+
"uv2nix": "uv2nix"
69
+
}
70
+
},
71
+
"uv2nix": {
72
+
"inputs": {
73
+
"nixpkgs": [
74
+
"nixpkgs"
75
+
],
76
+
"pyproject-nix": [
77
+
"pyproject-nix"
78
+
]
79
+
},
80
+
"locked": {
81
+
"lastModified": 1782100052,
82
+
"narHash": "sha256-UfyLY3Hfwb3JqxCcj0953GxTFI5dEL85EKEe6DAFiVs=",
83
+
"owner": "pyproject-nix",
84
+
"repo": "uv2nix",
85
+
"rev": "920fc6dfaf9f10ec56de93b184055e1a9f380d5e",
86
+
"type": "github"
87
+
},
88
+
"original": {
89
+
"owner": "pyproject-nix",
90
+
"repo": "uv2nix",
91
+
"type": "github"
20
92
}
21
93
}
22
94
},
+45
-9
flake.nix
+45
-9
flake.nix
···
1
1
{
2
2
description = "Tartarus: a Nix-defined containment runtime for auditable agents";
3
3
4
-
inputs.nixpkgs.url = "https://flakehub.com/f/NixOS/nixpkgs/0";
4
+
inputs = {
5
+
nixpkgs.url = "https://flakehub.com/f/NixOS/nixpkgs/0";
6
+
7
+
# uv2nix turns uv.lock into a Nix Python package set, so the harness's Python
8
+
# deps are resolved from the lockfile rather than hand-maintained.
9
+
pyproject-nix.url = "github:pyproject-nix/pyproject.nix";
10
+
pyproject-nix.inputs.nixpkgs.follows = "nixpkgs";
11
+
uv2nix.url = "github:pyproject-nix/uv2nix";
12
+
uv2nix.inputs.pyproject-nix.follows = "pyproject-nix";
13
+
uv2nix.inputs.nixpkgs.follows = "nixpkgs";
14
+
# uv does not lock build systems; this overlay supplies backends (hatchling).
15
+
pyproject-build-systems.url = "github:pyproject-nix/build-system-pkgs";
16
+
pyproject-build-systems.inputs.pyproject-nix.follows = "pyproject-nix";
17
+
pyproject-build-systems.inputs.uv2nix.follows = "uv2nix";
18
+
pyproject-build-systems.inputs.nixpkgs.follows = "nixpkgs";
19
+
};
5
20
6
21
outputs =
7
-
{ nixpkgs, ... }:
22
+
{
23
+
nixpkgs,
24
+
pyproject-nix,
25
+
uv2nix,
26
+
pyproject-build-systems,
27
+
...
28
+
}:
8
29
let
9
30
supportedSystems = [
10
31
"x86_64-linux"
···
34
55
agentsLib.mkAgents { inherit pkgs packages; } (import ./agent.nix { inherit pkgs; })
35
56
);
36
57
37
-
# The developer shell for hacking on this harness (Python + pytest). This is
38
-
# distinct from an agent's own `shell`, whose PATH is baked into its bundle.
39
-
devShells = eachSystem (
58
+
# The packaged harness (uv2nix virtualenv). `nix build .#tartarus` /
59
+
# `nix run .#tartarus -- "prompt"`. See package.nix.
60
+
packages = eachSystem (
40
61
system:
41
62
let
42
63
pkgs = pkgsFor system;
64
+
tartarus = pkgs.callPackage ./package.nix {
65
+
inherit pyproject-nix uv2nix pyproject-build-systems;
66
+
};
43
67
in
44
68
{
69
+
default = tartarus;
70
+
inherit tartarus;
71
+
}
72
+
);
73
+
74
+
# The developer shell for hacking on this harness (Python + pytest). This
75
+
# is distinct from an agent's own `shell`, whose PATH is baked into its
76
+
# bundle. ruff and ty are supplied by `uv`, not this shell.
77
+
devShells = eachSystem (
78
+
system:
79
+
let pkgs = pkgsFor system; in
80
+
{
45
81
default = pkgs.mkShellNoCC {
46
82
packages = with pkgs; [
47
83
bash
···
52
88
nixfmt
53
89
ripgrep
54
90
gnused
55
-
(python3.withPackages (pythonPackages: [
56
-
pythonPackages.httpx
57
-
pythonPackages.pip
58
-
pythonPackages.pytest
91
+
(python3.withPackages (p: [
92
+
p.httpx
93
+
p.pip
94
+
p.pytest
59
95
]))
60
96
];
61
97
};
+34
package.nix
+34
package.nix
···
1
+
# Package the tartarus harness from uv.lock via uv2nix.
2
+
{
3
+
pkgs,
4
+
lib,
5
+
pyproject-nix,
6
+
uv2nix,
7
+
pyproject-build-systems,
8
+
}:
9
+
10
+
let
11
+
workspace = uv2nix.lib.workspace.loadWorkspace { workspaceRoot = ./.; };
12
+
13
+
python =
14
+
let
15
+
interpreters = pyproject-nix.lib.util.filterPythonInterpreters {
16
+
inherit (workspace) requires-python;
17
+
inherit (pkgs) pythonInterpreters;
18
+
};
19
+
in
20
+
if interpreters == [ ] then
21
+
throw "tartarus: no Python interpreter matches requires-python = \"${workspace.requires-python}\""
22
+
else
23
+
builtins.elemAt interpreters 0;
24
+
25
+
pythonSet = (pkgs.callPackage pyproject-nix.build.packages { inherit python; }).overrideScope (
26
+
lib.composeManyExtensions [
27
+
pyproject-build-systems.overlays.wheel
28
+
(workspace.mkPyprojectOverlay { sourcePreference = "wheel"; })
29
+
]
30
+
);
31
+
in
32
+
(pythonSet.mkVirtualEnv "tartarus-env" workspace.deps.default).overrideAttrs (_: {
33
+
meta.mainProgram = "tartarus";
34
+
})
+11
-1
pyproject.toml
+11
-1
pyproject.toml
···
1
+
[build-system]
2
+
requires = ["hatchling"]
3
+
build-backend = "hatchling.build"
4
+
1
5
[project]
2
6
name = "tartarus-nix"
3
7
version = "0.1.0"
4
-
description = "A Nix-defined containment runtime for auditable agents."
8
+
description = "A framework for building composable, hermetic, and shareable AI agents with Nix."
5
9
readme = "README.md"
6
10
requires-python = ">=3.13"
7
11
dependencies = [
8
12
"httpx>=0.28.1",
9
13
]
10
14
15
+
[project.scripts]
16
+
tartarus = "tartarus.cli:main"
17
+
11
18
[dependency-groups]
12
19
dev = [
13
20
"pytest>=9.1.1",
···
18
25
[tool.pytest.ini_options]
19
26
pythonpath = ["."]
20
27
testpaths = ["tests"]
28
+
29
+
[tool.hatch.build.targets.wheel]
30
+
packages = ["tartarus"]
+25
-25
uv.lock
+25
-25
uv.lock
···
3
3
requires-python = ">=3.13"
4
4
5
5
[[package]]
6
-
name = "tartarus-nix"
7
-
version = "0.1.0"
8
-
source = { virtual = "." }
9
-
dependencies = [
10
-
{ name = "httpx" },
11
-
]
12
-
13
-
[package.dev-dependencies]
14
-
dev = [
15
-
{ name = "pytest" },
16
-
{ name = "ruff" },
17
-
{ name = "ty" },
18
-
]
19
-
20
-
[package.metadata]
21
-
requires-dist = [{ name = "httpx", specifier = ">=0.28.1" }]
22
-
23
-
[package.metadata.requires-dev]
24
-
dev = [
25
-
{ name = "pytest", specifier = ">=9.1.1" },
26
-
{ name = "ruff", specifier = ">=0.15.20" },
27
-
{ name = "ty", specifier = ">=0.0.55" },
28
-
]
29
-
30
-
[[package]]
31
6
name = "anyio"
32
7
version = "4.14.1"
33
8
source = { registry = "https://pypi.org/simple" }
···
178
153
{ url = "https://files.pythonhosted.org/packages/10/9b/5f14927848d2fd4aa891fd88d883788c5a7baba561c7874732364045708c/ruff-0.15.20-py3-none-win32.whl", hash = "sha256:ed65ef510e43a137207e0f01cfcf998aeddb1aeeda5c9d35023e910284d7cf21", size = 10857322, upload-time = "2026-06-25T17:20:28.612Z" },
179
154
{ url = "https://files.pythonhosted.org/packages/fa/f0/fe47c501f9dea92a26d788ff98bb5d92ed4cb4c88792c5c88af6b697dc8e/ruff-0.15.20-py3-none-win_amd64.whl", hash = "sha256:a525c81c70fb0380344dd1d8745d8cc1c890b7fc94a58d5a07bd8eb9557b8415", size = 11993274, upload-time = "2026-06-25T17:20:31.871Z" },
180
155
{ url = "https://files.pythonhosted.org/packages/d7/2b/9555445e1201d92b3195f45cdb153a0b68f24e0a4273f6e3d5ab46e212bb/ruff-0.15.20-py3-none-win_arm64.whl", hash = "sha256:2f5b2a6d614e8700388806a14996c40fab2c47b819ef57d790a34878858ed9ca", size = 11343498, upload-time = "2026-06-25T17:20:35.03Z" },
156
+
]
157
+
158
+
[[package]]
159
+
name = "tartarus-nix"
160
+
version = "0.1.0"
161
+
source = { editable = "." }
162
+
dependencies = [
163
+
{ name = "httpx" },
164
+
]
165
+
166
+
[package.dev-dependencies]
167
+
dev = [
168
+
{ name = "pytest" },
169
+
{ name = "ruff" },
170
+
{ name = "ty" },
171
+
]
172
+
173
+
[package.metadata]
174
+
requires-dist = [{ name = "httpx", specifier = ">=0.28.1" }]
175
+
176
+
[package.metadata.requires-dev]
177
+
dev = [
178
+
{ name = "pytest", specifier = ">=9.1.1" },
179
+
{ name = "ruff", specifier = ">=0.15.20" },
180
+
{ name = "ty", specifier = ">=0.0.55" },
181
181
]
182
182
183
183
[[package]]