Skip to content

Commit 33c2751

Browse files
christianalfonichristianalfoni
committed
how it works
1 parent 68db967 commit 33c2751

3 files changed

Lines changed: 297 additions & 10 deletions

File tree

‎packages/projects-docs/pages/sdk/_meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"index": "Introduction",
33
"use-cases": "Use Cases",
4+
"how-it-works": "How It Works",
45
"faq": "FAQ",
56
"pricing": "Pricing",
67
"-- sandboxes": {

‎packages/projects-docs/pages/sdk/how-it-works.mdx‎

Lines changed: 296 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
1+
---
2+
title: How It Works
3+
description: Understanding the conceptual architecture and lifecycle of Sandbox management with CodeSandbox SDK.
4+
---
5+
6+
import { Callout } from 'nextra-theme-docs'
7+
8+
# How It Works
9+
10+
The CodeSandbox SDK provides a complete cloud development infrastructure that allows you to programmatically create, manage, and interact with isolated development environments. This page explains the conceptual architecture and terminology to help you understand how Sandboxes integrate with your product.
11+
12+
## Core Architecture
13+
14+
At its heart, the SDK orchestrates three main components that work together to deliver secure, scalable development environments:
15+
16+
```mermaid
17+
graph TB
18+
subgraph "Your Application"
19+
A[Your Server/API]
20+
B[Client Applications<br/>Browser/Node/Mobile]
21+
end
22+
23+
subgraph "CodeSandbox SDK"
24+
C[SDK Instance]
25+
D[Session Management]
26+
E[Template Library]
27+
end
28+
29+
subgraph "CodeSandbox Infrastructure"
30+
F[Firecracker VMs<br/>Sandboxes]
31+
G[Snapshot Storage<br/>Hibernation]
32+
H[Host Routing<br/>Preview URLs]
33+
end
34+
35+
A --> C
36+
B --> D
37+
C --> E
38+
C --> F
39+
F --> G
40+
F --> H
41+
42+
style F fill:#e1f5fe
43+
style G fill:#f3e5f5
44+
style H fill:#e8f5e8
45+
```
46+
47+
## Key Concepts
48+
49+
### Templates
50+
**Templates** are pre-configured environment snapshots that serve as the foundation for creating Sandboxes. Think of them as "golden images" that contain:
51+
- Pre-installed dependencies
52+
- Development server configurations
53+
- Custom Docker environments
54+
- Setup tasks and workflows
55+
56+
Templates ensure consistent, fast Sandbox creation and eliminate the need to install dependencies every time.
57+
58+
### Sandboxes
59+
**Sandboxes** are isolated virtual machines (Firecracker VMs) running your development environments. Each Sandbox:
60+
- Runs completely isolated from others
61+
- Has persistent file storage with git integration
62+
- Can be hibernated and resumed with full state preservation
63+
- Exposes services through secure host URLs
64+
65+
### Sessions
66+
**Sessions** provide secure, permission-controlled access to Sandboxes. Each session:
67+
- Maps to a specific user with consistent identity
68+
- Controls read/write permissions
69+
- Manages git credentials and environment variables
70+
- Enables secure host access through tokens
71+
72+
## The Sandbox Lifecycle
73+
74+
Understanding how Sandboxes move through their lifecycle is crucial for effective integration:
75+
76+
```mermaid
77+
stateDiagram-v2
78+
[*] --> Template: Build Template<br/>(CLI)
79+
80+
state "Template Storage" as Template {
81+
[*] --> Snapshot: Optimized VM<br/>Snapshots Created
82+
}
83+
84+
Template --> Creating: Create Sandbox<br/>(SDK)
85+
86+
state "Active Sandbox" as Active {
87+
Creating --> Running: Firecracker VM<br/>Started
88+
Running --> Connected: Client<br/>Connected
89+
Connected --> Working: User<br/>Development
90+
Working --> Connected: Ongoing<br/>Activity
91+
}
92+
93+
Active --> Hibernating: Auto/Manual<br/>Hibernation
94+
95+
state "Hibernated State" as Hibernated {
96+
Hibernating --> Snapshot_Saved: VM Snapshot<br/>Created (3-10s)
97+
}
98+
99+
Hibernated --> Resuming: Resume Request<br/>(SDK/Auto)
100+
Resuming --> Active: Snapshot Restored<br/>(0.5-2s)
101+
102+
Hibernated --> Archived: 4 Day<br/>Timeout
103+
Archived --> [*]: Memory Released<br/>Files Persisted
104+
```
105+
106+
### Phase 1: Template Creation
107+
1. **Development**: Create your project structure locally
108+
2. **Configuration**: Add `.codesandbox/tasks.json` with setup tasks and dev server config
109+
3. **Building**: Use CLI to deploy optimized snapshots across global clusters
110+
4. **Storage**: Template becomes available for rapid Sandbox creation
111+
112+
### Phase 2: Sandbox Management
113+
1. **Creation**: Instantiate new Sandboxes from templates (~1-3 seconds)
114+
2. **Connection**: Establish secure sessions with appropriate permissions
115+
3. **Development**: Users interact with the environment through clients
116+
4. **Hibernation**: Automatically or manually pause Sandboxes to save resources
117+
5. **Resume**: Restore exact state when needed (~0.5-2 seconds)
118+
119+
### Phase 3: Resource Management
120+
1. **Monitoring**: Track active Sandboxes and resource usage
121+
2. **Scaling**: Manage VM tiers and concurrent limits
122+
3. **Persistence**: Files auto-persist via git, snapshots expire after 4 days
123+
4. **Cleanup**: Archive unused Sandboxes to optimize costs
124+
125+
## Client Architecture
126+
127+
The SDK supports multiple client environments, each designed for specific use cases:
128+
129+
```mermaid
130+
graph LR
131+
subgraph "Client Types"
132+
A[Server SDK<br/>Direct Access]
133+
B[Node Client<br/>React Native, etc.]
134+
C[Browser Client<br/>Web Applications]
135+
end
136+
137+
subgraph "Session Flow"
138+
D[Session Creation<br/>Server-side]
139+
E[Token Management<br/>Security Layer]
140+
F[Connection Handling<br/>Auto-reconnect]
141+
end
142+
143+
subgraph "Sandbox Interaction"
144+
G[File System API<br/>Read/Write/Watch]
145+
H[Terminal API<br/>Shell Commands]
146+
I[Preview API<br/>Web Previews]
147+
J[Host Management<br/>Secure URLs]
148+
end
149+
150+
A --> D
151+
B --> D
152+
C --> D
153+
D --> E
154+
E --> F
155+
F --> G
156+
F --> H
157+
F --> I
158+
F --> J
159+
160+
style A fill:#bbdefb
161+
style B fill:#c8e6c9
162+
style C fill:#fff3e0
163+
```
164+
165+
### Server SDK
166+
Direct integration for backend applications where the SDK manages Sandbox lifecycle directly.
167+
168+
### Client SDKs
169+
Browser and Node clients that connect through session tokens, enabling:
170+
- Secure access without exposing API keys
171+
- Automatic reconnection and state management
172+
- Real-time interaction with Sandbox services
173+
174+
## Host and Preview System
175+
176+
When your Sandbox runs services (like development servers), they become accessible through a sophisticated routing system:
177+
178+
```mermaid
179+
graph TB
180+
subgraph "Sandbox Environment"
181+
A[Dev Server<br/>Port 3000]
182+
B[API Server<br/>Port 8080]
183+
C[Database<br/>Port 5432]
184+
end
185+
186+
subgraph "Host Routing Layer"
187+
D[Secure Host URLs<br/>sandbox-id.sse.codesandbox.io]
188+
E[Token Validation<br/>Access Control]
189+
F[Port Mapping<br/>Service Discovery]
190+
end
191+
192+
subgraph "Client Access"
193+
G[Browser Preview<br/>Embedded iframe]
194+
H[Direct API Calls<br/>Authenticated]
195+
I[Public Access<br/>If configured]
196+
end
197+
198+
A --> F
199+
B --> F
200+
C --> F
201+
F --> D
202+
D --> E
203+
E --> G
204+
E --> H
205+
E --> I
206+
207+
style D fill:#e3f2fd
208+
style E fill:#fce4ec
209+
style F fill:#e8f5e8
210+
```
211+
212+
### Privacy Levels
213+
- **Public**: Sandbox and hosts are publicly accessible
214+
- **Private**: Requires tokens for all access
215+
- **Public-hosts**: Sandbox is private, but services are publicly accessible
216+
217+
### Preview Integration
218+
The Preview API enables embedding Sandbox services directly in your application with:
219+
- Secure iframe embedding
220+
- Message passing for communication
221+
- Navigation controls and custom code injection
222+
223+
## Integration Patterns
224+
225+
### Pattern 1: User Development Environments
226+
Perfect for educational platforms, coding interviews, or team development:
227+
228+
1. Create templates for different tech stacks
229+
2. Provision Sandboxes per user/project
230+
3. Manage sessions tied to user accounts
231+
4. Handle hibernation based on user activity
232+
233+
### Pattern 2: AI Code Interpretation
234+
Ideal for AI agents that need to execute code safely:
235+
236+
1. Create specialized templates for different runtimes
237+
2. Spin up Sandboxes per agent task
238+
3. Use filesystem API for code execution
239+
4. Hibernate immediately after task completion
240+
241+
### Pattern 3: CI/CD and Testing
242+
Scale testing across multiple environments:
243+
244+
1. Build template with test setup
245+
2. Fork Sandboxes for parallel test execution
246+
3. Use terminal API to run test suites
247+
4. Aggregate results and clean up resources
248+
249+
<Callout>
250+
**Best Practice**: Always use templates built with the CLI rather than generic setups. Pre-configured templates with snapshots provide the fastest, most reliable Sandbox creation experience and ensure consistency across your application.
251+
</Callout>
252+
253+
## Resource Management
254+
255+
Understanding resource management helps optimize costs and performance:
256+
257+
```mermaid
258+
graph LR
259+
subgraph "VM Tiers"
260+
A[Pico<br/>0.5 vCPU, 1GB RAM]
261+
B[Nano<br/>0.5 vCPU, 2GB RAM]
262+
C[Micro<br/>1 vCPU, 2GB RAM]
263+
D[Small<br/>2 vCPU, 4GB RAM]
264+
E[Medium<br/>4 vCPU, 8GB RAM]
265+
F[Large<br/>8 vCPU, 16GB RAM]
266+
end
267+
268+
subgraph "Usage Patterns"
269+
G[Light Development<br/>Documentation, Simple Apps]
270+
H[Standard Development<br/>Web Apps, APIs]
271+
I[Heavy Development<br/>Build Tools, Compilation]
272+
J[AI/ML Workloads<br/>Model Training, Processing]
273+
end
274+
275+
A --> G
276+
B --> G
277+
C --> H
278+
D --> H
279+
E --> I
280+
F --> J
281+
282+
style A fill:#e8f5e8
283+
style B fill:#e8f5e8
284+
style C fill:#fff3e0
285+
style D fill:#fff3e0
286+
style E fill:#ffebee
287+
style F fill:#ffebee
288+
```
289+
290+
### Cost Optimization Strategies
291+
- **Template-based creation**: Avoid dependency installation overhead
292+
- **Active hibernation**: Don't rely on timeouts, actively hibernate when done
293+
- **Right-sizing VMs**: Start with appropriate tiers, upgrade only when needed
294+
- **Session management**: Track user activity to determine optimal hibernation timing
295+
296+
The CodeSandbox SDK abstracts away the complexity of managing cloud development infrastructure while giving you complete control over the user experience. By understanding these core concepts, you can build sophisticated applications that leverage isolated, scalable development environments.

‎packages/projects-docs/pages/sdk/index.mdx‎

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -39,13 +39,3 @@ const output = await client.commands.run("echo 'Hello World'");
3939

4040
console.log(output) // Hello World
4141
```
42-
43-
## How it works
44-
45-
The SDK can spin up a sandbox by cloning a template in under 3 seconds. Inside this VM you have a full development environment.
46-
47-
Under the hood, the SDK uses CodeSandbox's microVM infrastructure to spin up sandboxes. The environment supports:
48-
49-
1. Resume/clone VMs in under 1 second
50-
2. VM FS persistence (with `git` version control)
51-
3. Environment customization using Docker & Docker Compose (Dev Containers)

0 commit comments

Comments
 (0)