🍒🔮 Jukebox-OS: Deterministic Time-Travel & ACID Tool Sandbox for AI Agents

---

"DROP THE NEEDLE ON ANY FRAME"

Jukebox-OS is a high-performance, deterministic flight-recorder and Copy-on-Write (CoW) ACID sandbox runtime designed specifically for multi-agent architectures.

Stop letting your autonomous agents accidentally wipe your production database or burn through hundreds of dollars in infinite recursive loops. JUKEBOX captures every single LLM prompt, token stream, MCP tool invocation, and filesystem change onto a cryptographic "vinyl tape" (.jbx). This grants your agents full BEGIN / COMMIT / ROLLBACK capabilities and enables near-instantaneous (1ms) time-travel replay.

🍽️ The Diner Menu (Overview)

• 🥞 The Blue Plate Special: Quickstart Guide
• 📋 A La Carte Menu: Architectural Deep Dive
• 🚗 Counter Service Drive-Thru: CLI Usage
• 🔥 Chef's Table: Performance Benchmarks
• 🪙 Tipping the Cooks: Contribution Guidelines

---

🍒 Why JUKEBOX?

While modern orchestration frameworks like LangGraph, AutoGen, CrewAI, or the OpenAI Agents SDK are excellent for prompt management, they typically treat side effects as "fire-and-forget."

The Problem: If a 15-step agent workflow hallucinates at Step 12, but already modified three SQL tables and five local files at Step 8, simply "checkpointing the chat history" is useless. You cannot undo the real-world damage.

The Solution: Architected by Marius Carlsson, JUKEBOX is a systems-level runtime built in Rust with Python bindings. It implements database-grade ACID transactions and deterministic replay for any AI agent stack.

🛠️ Feature Breakdown

---

⚙️ System Architecture

The following diagram illustrates how JUKEBOX intercepts agent actions to provide determinism:

---

🚀 Slide Into a Booth (Installation)

Follow these steps to get the runtime operational:

• Clone the repository
• Navigate to the directory
• Install the package in editable mode

git clone https://github.com/socrates6969/jukebox-os.git
cd jukebox-os
pip install -e .

---

💻 Implementation Example

Here is how to wrap a standard agent in a Transactional Vinyl Track:

import asyncio
from jukebox import Jukebox, SandboxPolicy, CircuitBreaker

# Initialize the runtime
jb = Jukebox(
    tape_dir="./tapes",
    sandbox=SandboxPolicy(
        filesystem="copy_on_write", 
        mcp_mode="staged_acid"
    ),
    breaker=CircuitBreaker(
        max_cost_usd=0.50, 
        max_semantic_repeat=3
    ),
)

@jb.track(name="invoice-reconciliation-agent")
async def run_accounting_agent(customer_id: str, amount_usd: float) -> dict:
    # Record the agent's thought process and cost
    async with jb.record_agent_turn(
        agent_name="planner",
        message=f"Staging refund of ${amount_usd} for {customer_id}",
        model="gpt-4o",
        cost_usd=0.008,
    ) as tx:
        
        # Stage a file write (does not hit disk yet)
        tx.stage_file_write(
            path="./tapes/staged_ledger_demo.json",
            content=f'{{"customer": "{customer_id}", "refund_usd": {amount_usd}}}'
        )

        # Safety Check: Logic-based rollback
        if amount_usd > 500.0:
            await tx.rollback(reason="Refund exceeds $500 autonomous threshold")
            return {"status": "ROLLED_BACK", "tape_id": tx.tape_id}
        
        # If we reach here, the changes are committed to the real world
        return {"status": "COMMITTED", "tape_id": tx.tape_id}

# To replay or fork:
# from jukebox import Tape
# tape = Tape.load("./tapes/some_trace.jbx")
# tape.fork(frame=9, model="claude-3-7-sonnet")

🧮 Cost Calculation Logic

The CircuitBreaker monitors the total cost $\mathcal{C}$ of a run: $\mathcal{C} = \sum_{i=1}^{n} (\text{input\_tokens}_i \times \text{rate}_{in}) + (\text{output\_tokens}_i \times \text{rate}_{out})$ If $\mathcal{C} > \text{max\_cost\_usd}$, the "needle" is tripped and the process terminates.