# tensorlakeai/tensorlake architecture

> Architecture diagram of the GitHub repository tensorlakeai/tensorlake, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tensorlakeai/tensorlake
- Repository: https://github.com/tensorlakeai/tensorlake

## Overview

Tensorlake is a cloud platform and multi-language SDK for stateful microVM sandboxes, durable cloud filesystems, and serverless function orchestration for agentic applications. The principal sandbox workflow is to create or claim a sandbox, wait until it is ready, use it to run commands and manipulate files, then snapshot or terminate it. Separate SDK capabilities cover deploying and executing applications, Document AI, and artifact storage. The graph combines README-documented product flows with source-index relationships; several unsampled subsystems are included by their tree paths, with uncertain wiring omitted.

Main entry points: [`crates/cli/src/main.rs`](https://github.com/tensorlakeai/tensorlake/blob/main/crates/cli/src/main.rs) (CLI commands), [`src/tensorlake/sandbox/client.py`](https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/sandbox/client.py) (Python sandbox client), [`src/tensorlake/sandbox/sandbox.py`](https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/sandbox/sandbox.py) (Sandbox operations), [`src/tensorlake/filesystem/client.py`](https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/filesystem/client.py) (Cloud filesystem)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_cli_entry["CLI commands<br/>[main.rs]"]
  node_cli_sbx["Sandbox commands"]
  node_cli_auth["Auth context<br/>[context.rs]"]
end

subgraph group_sandbox["Sandbox SDK"]
  node_py_client["Python sandbox client<br/>[client.py]"]
  node_py_sandbox["Sandbox operations<br/>[sandbox.py]"]
  node_ts_client["TypeScript client<br/>[client.ts]"]
  node_native_worker["Native worker bridge"]
  node_native_sandbox["Native sandbox binding<br/>[native-sandbox.ts]"]
end

subgraph group_runtime["Application Runtime"]
  node_applications["Function interface<br/>[function.py]"]
  node_manifest["Application manifests<br/>[application.py]"]
  node_remote_runner["Remote application runner<br/>[runner.py]"]
  node_executor_server["Executor server<br/>[server.py]"]
  node_blob_manager["Allocation blob manager<br/>[blob_manager.py]"]
  node_ts_executor["TypeScript executor<br/>[service.ts]"]
end

subgraph group_cloud["Cloud APIs"]
  node_cloud_sdk["Rust cloud SDK<br/>[client.rs]"]
  node_sandbox_service["Sandbox API<br/>[mod.rs]"]
  node_sandbox_images["Sandbox images<br/>[sandbox_images.rs]"]
  node_filesystem["Cloud filesystem<br/>[client.py]"]
end

subgraph group_other["Additional SDKs"]
  node_document_ai["Document AI<br/>[client.py]"]
  node_artifact_ingest["Artifact ingest<br/>[ingest.rs]"]
end

node_user(("Developer"))
node_cloud_service{{"Tensorlake cloud"}}
node_object_store[("Object storage")]

node_user -->|"runs commands"| node_cli_entry
node_cli_entry -->|"resolves auth"| node_cli_auth
node_cli_entry -->|"dispatches"| node_cli_sbx
node_cli_sbx -.->|"manages sandboxes"| node_cloud_sdk
node_user -->|"creates sandbox"| node_py_client
node_py_client -->|"connects"| node_py_sandbox
node_py_client -->|"requests sandbox"| node_cloud_service
node_py_sandbox -->|"runs and transfers files"| node_cloud_service
node_py_sandbox -->|"snapshots state"| node_cloud_service
node_user -->|"uses SDK"| node_ts_client
node_ts_client -->|"dispatches calls"| node_native_worker
node_native_worker -->|"forwards calls"| node_native_sandbox
node_native_sandbox -.->|"manages sandboxes"| node_cloud_service
node_cloud_sdk -->|"exposes operations"| node_sandbox_service
node_sandbox_service -.->|"sends API requests"| node_cloud_service
node_sandbox_images -.->|"manages images"| node_cloud_service
node_user -->|"writes file trees"| node_filesystem
node_filesystem -->|"publishes metadata"| node_cloud_service
node_filesystem -->|"transfers file data"| node_object_store
node_user -.->|"defines functions"| node_applications
node_applications -->|"describes application"| node_manifest
node_manifest -.->|"configures execution"| node_remote_runner
node_remote_runner -.->|"runs remotely"| node_cloud_service
node_executor_server -.->|"serves executor protocol"| node_ts_executor
node_ts_executor -->|"loads functions"| node_applications
node_blob_manager -.->|"handles output blobs"| node_object_store
node_user -.->|"uses document APIs"| node_document_ai
node_user -->|"pushes artifacts"| node_artifact_ingest
node_artifact_ingest -->|"uploads chunks"| node_cloud_service

click node_cli_entry "https://github.com/tensorlakeai/tensorlake/blob/main/crates/cli/src/main.rs"
click node_cli_sbx "https://github.com/tensorlakeai/tensorlake/tree/main/crates/cli/src/commands/sbx"
click node_cli_auth "https://github.com/tensorlakeai/tensorlake/blob/main/crates/cli/src/auth/context.rs"
click node_py_client "https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/sandbox/client.py"
click node_py_sandbox "https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/sandbox/sandbox.py"
click node_ts_client "https://github.com/tensorlakeai/tensorlake/blob/main/typescript/src/client.ts"
click node_native_worker "https://github.com/tensorlakeai/tensorlake/blob/main/typescript/src/native-worker-client.ts"
click node_native_sandbox "https://github.com/tensorlakeai/tensorlake/blob/main/typescript/src/native-sandbox.ts"
click node_cloud_sdk "https://github.com/tensorlakeai/tensorlake/blob/main/crates/cloud-sdk/src/client.rs"
click node_sandbox_service "https://github.com/tensorlakeai/tensorlake/blob/main/crates/cloud-sdk/src/sandboxes/mod.rs"
click node_sandbox_images "https://github.com/tensorlakeai/tensorlake/blob/main/crates/cloud-sdk/src/sandbox_images.rs"
click node_filesystem "https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/filesystem/client.py"
click node_applications "https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/applications/interface/function.py"
click node_manifest "https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/applications/remote/manifests/application.py"
click node_remote_runner "https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/applications/remote/runner.py"
click node_executor_server "https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/function_executor/server.py"
click node_blob_manager "https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/function_executor/allocation_runner/blob_manager.py"
click node_ts_executor "https://github.com/tensorlakeai/tensorlake/blob/main/typescript/src/function-executor/service.ts"
click node_document_ai "https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/documentai/client.py"
click node_artifact_ingest "https://github.com/tensorlakeai/tensorlake/blob/main/crates/cloud-sdk/src/artifact_storage/ingest.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_entry,node_cli_sbx,node_cli_auth toneBlue
class node_py_client,node_py_sandbox,node_ts_client,node_native_worker,node_native_sandbox,node_object_store toneAmber
class node_applications,node_manifest,node_remote_runner,node_executor_server,node_blob_manager,node_ts_executor toneMint
class node_cloud_sdk,node_sandbox_service,node_sandbox_images,node_filesystem toneRose
class node_document_ai,node_artifact_ingest,node_user,node_cloud_service toneIndigo
```

## Components

### CLI

- [CLI commands](https://github.com/tensorlakeai/tensorlake/blob/main/crates/cli/src/main.rs): `crates/cli/src/main.rs`
- [Sandbox commands](https://github.com/tensorlakeai/tensorlake/tree/main/crates/cli/src/commands/sbx): `crates/cli/src/commands/sbx`
- [Auth context](https://github.com/tensorlakeai/tensorlake/blob/main/crates/cli/src/auth/context.rs): `crates/cli/src/auth/context.rs`

### Sandbox SDK

- [Python sandbox client](https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/sandbox/client.py): `src/tensorlake/sandbox/client.py`
- [Sandbox operations](https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/sandbox/sandbox.py): `src/tensorlake/sandbox/sandbox.py`
- [TypeScript client](https://github.com/tensorlakeai/tensorlake/blob/main/typescript/src/client.ts): `typescript/src/client.ts`
- [Native worker bridge](https://github.com/tensorlakeai/tensorlake/blob/main/typescript/src/native-worker-client.ts): `typescript/src/native-worker-client.ts`
- [Native sandbox binding](https://github.com/tensorlakeai/tensorlake/blob/main/typescript/src/native-sandbox.ts): `typescript/src/native-sandbox.ts`

### Application Runtime

- [Function interface](https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/applications/interface/function.py): `src/tensorlake/applications/interface/function.py`
- [Application manifests](https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/applications/remote/manifests/application.py): `src/tensorlake/applications/remote/manifests/application.py`
- [Remote application runner](https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/applications/remote/runner.py): `src/tensorlake/applications/remote/runner.py`
- [Executor server](https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/function_executor/server.py): `src/tensorlake/function_executor/server.py`
- [Allocation blob manager](https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/function_executor/allocation_runner/blob_manager.py): `src/tensorlake/function_executor/allocation_runner/blob_manager.py`
- [TypeScript executor](https://github.com/tensorlakeai/tensorlake/blob/main/typescript/src/function-executor/service.ts): `typescript/src/function-executor/service.ts`

### Cloud APIs

- [Rust cloud SDK](https://github.com/tensorlakeai/tensorlake/blob/main/crates/cloud-sdk/src/client.rs): `crates/cloud-sdk/src/client.rs`
- [Sandbox API](https://github.com/tensorlakeai/tensorlake/blob/main/crates/cloud-sdk/src/sandboxes/mod.rs): `crates/cloud-sdk/src/sandboxes/mod.rs`
- [Sandbox images](https://github.com/tensorlakeai/tensorlake/blob/main/crates/cloud-sdk/src/sandbox_images.rs): `crates/cloud-sdk/src/sandbox_images.rs`
- [Cloud filesystem](https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/filesystem/client.py): `src/tensorlake/filesystem/client.py`

### Additional SDKs

- [Document AI](https://github.com/tensorlakeai/tensorlake/blob/main/src/tensorlake/documentai/client.py): `src/tensorlake/documentai/client.py`
- [Artifact ingest](https://github.com/tensorlakeai/tensorlake/blob/main/crates/cloud-sdk/src/artifact_storage/ingest.rs): `crates/cloud-sdk/src/artifact_storage/ingest.rs`

### Other components

- **Developer**
- **Tensorlake cloud**
- **Object storage**

## Connections

- Developer → CLI commands: runs commands
- CLI commands → Auth context: resolves auth (evidence: `crates/cli/src/main.rs`)
- CLI commands → Sandbox commands: dispatches (evidence: `crates/cli/src/main.rs`)
- Sandbox commands → Rust cloud SDK: manages sandboxes
- Developer → Python sandbox client: creates sandbox
- Python sandbox client → Sandbox operations: connects (evidence: `src/tensorlake/sandbox/client.py`)
- Python sandbox client → Tensorlake cloud: requests sandbox
- Sandbox operations → Tensorlake cloud: runs and transfers files
- Sandbox operations → Tensorlake cloud: snapshots state
- Developer → TypeScript client: uses SDK
- TypeScript client → Native worker bridge: dispatches calls (evidence: `typescript/src/client.ts`)
- Native worker bridge → Native sandbox binding: forwards calls (evidence: `typescript/src/native-worker-client.ts`)
- Native sandbox binding → Tensorlake cloud: manages sandboxes
- Rust cloud SDK → Sandbox API: exposes operations (evidence: `crates/cloud-sdk/src/client.rs`)
- Sandbox API → Tensorlake cloud: sends API requests
- Sandbox images → Tensorlake cloud: manages images
- Developer → Cloud filesystem: writes file trees
- Cloud filesystem → Tensorlake cloud: publishes metadata
- Cloud filesystem → Object storage: transfers file data
- Developer → Function interface: defines functions
- Function interface → Application manifests: describes application (evidence: `src/tensorlake/applications/remote/manifests/application.py`)
- Application manifests → Remote application runner: configures execution
- Remote application runner → Tensorlake cloud: runs remotely
- Executor server → TypeScript executor: serves executor protocol
- TypeScript executor → Function interface: loads functions (evidence: `typescript/src/function-executor/service.ts`)
- Allocation blob manager → Object storage: handles output blobs
- Developer → Document AI: uses document APIs
- Developer → Artifact ingest: pushes artifacts (evidence: `crates/cloud-sdk/src/artifact_storage/ingest.rs`)
- Artifact ingest → Tensorlake cloud: uploads chunks (evidence: `crates/cloud-sdk/src/artifact_storage/ingest.rs`)
