Sandbox Blueprint

Crate Architecture

Sandbox blueprints use a three-layer crate hierarchy:

{name}-runtime/          (L1: stable runtime contracts, reusable across blueprints)
  ├── runtime.rs         — container lifecycle, CreateSandboxParams, SandboxRecord
  ├── operator_api.rs    — Axum HTTP router, middleware, rate limiting
  ├── session_auth.rs    — EIP-191 + PASETO session management
  ├── scoped_session_auth.rs — sandbox/instance scope enforcement
  ├── auth.rs            — sidecar bearer token validation
  ├── store.rs           — PersistentStore (JSON filesystem, RwLock)
  ├── reaper.rs          — idle/lifetime enforcement, tiered GC
  ├── circuit_breaker.rs — three-state circuit breaker
  ├── metrics.rs         — atomic counters for telemetry
  ├── provision_progress.rs — multi-phase progress tracking
  ├── secret_provisioning.rs — two-phase secret injection
  ├── contracts.rs       — SandboxProvider + RuntimeAdapter traits
  ├── http.rs            — sidecar HTTP client with auth headers
  ├── tee/               — TEE backend trait + implementations
  ├── firecracker.rs     — Firecracker host-agent integration
  └── error.rs           — typed error taxonomy

{name}-blueprint-lib/    (L2: product-specific job handlers)
  ├── lib.rs             — Router setup, ABI types, job ID constants
  ├── jobs/              — per-job handler functions
  └── state.rs           — product-specific state helpers

{name}-blueprint-bin/    (L3: binary entry point)
  └── main.rs            — BlueprintRunner wiring, background services, startup

Variant pattern: A single runtime crate can support multiple deployment modes:

• Cloud mode: Multi-instance per service, lifecycle via on-chain jobs
• Instance mode: Single instance per service, auto-provisioned at startup
• TEE instance mode: Instance mode with hardware enclave isolation

Each mode gets its own lib + bin crate pair sharing the same runtime.

On-Chain vs Off-Chain Split

On-chain jobs (state-changing mutations only):

• Create/delete instances
• Workflow create/trigger/cancel
• Any operation that must be auditable on-chain

Operator API (everything else):

• exec, prompt, task, stop, resume
• SSH, terminal, secrets injection
• Snapshot, health checks, status queries
• Instance access and configuration

Rule: Jobs mutate state. Reads and operational I/O go through the operator HTTP API. Never put secrets or large payloads in on-chain job calldata.

Job Handler Pattern

use blueprint_sdk::Router;
use blueprint_sdk::tangle::layers::TangleLayer;

pub const JOB_CREATE: u32 = 0;
pub const JOB_DELETE: u32 = 1;

pub fn router() -> Router {
    Router::new()
        .route(JOB_CREATE, create_instance.layer(TangleLayer))
        .route(JOB_DELETE, delete_instance.layer(TangleLayer))
}

Job handlers extract on-chain arguments via TangleArg<T> and return results via TangleResult<T>:

use blueprint_sdk::tangle::extract::{TangleArg, TangleResult, Caller, CallId};
use blueprint_sdk::tangle::layers::TangleLayer;

pub async fn create_instance(
    TangleArg(request): TangleArg<CreateRequest>,
    caller: Caller,
    call_id: CallId,
    context: Context<RuntimeState>,
) -> TangleResult<CreateOutput> {
    // Validate caller is service owner
    // Create container via runtime adapter
    // Track provision progress
    // Return result
    Ok(TangleResult(output))
}

ABI types use sol! macro for on-chain encoding:

use alloy_sol_types::sol;

sol! {
    struct CreateRequest {
        string name;
        string image;
        uint64 cpu_cores;
        uint64 memory_mb;
        uint64 disk_gb;
        string metadata_json;
    }

    struct CreateOutput {
        string sandbox_id;
        string sidecar_url;
        string token;
    }
}

Instance Provisioning Flow

Multi-phase provisioning with progress tracking:

1. Job received: Validate caller, parse ABI args
2. Backend selection: Docker, Firecracker, or TEE based on request metadata
3. Image pull: If SIDECAR_PULL_IMAGE=true and image not cached
4. Container create: Build container config (env, ports, resources, security)
5. Container start: Start and wait for sidecar health
6. Health check: Verify sidecar responds on HTTP port
7. Token generation: 32-byte hex, cryptographically random, server-side only
8. SSH setup: If enabled, generate keys and configure
9. TEE attestation: If TEE backend, collect attestation document
10. Record persistence: Store SandboxRecord to persistent store
11. Ready: Return sandbox ID, sidecar URL, token

Progress Tracking

// Phases: Queued → ImagePull → ContainerCreate → ContainerStart → HealthCheck → Ready | Failed
// Queryable via operator API: GET /api/provisions/{call_id}
// Polls every 2s from frontend via useProvisionProgress()

Lifecycle State Machine

Two primary states with tiered storage transitions:

                   ┌──────────┐
          create → │ Running  │ ← resume (from any tier)
                   └────┬─────┘
                        │ stop (idle timeout / manual / max lifetime)
                        ▼
                   ┌──────────┐
                   │ Stopped  │
                   └────┬─────┘
                        │ GC tiers (automatic)
                        ▼
            Hot (container) ──1d──→ Warm (committed image)
            Warm ──2d──→ Cold (S3 snapshot)
            Cold ──7d──→ Gone (deleted)

• Hot → Warm: docker commit preserves filesystem state
• Warm → Cold: TAR upload to S3
• Cold → Gone: S3 object deletion
• Resume: Restores from whichever tier is available (Hot > Warm > Cold)
• User BYOS3: Never deleted by operator GC

Key Fields on SandboxRecord

pub struct SandboxRecord {
    pub id: String,
    pub owner: String,                    // immutable after creation
    pub sidecar_url: Option<String>,
    pub token: String,
    pub state: SandboxState,              // Running | Stopped
    pub created_at: i64,
    pub last_activity_at: i64,
    pub max_lifetime_seconds: u64,
    pub idle_timeout_seconds: u64,
    pub cpu_cores: u64,
    pub memory_mb: u64,
    pub disk_gb: u64,
    pub snapshot_image_id: Option<String>,  // Warm tier
    pub snapshot_s3_url: Option<String>,    // Cold tier
    pub tee_deployment_id: Option<String>,
    pub base_env_json: Option<String>,
    pub user_env_json: Option<String>,
}

Sidecar Integration

Communication Pattern

• Each sandbox gets a unique 32-byte hex bearer token (server-side generated)
• Sidecar calls use Authorization: Bearer {token} header
• Token comparison uses constant-time equality (subtle::ConstantTimeEq)
• Request correlation via x-request-id header (unique per request)

Per-Operation Timeouts

const SIDECAR_EXEC_TIMEOUT: Duration = Duration::from_secs(30);
const SIDECAR_AGENT_TIMEOUT: Duration = Duration::from_secs(90);  // LLM inference
const SIDECAR_DEFAULT_TIMEOUT: Duration = Duration::from_secs(60);

Session Auth

Three-tier auth model:

1. EIP-191 Challenge-Response

Client: POST /api/auth/challenge → { challenge, expires_at }
Client: Signs challenge with wallet (personal_sign)
Client: POST /api/auth/verify → { signature, challenge } → { token, expires_at }

• Challenge TTL: 5 minutes
• Session TTL: 1 hour
• Address recovery from ECDSA signature via k256

2. PASETO v4.local Session Tokens

• Symmetric encryption with SESSION_AUTH_SECRET (32-byte hex, required in production)
• Payload: { address, scope, issued_at, expires_at }
• No database lookup needed — token is self-contained

3. Scoped Sessions

• Scopes: sandbox:{id} (cloud mode) or instance:{id} (instance mode)
• Enforces owner + scope binding: token for sandbox A cannot access sandbox B
• Extracted via middleware on every protected route

Two-Phase Secret Provisioning

Secrets never appear in on-chain calldata:

Phase 1 (on-chain): JOB_CREATE with base_env_json only (non-sensitive config)

Phase 2 (off-chain): Secrets injected via operator API

• Standard path: POST /api/sandboxes/{id}/secrets → container recreated with merged env
• TEE path: POST /api/sandboxes/{id}/tee/sealed-secrets → client encrypts to TEE public key

Phase 1: On-chain create → base config only
Phase 2: Off-chain inject → secrets merged, container recreated

Key functions: inject_secrets(), wipe_secrets(), merge_env_json()

Invariant: Sandbox identity (ID, token) is preserved across secret injection — the container is recreated but the record is the same.

TEE Backend Abstraction

pub trait TeeBackend: Send + Sync {
    async fn deploy(&self, params: TeeDeployParams) -> Result<TeeDeployment>;
    async fn attestation(&self, deployment_id: &str) -> Result<TeeAttestation>;
    async fn stop(&self, deployment_id: &str) -> Result<()>;
    async fn destroy(&self, deployment_id: &str) -> Result<()>;
    fn tee_type(&self) -> TeeType;
    // Optional: sealed secrets support
}

Backends: phala (dstack), aws_nitro, gcp, azure, direct (local TDX/SEV)

Selected via TEE_BACKEND env var. Backend factory in tee/backend_factory.rs.

Operator API Pattern

Axum-based HTTP server running alongside the BlueprintRunner:

// In main.rs:
let router = operator_api_router();
let listener = TcpListener::bind((bind_addr, api_port)).await?;
let server = axum::serve(listener, router).with_graceful_shutdown(shutdown_signal());