Architecture

Design Philosophy

Transactional does not reinvent infrastructure. Instead, it wraps best-in-class providers and self-hosted engines behind a unified API layer that handles auth, billing, and observability consistently across all primitives.

This means you get the reliability of purpose-built systems with the simplicity of a single integration.

System Diagram

                        Your Agent / App
                              |
                     @usetransactional/node SDK
                              |
                    +---------+---------+
                    |   Transactional   |
                    |    API Gateway    |
                    |  (Auth + Billing  |
                    |  + Observability) |
                    +---------+---------+
                              |
          +--------+----------+----------+---------+
          |        |          |          |         |
     Sandboxes  Browsers  Code Exec  File Sys  Email/AI
          |        |          |          |         |
        E2B   Browserbase  Piston    R2/S3    SES/LLMs
     (managed)  (managed)  (self)   (managed)  (managed)

Provider Architecture

Managed Providers

Self-Hosted Services

The Unified Layer

Every request to any primitive passes through the same middleware:

Authentication

A single API key (tx_sk_*) authenticates across all primitives. No separate accounts or tokens needed for sandboxes, browsers, code execution, or file storage.

// One key for everything
const tx = new Transactional({ apiKey: 'tx_sk_...' });
 
await tx.sandboxes.create({ ... });  // Same key
await tx.browsers.create();           // Same key
await tx.code.run({ ... });           // Same key
await tx.files.upload({ ... });       // Same key

Billing

All primitive usage rolls up into a single invoice:

• Sandboxes — Billed per second of VM uptime
• Browsers — Billed per session minute
• Code Execution — Billed per execution (generous free tier)
• File Systems — Billed per GB stored (zero egress)

Per-agent cost breakdowns are available in the dashboard, so you can see exactly how much each agent workflow costs.

Observability

Every primitive operation emits structured traces to the Observability module:

• Sandbox lifecycle events (create, execute, destroy)
• Browser actions (navigate, click, screenshot)
• Code execution results (runtime, duration, exit code)
• File operations (upload, download, delete)

Traces are correlated by agent session, so you can follow a single agent run across all four primitives in one timeline.

The Composition Model

The primitives are designed to be composed, not used in isolation. A typical agent workflow combines multiple primitives in a single run:

Agent receives task
    |
    +-> Sandbox: Install dependencies, run complex scripts
    |
    +-> Browser: Navigate web pages, extract data
    |
    +-> Code Execution: Quick transformations and formatting
    |
    +-> File System: Store intermediate results and outputs
    |
    +-> Email: Send final results to user

Why Separate Code Execution and Sandboxes?

They serve different purposes:

Use Code Execution for data transformations, formatting, and quick computations. Use Sandboxes when you need a full environment with package installation, file I/O, and long-running processes.

Integration with Platform Modules

Agent primitives are first-class citizens alongside existing Transactional modules:

• AI Gateway — Your agent's LLM calls go through the gateway for caching and failover, while tool calls use sandboxes and browsers
• Memory — Store and retrieve agent context across sessions
• Email — Agents can send transactional emails as part of their workflow
• Auth — Secure agent endpoints with the same auth infrastructure

Next Steps

• Quickstart — Build a complete agent loop in 5 minutes
• Sandboxes — Deep dive into isolated execution environments
• Browsers — Headless browser automation
• Code Execution — Multi-language script execution
• File Systems — Persistent agent storage