Code Metrics¶

Generated: 2026-07-21 22:33 UTC

Lines of Code¶

	Files	Code	Comment	Blank	Total
Source	83	20 082	4 436	1 298	25 816
Tests	96	28 397	2 560	2 100	33 057
Combined	179	48 479	6 996	3 398	58 873

Comment/code ratio: 22%
Test/source ratio: 141.4%

Source by module (click to expand)

Module	Files	Code	Comment	Blank
`terok_sandbox/`	83	20 082	4 436	1 298
`terok_sandbox/_util/`	11	638	253	94
`terok_sandbox/_util/__init__.py`	—	26	3	4
`terok_sandbox/_util/_apparmor.py`	—	97	18	5
`terok_sandbox/_util/_fs.py`	—	23	13	2
`terok_sandbox/_util/_logging.py`	—	29	12	2
`terok_sandbox/_util/_naming.py`	—	7	9	3
`terok_sandbox/_util/_net.py`	—	25	10	9
`terok_sandbox/_util/_pidfile.py`	—	50	32	8
`terok_sandbox/_util/_selinux.py`	—	238	88	46
`terok_sandbox/_util/_subprocess_env.py`	—	15	15	2
`terok_sandbox/_util/_systemctl.py`	—	104	39	8
`terok_sandbox/_util/_templates.py`	—	24	14	5
`terok_sandbox/commands/`	11	3 480	622	157
`terok_sandbox/commands/__init__.py`	—	213	68	6
`terok_sandbox/commands/_types.py`	—	12	8	1
`terok_sandbox/commands/credentials.py`	—	644	127	40
`terok_sandbox/commands/doctor.py`	—	67	20	15
`terok_sandbox/commands/gate.py`	—	51	12	7
`terok_sandbox/commands/launch.py`	—	231	20	3
`terok_sandbox/commands/sandbox.py`	—	203	69	24
`terok_sandbox/commands/shield.py`	—	113	75	5
`terok_sandbox/commands/ssh.py`	—	686	20	23
`terok_sandbox/commands/supervisor.py`	—	83	26	3
`terok_sandbox/commands/vault.py`	—	1 177	177	30
`terok_sandbox/gate/`	4	1 378	217	36
`terok_sandbox/gate/mirror.py`	—	924	136	22
`terok_sandbox/gate/server.py`	—	445	51	10
`terok_sandbox/gate/tokens.py`	—	9	15	3
`terok_sandbox/integrations/`	3	193	182	24
`terok_sandbox/integrations/clearance.py`	—	13	27	2
`terok_sandbox/integrations/shield.py`	—	180	145	21
`terok_sandbox/resources/`	7	721	312	88
`terok_sandbox/resources/apparmor/`	1	60	28	9
`terok_sandbox/resources/bridges/`	2	83	101	17
`terok_sandbox/resources/hooks/`	2	432	121	45
`terok_sandbox/resources/hooks/_supervisor_state.py`	—	58	47	8
`terok_sandbox/resources/hooks/supervisor_hook.py`	—	374	74	37
`terok_sandbox/resources/selinux/`	1	66	33	13
`terok_sandbox/resources/supervisor_wrapper.py`	—	80	29	4
`terok_sandbox/runtime/`	7	3 231	449	142
`terok_sandbox/runtime/__init__.py`	—	68	14	4
`terok_sandbox/runtime/gpu.py`	—	533	55	26
`terok_sandbox/runtime/krun.py`	—	252	66	7
`terok_sandbox/runtime/krun_transport.py`	—	353	77	23
`terok_sandbox/runtime/null.py`	—	365	65	23
`terok_sandbox/runtime/podman.py`	—	1 375	127	38
`terok_sandbox/runtime/protocol.py`	—	285	45	21
`terok_sandbox/supervisor/`	7	1 449	305	75
`terok_sandbox/supervisor/__init__.py`	—	25	9	1
`terok_sandbox/supervisor/children.py`	—	248	96	14
`terok_sandbox/supervisor/install.py`	—	313	30	9
`terok_sandbox/supervisor/janitor.py`	—	257	58	27
`terok_sandbox/supervisor/launcher.py`	—	57	5	3
`terok_sandbox/supervisor/main.py`	—	297	59	14
`terok_sandbox/supervisor/sidecar.py`	—	252	48	7
`terok_sandbox/vault/`	16	4 352	1 118	367
`terok_sandbox/vault/daemon/`	3	940	321	115
`terok_sandbox/vault/daemon/__init__.py`	—	5	43	3
`terok_sandbox/vault/daemon/audit.py`	—	120	5	4
`terok_sandbox/vault/daemon/token_broker.py`	—	815	273	108
`terok_sandbox/vault/ssh/`	4	991	210	94
`terok_sandbox/vault/ssh/__init__.py`	—	2	21	1
`terok_sandbox/vault/ssh/keypair.py`	—	457	92	32
`terok_sandbox/vault/ssh/manager.py`	—	163	27	16
`terok_sandbox/vault/ssh/signer.py`	—	369	70	45
`terok_sandbox/vault/store/`	8	2 421	568	157
`terok_sandbox/vault/store/db.py`	—	703	100	23
`terok_sandbox/vault/store/encryption.py`	—	610	131	38
`terok_sandbox/vault/store/migrations.py`	—	129	59	15
`terok_sandbox/vault/store/recovery.py`	—	94	69	20
`terok_sandbox/vault/store/status.py`	—	375	92	23
`terok_sandbox/vault/store/systemd_creds.py`	—	395	89	32
`terok_sandbox/vault/store/tiers.py`	—	115	7	5
`terok_sandbox/__init__.py`	—	384	62	8
`terok_sandbox/__main__.py`	—	8	11	4
`terok_sandbox/_exit_codes.py`	—	3	17	5
`terok_sandbox/_setup.py`	—	469	79	18
`terok_sandbox/_stage.py`	—	237	40	16
`terok_sandbox/_yaml.py`	—	57	19	3
`terok_sandbox/cli.py`	—	65	25	19
`terok_sandbox/config.py`	—	598	52	24
`terok_sandbox/config_schema.py`	—	573	24	22
`terok_sandbox/diagnostics.py`	—	37	37	10
`terok_sandbox/doctor.py`	—	229	57	24
`terok_sandbox/launch.py`	—	650	229	59
`terok_sandbox/operator_cli.py`	—	30	4	1
`terok_sandbox/paths.py`	—	104	31	9
`terok_sandbox/port_registry.py`	—	450	63	9
`terok_sandbox/sandbox.py`	—	565	182	68
`terok_sandbox/setup_stamp.py`	—	181	46	16

Architecture¶

Module Dependency Graph¶

graph TD
    terok_sandbox.port_registry --> terok_sandbox.paths
    terok_sandbox.setup_stamp --> terok_sandbox.paths
    terok_sandbox.config_schema --> terok_sandbox.paths
    terok_sandbox.config --> terok_sandbox.paths
    terok_sandbox.config --> terok_sandbox.port_registry
    terok_sandbox.config --> terok_sandbox.vault.store.db
    terok_sandbox.config --> terok_sandbox.vault.store.encryption
    terok_sandbox.config --> terok_sandbox.config_schema
    terok_sandbox.doctor --> terok_sandbox._stage
    terok_sandbox.doctor --> terok_sandbox.config
    terok_sandbox.doctor --> terok_sandbox.paths
    terok_sandbox.doctor --> terok_sandbox.vault.daemon
    terok_sandbox.doctor --> terok_sandbox.vault.store.encryption
    terok_sandbox.doctor --> terok_sandbox.vault.store.recovery
    terok_sandbox.vault --> terok_sandbox.vault.daemon.token_broker
    terok_sandbox.vault.store.db --> terok_sandbox.vault.store.migrations
    terok_sandbox.vault.store.db --> terok_sandbox.vault.store.encryption
    terok_sandbox.vault.store.db --> terok_sandbox.vault.store.tiers
    terok_sandbox.vault.store.encryption --> terok_sandbox.vault.store.systemd_creds
    terok_sandbox.vault.store.encryption --> terok_sandbox.vault.store.tiers
    terok_sandbox.vault.store.recovery --> terok_sandbox._yaml
    terok_sandbox.vault.store.recovery --> terok_sandbox.config
    terok_sandbox.vault.store.recovery --> terok_sandbox.vault.store.encryption
    terok_sandbox.vault.store.recovery --> terok_sandbox.vault.store.tiers
    terok_sandbox.vault.store.status --> terok_sandbox.config
    terok_sandbox.vault.store.status --> terok_sandbox.vault.store.encryption
    terok_sandbox.vault.store.status --> terok_sandbox.vault.store.recovery
    terok_sandbox.vault.store.status --> terok_sandbox.vault.store.tiers
    terok_sandbox.vault.ssh.signer --> terok_sandbox.vault.store.db
    terok_sandbox.vault.ssh.signer --> terok_sandbox.vault.daemon.token_broker
    terok_sandbox.vault.daemon.token_broker --> terok_sandbox.vault.daemon
    terok_sandbox.vault.daemon.token_broker --> terok_sandbox.vault.daemon.audit
    terok_sandbox.vault.daemon.token_broker --> terok_sandbox.vault.store.db
    terok_sandbox.vault.daemon.token_broker --> terok_sandbox.vault.store.encryption
    terok_sandbox.vault.daemon.token_broker --> terok_sandbox.config
    terok_sandbox.gate --> terok_sandbox.gate.server
    terok_sandbox.runtime --> terok_sandbox.config_schema
    terok_sandbox.vault.ssh.manager --> terok_sandbox.vault.ssh.keypair
    terok_sandbox.sandbox --> terok_sandbox.integrations.shield
    terok_sandbox.commands --> terok_sandbox.commands.credentials
    terok_sandbox.commands --> terok_sandbox.commands.doctor
    terok_sandbox.commands --> terok_sandbox.commands.gate
    terok_sandbox.commands --> terok_sandbox.commands.launch
    terok_sandbox.commands --> terok_sandbox.commands.sandbox
    terok_sandbox.commands --> terok_sandbox.commands.shield
    terok_sandbox.commands --> terok_sandbox.commands.ssh
    terok_sandbox.commands --> terok_sandbox.commands.supervisor
    terok_sandbox.commands --> terok_sandbox.commands.vault
    terok_sandbox.commands.sandbox --> terok_sandbox._setup
    terok_sandbox.commands.sandbox --> terok_sandbox.commands.credentials
    terok_sandbox.commands.vault --> terok_sandbox.commands.credentials
    terok_sandbox.commands.doctor --> terok_sandbox.launch
    terok_sandbox.commands.launch --> terok_sandbox.launch
    terok_sandbox.commands.supervisor --> terok_sandbox.supervisor
    terok_sandbox.supervisor --> terok_sandbox.supervisor.main
    terok_sandbox.supervisor --> terok_sandbox.supervisor.sidecar
    terok_sandbox.supervisor --> terok_sandbox.integrations.shield
    terok_sandbox.supervisor --> terok_sandbox.paths
    terok_sandbox.supervisor.main --> terok_sandbox.supervisor.children
    terok_sandbox.supervisor.main --> terok_sandbox.supervisor.launcher
    terok_sandbox.supervisor.main --> terok_sandbox.supervisor.sidecar
    terok_sandbox.supervisor.children --> terok_sandbox.supervisor.sidecar
    terok_sandbox.supervisor.children --> terok_sandbox.integrations.clearance
    terok_sandbox.supervisor.children --> terok_sandbox.vault.daemon.token_broker
    terok_sandbox.supervisor.children --> terok_sandbox.vault.ssh.signer
    terok_sandbox.supervisor.children --> terok_sandbox.gate.server
    terok_sandbox.supervisor.children --> terok_sandbox._util._selinux
    terok_sandbox.launch --> terok_sandbox.sandbox
    terok_sandbox.launch --> terok_sandbox.integrations.shield
    terok_sandbox._setup --> terok_sandbox.integrations.shield
    terok_sandbox._setup --> terok_sandbox.integrations.clearance
    terok_sandbox.cli --> terok_sandbox.commands
    terok_sandbox --> terok_sandbox.cli
    terok_sandbox --> terok_sandbox.commands
    terok_sandbox --> terok_sandbox.launch
    terok_sandbox --> terok_sandbox.sandbox
    terok_sandbox._util
    terok_sandbox.paths
    terok_sandbox._stage
    terok_sandbox.vault.store
    terok_sandbox.vault.store.migrations
    terok_sandbox.vault.store.tiers
    terok_sandbox.vault.store.systemd_creds
    terok_sandbox.vault.ssh
    terok_sandbox.vault.daemon
    terok_sandbox.vault.daemon.audit
    terok_sandbox.gate.server
    terok_sandbox.integrations.shield
    terok_sandbox.integrations.clearance
    terok_sandbox.gate.tokens
    terok_sandbox.vault.ssh.keypair
    terok_sandbox.gate.mirror
    terok_sandbox.commands._types
    terok_sandbox.operator_cli
    terok_sandbox.commands.gate
    terok_sandbox.commands.shield
    terok_sandbox.commands.ssh
    terok_sandbox.commands.credentials
    terok_sandbox.supervisor.launcher
    terok_sandbox.supervisor.sidecar
    terok_sandbox._yaml
    terok_sandbox._exit_codes

Module Boundaries¶

55 modules, 76 dependency edges — all boundaries validated.

Module Summary¶

55 modules (click to expand)

Module	Deps	Description
`terok_sandbox._util`	0	Shared repo-local helpers (fs, logging, templates, naming conventions)
`terok_sandbox.paths`	0	binders (vault_root, runtime_root, …).
`terok_sandbox.port_registry`	1	Shared port registry — depends on paths for configurable registry dir
`terok_sandbox.setup_stamp`	1	package versions via importlib.metadata, writes under namespace_state_dir.
`terok_sandbox._stage`	0	re-export.
`terok_sandbox.config_schema`	1	validation, composed by terok-executor and terok into the global config.
`terok_sandbox.config`	5	standalone sandbox and embedded (terok) paths share one validator.
`terok_sandbox.doctor`	6	Health check protocol + sandbox-level diagnostics
`terok_sandbox.vault`	1
`terok_sandbox.vault.store`	0	Vault.store — at-rest data layer.
`terok_sandbox.vault.store.db`	3
`terok_sandbox.vault.store.migrations`	0
`terok_sandbox.vault.store.tiers`	0	speak it.
`terok_sandbox.vault.store.encryption`	2
`terok_sandbox.vault.store.recovery`	4	`WrongPassphraseError` while walking the resolver chain.
`terok_sandbox.vault.store.status`	4	registry; receives `SandboxConfig` (default-fill `cfg=None`).
`terok_sandbox.vault.store.systemd_creds`	0
`terok_sandbox.vault.ssh`	0	Vault.ssh — keypair I/O + scope manager + agent protocol + sockets.
`terok_sandbox.vault.ssh.signer`	2
`terok_sandbox.vault.daemon`	0	Vault.daemon — the long-running process: lifecycle, broker, audit.
`terok_sandbox.vault.daemon.token_broker`	5
`terok_sandbox.vault.daemon.audit`	0
`terok_sandbox.gate.server`	0	only internal import is the SELinux socket-labelling helper (foundation).
`terok_sandbox.gate`	1	Gate package root
`terok_sandbox.runtime`	1	Container runtime
`terok_sandbox.integrations.shield`	0	Shield adapter (cross-package — terok_shield boundary)
`terok_sandbox.integrations.clearance`	0	Clearance adapter (cross-package — terok_clearance boundary)
`terok_sandbox.gate.tokens`	0	Gate token minter — no internal imports
`terok_sandbox.vault.ssh.manager`	1	and the keypair primitives.
`terok_sandbox.vault.ssh.keypair`	0
`terok_sandbox.gate.mirror`	0	Git gate mirror management
`terok_sandbox.sandbox`	1	Sandbox facade
`terok_sandbox.commands`	9	tuple; the package `__init__` assembles `COMMANDS` from them.
`terok_sandbox.commands._types`	0	subsystem modules in the surface layer can all import from it.
`terok_sandbox.operator_cli`	0	so any layer composing operator hints can import it.
`terok_sandbox.commands.sandbox`	2
`terok_sandbox.commands.gate`	0
`terok_sandbox.commands.shield`	0
`terok_sandbox.commands.vault`	1	`commands.sandbox` reusing the credentials setup phase.
`terok_sandbox.commands.ssh`	0
`terok_sandbox.commands.doctor`	1
`terok_sandbox.commands.credentials`	0
`terok_sandbox.commands.launch`	1
`terok_sandbox.commands.supervisor`	1
`terok_sandbox.supervisor`	4	config/paths vocabulary both parent and children read.
`terok_sandbox.supervisor.main`	3	children; no service imports of its own.
`terok_sandbox.supervisor.children`	6	one process each.
`terok_sandbox.supervisor.launcher`	0	Child spawn mechanics (Direct + systemd-run scope) — stdlib only.
`terok_sandbox.supervisor.sidecar`	0	the parent and the children; stdlib only.
`terok_sandbox._yaml`	0	Round-trip YAML writer for setup-time config.yml edits.
`terok_sandbox.launch`	2	and shield rules in one place.
`terok_sandbox._setup`	2	gate / clearance.
`terok_sandbox._exit_codes`	0	API). Zero internal imports.
`terok_sandbox.cli`	1	CLI entry point — same-layer dep on commands
`terok_sandbox`	4	Package root — same-layer deps on surface peers

Test Coverage¶

Overall line coverage: 97.8% (7834/8008 statements).

Each rectangle is a source file. Area is proportional to the number of statements; colour encodes the coverage percentage (green = fully covered, red = uncovered). Files are grouped by the first 3 directory levels.

Cognitive Complexity¶

Threshold: 15 (functions above this are listed below)

Functions analyzed: 854
Median complexity: 1.0 · Average: 2.8 · Max: 51
Within threshold (15): 97% (831/854)

    0–  3 │ ██████████████████████████████ 641 (75.1%)
    4–  6 │ █████                          115 (13.5%)
    7–  9 │ ██                              35 ( 4.1%)
   10– 12 │ █                               25 ( 2.9%)
   13– 15 │ █                               15 ( 1.8%) ◄ threshold
   16– 18 │                                  7 ( 0.8%)
   19– 21 │                                  7 ( 0.8%)
   22– 25 │                                  3 ( 0.4%)
   26+    │                                  6 ( 0.7%)

23 functions exceeding threshold:

Complexity	Function	File
51	`_stream_initial_logs`	`src/terok_sandbox/runtime/podman.py`
47	`_handle_request`	`src/terok_sandbox/vault/daemon/token_broker.py`
43	`_handle_ssh_remove`	`src/terok_sandbox/commands/ssh.py`
27	`compose`	`src/terok_sandbox/launch.py`
27	`PortRegistry::_claim_locked`	`src/terok_sandbox/port_registry.py`
26	`_RouteTable::__init__`	`src/terok_sandbox/vault/daemon/token_broker.py`
25	`_proxy_websocket`	`src/terok_sandbox/vault/daemon/token_broker.py`
22	`PortRegistry::_resolve_service_ports_locked`	`src/terok_sandbox/port_registry.py`
22	`_serve_agent_session`	`src/terok_sandbox/vault/ssh/signer.py`
21	`make_stray_sidecar_check`	`src/terok_sandbox/launch.py`
21	`Sandbox::run`	`src/terok_sandbox/sandbox.py`
20	`Sandbox::_build_cmd`	`src/terok_sandbox/sandbox.py`
19	`change_passphrase`	`src/terok_sandbox/commands/vault.py`
19	`purge_passphrase_tiers`	`src/terok_sandbox/commands/vault.py`
19	`_make_handler_class`	`src/terok_sandbox/gate/server.py`
19	`_nvidia_args`	`src/terok_sandbox/runtime/gpu.py`
18	`_handle_vault_list`	`src/terok_sandbox/commands/vault.py`
18	`PortRegistry::_read_other_claims`	`src/terok_sandbox/port_registry.py`
17	`_amd_args`	`src/terok_sandbox/runtime/gpu.py`
17	`_intel_args`	`src/terok_sandbox/runtime/gpu.py`
17	`PodmanContainer::_watch_stop`	`src/terok_sandbox/runtime/podman.py`
16	`_handle_doctor`	`src/terok_sandbox/commands/doctor.py`
16	`normalize_gpus`	`src/terok_sandbox/config_schema.py`

Dead Code Analysis¶

Confidence	Location	Issue
100% confidence	`src/terok_sandbox/cli.py:44`	unused variable 'namespace'
100% confidence	`src/terok_sandbox/cli.py:46`	unused variable 'option_string'

Docstring Coverage¶

Needed: 23; Found: 20; Missing: 3; Coverage: 87.0%
Needed: 8; Found: 7; Missing: 1; Coverage: 87.5%
Needed: 33; Found: 32; Missing: 1; Coverage: 97.0%
Needed: 14; Found: 13; Missing: 1; Coverage: 92.9%
Needed: 38; Found: 36; Missing: 2; Coverage: 94.7%
Needed: 29; Found: 28; Missing: 1; Coverage: 96.6%
Needed: 22; Found: 21; Missing: 1; Coverage: 95.5%
Needed: 27; Found: 26; Missing: 1; Coverage: 96.3%
Needed: 25; Found: 22; Missing: 3; Coverage: 88.0%
Needed: 13; Found: 11; Missing: 2; Coverage: 84.6%
Needed: 66; Found: 62; Missing: 4; Coverage: 93.9%
Needed: 85; Found: 78; Missing: 7; Coverage: 91.8%
Needed: 47; Found: 41; Missing: 6; Coverage: 87.2%
Needed: 31; Found: 29; Missing: 2; Coverage: 93.5%
Needed: 15; Found: 14; Missing: 1; Coverage: 93.3%
Needed: 49; Found: 46; Missing: 3; Coverage: 93.9%
Needed: 21; Found: 20; Missing: 1; Coverage: 95.2%
Needed: 42; Found: 40; Missing: 2; Coverage: 95.2%
Needed: 1078 - Found: 1036 - Missing: 42
Total coverage: 96.1% - Grade: Excellent

Generated by scc, complexipy, vulture, tach, and docstr-coverage.