Skip to main content
DeepAgents Backend manages Agent file system operations, including artifact storage, user cloud drive, and long-term memory.

​
1. Overview

​
1.1 Current Issues

​
1.2 Goals

  • All artifacts are automatically persisted to cloud storage
  • Users have a “cloud drive” experience with access to their files at any time
  • Unified storage architecture to reduce complexity

​
2. DeepAgents Backend Types

DeepAgents provides the following Backend types:

​
3.1 Architecture Design

​
3.2 Storage Structure

​
4. CloudDriveBackend Overview

CloudDriveBackend is a persistent file backend built on Supabase Storage with the following features:
  • Isolated storage space per user
  • All files are automatically persisted
  • Redis cache for acceleration
  • Support for large files (images, documents, etc.)
Storage structure:
  • /workspace/ - Workspace files (Agent artifacts)
  • /memory/ - Long-term memory (user knowledge)
Path mapping rules:
  • Virtual path /code/main.py maps to users/{user_id}/workspace/code/main.py
  • Virtual path /memory/facts.json maps to users/{user_id}/memory/facts.json
CloudDriveBackend implements the full BackendProtocol interface, including file listing, reading, writing, editing, searching, glob matching, uploading, and downloading operations.

​
4.1 Integration

BaseService manages CloudDriveBackend instances through Redis cache and a per-user Backend cache. Each user has an independent Backend instance, accessed via get_backend(user_id).

​
5. Desktop Mode Support

When users are on the Desktop app, the system automatically selects the appropriate Backend based on the device type:
  • Desktop mode: Uses FilesystemBackend (local file system)
  • Cloud mode: Uses CloudDriveBackend (Supabase Storage)

​
6. Frontend Cloud Drive API

The frontend interacts with the cloud drive through the following API endpoints:
  • GET /api/storage/list?path=... - List files
  • POST /api/storage/upload - Upload files
  • GET /api/storage/download?path=... - Download files
  • DELETE /api/storage/delete?path=... - Delete files
  • GET /api/storage/url?path=... - Get preview URL

​
7. Sandbox Artifact Sync

When the E2B sandbox generates files, the system automatically syncs the artifacts to the user’s cloud drive, stored under the /workspace/sandbox-output/{date}/ path.

​
8. Performance Optimization

​
8.1 Redis Cache Performance

​
8.2 Cache Strategy

  • Workspace files TTL: 5 minutes
  • Memory files TTL: 10 minutes
  • Cache is updated immediately after writes/edits

​
9. Migration Steps

  1. Create Supabase Storage Bucket - Create the workspace bucket in the Supabase Dashboard
  2. Configure RLS Policies - Ensure users can only access their own files
  3. Configure Environment Variables - Set SUPABASE_URL, SUPABASE_SERVICE_KEY, REDIS_URL (optional)
  4. Create CloudDriveBackend - Implement the core Backend logic
  5. Modify BaseService - Integrate CloudDriveBackend
  6. Remove Old Code - Remove StateBackend and InMemoryStore related usage

​
10. Summary