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/Drex-Dotz.git@v0.1.0"

Two-Command Install (Explicit Firewall Dependency)

If your environment prefers explicit dependency pre-installation:

pip install "git+https://github.com/colt2822/Drex-Agent-Firewall.git@v0.1.3"
pip install "git+https://github.com/colt2822/Drex-Dotz.git@v0.1.0"

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:

1. Researcher (dotz/examples/researcher/): Web research, reading local documentation, and compiling notes. Denied shell execution and destructive filesystem modification.
2. Developer (dotz/examples/developer/): Workspace code navigation and test execution. Consequential file edits require explicit, time-bounded mutation grants.
3. 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.