Data Model and Storage

Entities

erDiagram
  %%{init: {"theme":"base","themeVariables":{"primaryColor":"#1e293b","primaryTextColor":"#f8fafc","primaryBorderColor":"#38bdf8","lineColor":"#64748b","attributeBackgroundColor":"#1e293b","attributeTextColor":"#f8fafc"}}}%%
  SESSION ||--o{ EXECUTION : runs
  SESSION ||--o{ FILE : indexes
  SESSION ||--o{ ARTIFACT : exports
  SESSION ||--o{ SNAPSHOT : creates
  SESSION {
    string id
    string workspace_id
    string status
    string backend
    datetime expires_at
  }
  EXECUTION {
    string id
    string status
    int exit_code
    string stdout_path
    string stderr_path
  }
  ARTIFACT {
    string artifact_uri
    string source_path
    string sha256
  }
  SNAPSHOT {
    string digest
    string image_ref
    boolean include_workspace
  }

Storage layout

~/.nexus-sandbox/sandbox.db stores metadata. Scratch workspaces live under scratch/<session_id>/workspace; execution logs live under a session-specific log root; artifacts live under artifacts; optional snapshot workspace bundles live under snapshot-workspaces. Microsandbox VM disk snapshots live in the microsandbox-managed directory.

Integrity and consistency

Files and artifacts expose SHA-256 hashes. Artifact sync applies include/exclude globs and records source path, URI, size, and digest. Session deletion removes runtime state and workspace metadata; artifact retention is separate and should be made explicit.

Snapshot restore couples a VM snapshot with an optional workspace tarball. The API validates workspace identity before restore, avoiding accidental cross-workspace state attachment.