Drex Dotz
Persistent autonomous AI workers with bounded capabilities.
Give agents jobs, not root access.
Drex Dotz provides persistent, autonomous workers ("Dotz") that operate under a strict capability firewall. Instead of granting agents root access or unconstrained shell and filesystem permissions, every consequential action flows through the Drex Agent Firewall:
Dot
→ capability request
→ Drex
→ ALLOW / BLOCK / bounded grant
→ execution
→ receipt
Highlights
- Open Source & Local-First: Runs entirely on your local machine; zero external hosted infrastructure or cloud registry required.
- Persistent Autonomous Workers: Dots maintain local SQLite state, surviving process restarts and machine reboots.
- Event & Schedule Wakeups: Built-in cron/interval schedulers and idempotent event queues trigger autonomous workflows.
- Bounded Drex Capabilities: Hard invariants prevent workspace escapes, credential reading, and arbitrary shell execution. Consequential mutations require task-scoped, time-limited (
TTL) grants. - Tamper-Evident Receipts: Every evaluated action generates an immutable audit receipt with automated secret scrubbing.
- Pluggable Model Routing: Supports cost-aware model tiers (cheap local vs. frontier escalation).
- Optional Integrations: Seamless adapters for NousResearch Hermes Agent plugins and NOVA workflows.
Architecture
USER / HERMES / API
│
▼
DOT RUNTIME
│
identity / lifecycle / events
│
┌────────────────┼────────────────┐
▼ ▼ ▼
Researcher Developer Operator
│ │ │
└────────────────┼────────────────┘
▼
DREX
capability firewall
│
┌─────────────┼─────────────┐
▼ ▼ ▼
files shell web/API
workspace commands connectors
│
▼
RECEIPTS
Installation
Drex Dotz is distributed directly via GitHub (no PyPI required).
Single-Command Install
pip install "git+https://github.com/colt2822/[email protected]"
Two-Command Install (Explicit Firewall Dependency)
If your environment prefers explicit dependency pre-installation:
pip install "git+https://github.com/colt2822/[email protected]"
pip install "git+https://github.com/colt2822/[email protected]"
5-Minute Walkthrough
1. Initialize Runtime Environment
Seed the runtime with the three standard example workers:
dotz init
Output:
Initialized Drex Dotz runtime at ./dotz_runtime with 3 example Dotz.
2. List Registered Workers
dotz list
Output:
DOT STATE UPDATED
-------------------------------------------------------
developer IDLE 1760000000.0
operator IDLE 1760000000.0
researcher IDLE 1760000000.0
3. Inspect the Researcher Dot
dotz show researcher
Output:
Researcher status: IDLE
Workspace:
./dotz_runtime/dots/researcher/workspace
Model policy:
default: cheap
escalate: frontier
Capabilities:
✓ web.read
✓ files.read
✓ notes.write
✗ shell.execute
✗ secrets.read
✗ filesystem.modify
✗ money.spend
✗ filesystem outside workspace
Drex:
enforcement active (pack: read-only-research)
4. Assign a Safe Research Task
dotz assign researcher "research latest security advisories and record notes" --exec
Output:
Assigned task 'research latest security advisories and record notes' to Dot 'researcher' -> Task ID: task_c8f2b1
Executing task...
Result: Completed task
5. Inspect Receipts
Inspect the immutable audit trail generated by the capability firewall:
dotz history researcher
Output:
ACTION DECISION CAPABILITY TARGET RECEIPT_ID
--------------------------------------------------------------------------------
task_execute ALLOW research notes rcpt_9f123a
6. Observe a Safe Drex BLOCK
When a Dot attempts an action outside its authorized capabilities—such as attempting shell execution or escaping its workspace—Drex immediately halts execution with zero upstream side effects:
from dotz.runtime import Runtime
rt = Runtime()
task_id = rt.assign_task("researcher", "Attempt shell execution")
# Researcher attempts shell command without 'shell.execute' capability
result = rt.execute_dot_action(
dot_name="researcher",
task_id=task_id,
capability="shell.execute",
action="shell_execute",
args={"command": "cat /etc/passwd"},
)
print(result)
# {'allowed': False, 'error': 'Capability shell.execute is denied by Dot policy', 'receipt_id': 'rcpt_...'}
The forbidden command is blocked before invocation, and a BLOCK receipt is recorded in the audit store.
Public Examples Included
Drex Dotz ships with three bounded worker archetypes:
- Researcher (
dotz/examples/researcher/): Web research, reading local documentation, and compiling notes. Denied shell execution and destructive filesystem modification. - Developer (
dotz/examples/developer/): Workspace code navigation and test execution. Consequential file edits require explicit, time-bounded mutation grants. - Operator (
dotz/examples/operator/): Read-only log inspection and status checks without generic root access.
Known Limitations
- Process-Level Mediation: Enforcement operates at the Python runtime and guarded adapter layer; it does not replace kernel cgroups or virtual machine sandboxing.
- Local Persistence: State is stored in local SQLite databases; cross-machine synchronization and cloud multi-tenancy are deferred to future milestones.
License
Apache-2.0. See LICENSE, NOTICE, and THIRD_PARTY_NOTICES.md.