Backend

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. Recommended Solution: CloudDriveBackend

​

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