You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Sprites are persistent, stateful environments that maintain their filesystem and state between runs. This page covers how Sprites manage their lifecycle, including hibernation, persistence, and resource allocation.
9
+
This page is about what happens to a Sprite after you create it. Where it lives, how it sleeps, when it wakes up, and what it remembers.
10
10
11
-
## Automatic Hibernation
11
+
We'll cover how Sprites hibernate when idle, what counts as “activity,” what persists on resume, and how storage behaves under the hood.
12
12
13
-
Sprites automatically hibernate when inactive to minimize costs. While hibernated:
13
+
## The Sprite Lifecycle
14
14
15
-
-**No compute charges** - You only pay for storage
16
-
-**Full state preserved** - All files and data intact
17
-
-**Instant wake** - Resume execution immediately on next request
15
+
Sprites aren't always running. That's the whole point. Once launched, a Sprite starts in an active state, ready to do work. If it sits idle for a while, it hibernates. That shuts down compute but keeps its state on disk. Later, when something pokes it (like a CLI call or HTTP request), it resumes.
18
16
19
-
### Default Behavior
17
+
This model keeps things lean. Sprites pause when you're not using them, so you don't burn CPU or RAM just to keep state around. It also keeps billing predictable — storage sticks around, compute doesn't.
20
18
21
-
By default, Sprites hibernate after **30 seconds** of inactivity. This timeout is not configurable yet.
19
+
The platform handles this automatically by tracking usage. If nothing interacts with a Sprite for long enough, it goes to sleep. If something hits it again, it spins back up and picks up where it left off.
22
20
23
-
### Activity Detection
21
+
You don't have to manage any of this directly. But it helps to know what's going on, especially if you're optimizing for latency or trying to debug weird behavior on resume.
24
22
25
-
A Sprite is considered **active** when any of the following are true:
23
+
## Automatic Hibernation
26
24
27
-
1. A command is executing (via `exec` or `console`)
28
-
2. Data is being written to stdin
29
-
3. There's an active TCP connection to the Sprite's URL
30
-
4. A detachable session is running
25
+
Sprites automatically hibernate when they're no longer doing anything useful. The default timeout is **30 seconds**, and it's not configurable yet.
31
26
32
-
The inactivity timer resets each time activity is detected.
27
+
A Sprite is considered *active* when any of the following are true:
33
28
34
-
## Wake-on-Request
29
+
- A command is executing (via `exec` or the console)
30
+
- Data is being written to `stdin`
31
+
- There's an active TCP connection to the Sprite's URL
32
+
- A detachable session is running
35
33
36
-
When you interact with a hibernated Sprite, it automatically wakes:
34
+
If none of those are happening, the Sprite is considered idle. The inactivity timer starts at 30 seconds and resets whenever new activity is detected. Once the timer runs out, the Sprite hibernates. At that point, you're only billed for storage.
37
35
38
-
```bash
39
-
# Sprite is hibernated...
40
-
sprite exececho"hello"# Sprite wakes, runs command, result returns
36
+
While hibernated, Sprites have:
37
+
38
+
-**No compute charges** — You only pay for storage
39
+
-**Full state preserved** — All files and data stay intact
40
+
-**Instant wake** — Sprite resumes execution on the next request
41
+
42
+
## Wake-on-Request
41
43
42
-
# Next command uses already-awake sprite
43
-
sprite exececho"world"# Fast, no wake needed
44
-
```
44
+
Sprites wake up automatically when something tries to use them. This could be a CLI command, an HTTP request to a running service, or a call to the API. You don't have to manually start anything.
45
45
46
-
Wake time is typically under a few seconds. Your data, installed packages, and filesystem state are all preserved.
46
+
Wake time is typically under a few seconds. The Sprite picks up where it left off. Disk state is preserved, but any running processes are gone. If a request comes in while the Sprite is hibernated, it will block until the Sprite is ready.
47
47
48
-
## Persistence
48
+
You don't need to change anything in your code to handle this. But if your workflow is latency-sensitive, it helps to know what's happening under the hood.
49
49
50
-
### Filesystem
50
+
##Persistence Fundamentals
51
51
52
-
Every Sprite has a persistent **ext4 filesystem**:
52
+
Every Sprite has a persistent ext4 filesystem. That means files you write stick around between hibernations, even if the Sprite shuts down completely. You get the benefits of local storage with the durability of object storage, and you don't have to think about where the bits live.
53
53
54
-
-**100GB** provisioned storage (current default)
55
-
-**Standard ext4** compatibility (SQLite, shared memory, all tools work)
56
-
-**TRIM-friendly** billing (pay only for actual data)
54
+
When a Sprite is active, it writes to fast NVMe-backed storage. When it hibernates, that storage is snapshotted and moved to object storage. On resume, the snapshot is restored and mounted back in — same data, same paths, same state.
57
55
58
-
### How Persistence Works
56
+
Refer to this diagram to visualize how this works:
59
57
60
58
<LifecycleDiagram />
61
59
62
-
### What's Persisted
60
+
### What you get:
61
+
62
+
-**100 GB provisioned storage** (default)
63
+
-**Standard ext4 compatibility** — SQLite works. `shm` works. Most tools work without surprises.
64
+
-**TRIM-friendly billing** — you only pay for the actual data stored, not the full 100 GB.
65
+
66
+
This isn't a custom virtual filesystem or an S3 shim. It's real disk, with real semantics. If your app expects local writes to behave like Linux, it'll feel at home here.
67
+
68
+
### What's preserved (and what isn't)
69
+
70
+
Here's a quick reference on what survives hibernation:
63
71
64
72
| Persisted | Not Persisted |
65
73
|-----------|---------------|
@@ -69,24 +77,22 @@ Every Sprite has a persistent **ext4 filesystem**:
69
77
| Git repositories | Temporary `/tmp` files |
70
78
| Databases (SQLite, etc.) | Process PIDs |
71
79
72
-
### Storage Limits
80
+
Hibernation clears out compute state, but your data and filesystem don't go anywhere. If your workload can start cleanly from disk, this works great. If it needs long-lived processes or runtime state, you'll want to look at **Services** or **Detachable Sessions**, which we'll get to shortly.
81
+
82
+
## Resource Profile
73
83
74
-
| Metric | Value |
75
-
|--------|-------|
76
-
| Provisioned size | 100 GB (current default) |
77
-
| Billing | Actual data written |
84
+
Sprites run with fixed resources:
78
85
79
-
<Callouttype="info">
80
-
Storage is TRIM-friendly, meaning you only pay for data actually written to disk. Deleting files reduces your storage costs.
81
-
</Callout>
86
+
-**8 vCPUs**
87
+
-**8 GB RAM**
88
+
-**100 GB persistent storage**
82
89
83
-
## Resource Allocation
90
+
You can't resize them (yet). That's by design — one size, no config. It keeps things simple and predictable.
84
91
85
-
Sprites currently run with a fixed configuration (8 vCPUs, 8192 MB RAM, 100 GB storage). These values are not configurable yet.
86
92
87
93
## Sprite States
88
94
89
-
Sprites have internal lifecycle states such as:
95
+
Sprites move through a few internal states depending on what they're doing. These aren't yet exposed in the CLI or SDK, but they can show up in logs or support traces.
90
96
91
97
| State | Description |
92
98
|-------|-------------|
@@ -99,76 +105,30 @@ Sprites have internal lifecycle states such as:
99
105
100
106
These states are not currently exposed in CLI/SDK responses.
101
107
102
-
## Services
103
-
104
-
For processes that need to run continuously and survive Sprite restarts, use **Services** instead of detachable sessions. Services are managed through the internal API and automatically restart when your Sprite boots.
108
+
## Detached Sessions
105
109
106
-
### Services vs Detachable Sessions
110
+
Detached sessions let you run long-lived processes inside a Sprite without keeping a connection open. Think of it like starting a background job and coming back later to check on it.
107
111
108
-
| Feature | Services | Detachable Sessions |
109
-
|---------|----------|---------------------|
110
-
| Survives Sprite restart | Yes | No |
111
-
| Auto-starts on boot | Yes | No |
112
-
| Managed via | Internal API (`curl-sprite-api`) | External CLI/SDK |
113
-
| Dependencies | Supported | Not supported |
114
-
| Best for | Daemons, dev servers | One-off tasks, builds |
112
+
Sessions persist across CLI disconnects and can survive hibernation. If the Sprite goes to sleep mid-task, the session resumes when it wakes. This makes them ideal for long-running or asynchronous work.
115
113
116
-
### Creating a Service
114
+
If you're looking to run a persistent service that automatically starts on wake, see [Services](/concepts/services) for complete documentation.
117
115
118
-
From inside your Sprite:
119
-
120
-
```bash
121
-
# Create a service that auto-starts on boot
122
-
curl-sprite-api -X PUT /v1/services/devserver -d '{
123
-
"cmd": "npm",
124
-
"args": ["run", "dev"]
125
-
}'
126
-
127
-
# List running services
128
-
curl-sprite-api /v1/services
129
-
130
-
# Stop a service
131
-
curl-sprite-api -X DELETE /v1/services/devserver
132
-
```
133
-
134
-
See [Services](/concepts/services) for complete documentation.
135
116
136
117
## Best Practices
137
118
138
-
### Optimize for Hibernation
139
-
140
-
1.**Clean up temporary files** before long idle periods
141
-
2.**Use SQLite** or file-based databases that persist naturally
142
-
3.**Plan for 30s idle hibernation** (keep activity running if you need the sprite warm)
143
-
144
-
### Handle Wake Latency
145
-
146
-
```javascript
147
-
// For latency-sensitive operations, pre-warm the sprite
148
-
constsprite=awaitclient.getSprite('my-sprite');
149
-
150
-
// This exec will wake the sprite if hibernated
151
-
awaitsprite.exec('true');
152
-
153
-
// Now the sprite is warm for subsequent operations
You don't need to micromanage Sprite lifecycle — it mostly just works. But a few habits can make things smoother:
160
120
161
-
1. Use **detachable sessions** so commands survive disconnection
162
-
2. Consider **services** if the process should auto-start on boot
163
-
3. Consider **checkpoints** to save progress periodically
121
+
-**Use SQLite or file-based databases.** The filesystem is persistent, so tools that store data in files just work. You don't need to wire up external storage for most use cases.
122
+
-**Plan for 30s idle hibernation.** If you need a Sprite to stay warm, keep something running — a background process or open session will do it.
123
+
-**Clean up temporary state before idle.** If your Sprite drops temp files or leaves things half-written, make sure they get flushed before it hibernates.
124
+
-**Checkpoint long-running work.** Detached sessions survive hibernation, but writing progress to disk gives you more control — and makes debugging easier.
125
+
-**Don't fight the lifecycle.** Sprites hibernate for a reason. Unless you've got a real-time use case, let them sleep.
If you're running something where latency matters and you want to keep a Sprite warm, consider using Services or a background process — but use that power sparingly.
169
128
170
129
## Related Documentation
171
130
131
+
-[Services](/concepts/services/) — Run persistent processes that restart automatically on resume.
172
132
-[Checkpoints](/concepts/checkpoints) - Save and restore state
173
133
-[Configuration](/reference/configuration) - All configuration options
0 commit comments