Skip to content

Commit cff9fdb

Browse files
mintlify[bot]mintlify[bot]
authored
Improve start & ready command documentation clarity
Generated-By: mintlify-agent
1 parent 0c20e14 commit cff9fdb

1 file changed

Lines changed: 146 additions & 23 deletions

File tree

‎docs/template/start-ready-command.mdx‎

Lines changed: 146 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ description: "Define running processes for the sandbox"
44
---
55

66
## Start command
7-
The start command lets you specify a process that runs at the **end of the template build** — not when a sandbox is created.
7+
8+
The start command specifies a process that runs at the **end of the template build** — not when a sandbox is created.
89
During the build, E2B executes the start command, waits for the [ready command](#ready-command) to confirm the process is up, and then takes a [snapshot](/docs/template/how-it-works) of the entire sandbox including the running process.
910

1011
When you later create a sandbox from that template, the snapshotted process is **already running** — there is no startup wait.
@@ -19,51 +20,165 @@ This is how you get servers, seeded databases, or any long-running process avail
1920
You can see the full build process [here](/docs/template/how-it-works).
2021

2122
## Ready command
22-
The ready command allows you to specify a command that will determine **template sandbox** readiness before a [snapshot](/docs/template/how-it-works) is created.
23+
24+
The ready command determines when the sandbox is ready before a [snapshot](/docs/template/how-it-works) is created.
2325
It is executed in an infinite loop until it returns a successful **exit code 0**.
24-
This way you can control how long should we wait for the [start command](/docs/template/start-ready-command#start-command) or any system state.
26+
This lets you control how long the build waits for the [start command](#start-command) or any other system state to be ready.
2527

26-
## Usage
28+
## `setStartCmd` / `set_start_cmd`
2729

28-
Set the start command (executed during template build) and the ready command (determines when the process is up before snapshotting):
30+
Use `setStartCmd` / `set_start_cmd` when you want to run a process during the template build **and** wait for it to be ready. This method accepts **two arguments**: the start command and the ready command.
2931

3032
<CodeGroup>
3133

3234
```typescript JavaScript & TypeScript
33-
// Set both start command and ready command
34-
template.setStartCmd('npm start', waitForPort(3000))
35+
import { Template, waitForPort, waitForURL, waitForTimeout } from 'e2b'
36+
37+
// Start an HTTP server and wait for it to listen on port 3000
38+
const template = Template()
39+
.fromUbuntuImage("22.04")
40+
.aptInstall(["curl", "nodejs", "npm"])
41+
.setWorkdir('/app')
42+
.copy("package.json", "/app/package.json")
43+
.runCmd("npm install")
44+
.setStartCmd('npm start', waitForPort(3000))
45+
```
46+
47+
```python Python
48+
from e2b import Template, wait_for_port, wait_for_url, wait_for_timeout
49+
50+
# Start an HTTP server and wait for it to listen on port 3000
51+
template = (
52+
Template()
53+
.from_ubuntu_image("22.04")
54+
.apt_install(["curl", "nodejs", "npm"])
55+
.set_workdir("/app")
56+
.copy("package.json", "/app/package.json")
57+
.run_cmd("npm install")
58+
.set_start_cmd("npm start", wait_for_port(3000))
59+
)
60+
```
3561

36-
// Set custom start and ready command
37-
template.setStartCmd('npm start', 'curl -s -o /dev/null -w "200"')
62+
</CodeGroup>
3863

39-
// Set only ready command
40-
template.setReadyCmd(waitForTimeout(10_000))
64+
You can also pass a custom shell command as the ready command instead of using a helper:
65+
66+
<CodeGroup>
67+
68+
```typescript JavaScript & TypeScript
69+
// Start command with a custom ready command
70+
template.setStartCmd('npm start', 'curl -s http://localhost:3000/health')
4171
```
4272

4373
```python Python
44-
# Set both start command and ready command
45-
template.set_start_cmd("npm start", wait_for_port(3000))
74+
# Start command with a custom ready command
75+
template.set_start_cmd("npm start", "curl -s http://localhost:3000/health")
76+
```
4677

47-
# Set custom start and ready command
48-
template.set_start_cmd("npm start", 'curl -s -o /dev/null -w "200"')
78+
</CodeGroup>
4979

50-
# Set only ready command
51-
template.set_ready_cmd(wait_for_timeout(10_000))
80+
More real-world examples:
81+
82+
<CodeGroup>
83+
84+
```typescript JavaScript & TypeScript
85+
import { Template, waitForURL, waitForPort } from 'e2b'
86+
87+
// Next.js app — wait for the dev server URL
88+
template.setStartCmd('npx next --turbo', waitForURL('http://localhost:3000'))
89+
90+
// Python HTTP server — wait for port 8000
91+
template.setStartCmd('python -m http.server 8000', waitForPort(8000))
92+
93+
// VNC desktop — wait for the VNC port
94+
template.setStartCmd('/start_command.sh', waitForPort(6080))
95+
```
96+
97+
```python Python
98+
from e2b import Template, wait_for_url, wait_for_port
99+
100+
# Next.js app — wait for the dev server URL
101+
template.set_start_cmd("npx next --turbo", wait_for_url("http://localhost:3000"))
102+
103+
# Python HTTP server — wait for port 8000
104+
template.set_start_cmd("python -m http.server 8000", wait_for_port(8000))
105+
106+
# VNC desktop — wait for the VNC port
107+
template.set_start_cmd("/start_command.sh", wait_for_port(6080))
108+
```
109+
110+
</CodeGroup>
111+
112+
## `setReadyCmd` / `set_ready_cmd`
113+
114+
Use `setReadyCmd` / `set_ready_cmd` when you **don't need a start command** but still want to control when the sandbox snapshot is taken. This method accepts only **one argument**: the ready command.
115+
116+
This is useful when your template's build steps (e.g., `runCmd` / `run_cmd`) already start a background process or when you just need extra time for the system to settle before snapshotting.
117+
118+
<CodeGroup>
119+
120+
```typescript JavaScript & TypeScript
121+
import { Template, waitForTimeout, waitForPort, waitForFile } from 'e2b'
122+
123+
// Wait 10 seconds before taking the snapshot
124+
const template = Template()
125+
.fromUbuntuImage("22.04")
126+
.runCmd("apt-get install -y nginx && service nginx start")
127+
.setReadyCmd(waitForPort(80))
128+
```
129+
130+
```python Python
131+
from e2b import Template, wait_for_timeout, wait_for_port, wait_for_file
132+
133+
# Wait for nginx to start listening before taking the snapshot
134+
template = (
135+
Template()
136+
.from_ubuntu_image("22.04")
137+
.run_cmd("apt-get install -y nginx && service nginx start")
138+
.set_ready_cmd(wait_for_port(80))
139+
)
52140
```
53141

54142
</CodeGroup>
55143

56-
The ready command is used to determine when the sandbox is ready to accept connections.
144+
More examples:
145+
146+
<CodeGroup>
147+
148+
```typescript JavaScript & TypeScript
149+
// Wait for a file to be created by a background process
150+
template.setReadyCmd(waitForFile('/tmp/ready'))
151+
152+
// Wait a fixed duration for the system to stabilize
153+
template.setReadyCmd(waitForTimeout(10_000))
154+
155+
// Custom readiness check
156+
template.setReadyCmd('curl -s http://localhost:8080/health')
157+
```
158+
159+
```python Python
160+
# Wait for a file to be created by a background process
161+
template.set_ready_cmd(wait_for_file("/tmp/ready"))
162+
163+
# Wait a fixed duration for the system to stabilize
164+
template.set_ready_cmd(wait_for_timeout(10_000))
165+
166+
# Custom readiness check
167+
template.set_ready_cmd("curl -s http://localhost:8080/health")
168+
```
169+
170+
</CodeGroup>
57171

58172
## Ready command helpers
59173

60-
The SDK provides helper functions for common ready command patterns:
174+
The SDK provides helper functions for common ready command patterns. These can be used with both `setStartCmd` / `set_start_cmd` and `setReadyCmd` / `set_ready_cmd`.
61175

62176
<CodeGroup>
63177

64178
```typescript JavaScript & TypeScript
65179
import {
66180
waitForPort,
181+
waitForURL,
67182
waitForProcess,
68183
waitForFile,
69184
waitForTimeout,
@@ -72,30 +187,38 @@ import {
72187
// Wait for a port to be available
73188
waitForPort(3000)
74189

190+
// Wait for a URL to return a specific status code (defaults to 200)
191+
waitForURL('http://localhost:3000/health')
192+
waitForURL('http://localhost:3000/health', 200)
193+
75194
// Wait for a process to be running
76195
waitForProcess('node')
77196

78197
// Wait for a file to exist
79198
waitForFile('/tmp/ready')
80199

81-
// Wait for a timeout
200+
// Wait for a specified duration (in milliseconds, minimum 1000)
82201
waitForTimeout(10_000) // 10 seconds
83202
```
84203

85204
```python Python
86-
from e2b import wait_for_port, wait_for_process, wait_for_file, wait_for_timeout
205+
from e2b import wait_for_port, wait_for_url, wait_for_process, wait_for_file, wait_for_timeout
87206

88207
# Wait for a port to be available
89208
wait_for_port(3000)
90209

210+
# Wait for a URL to return a specific status code (defaults to 200)
211+
wait_for_url("http://localhost:3000/health")
212+
wait_for_url("http://localhost:3000/health", 200)
213+
91214
# Wait for a process to be running
92215
wait_for_process("node")
93216

94217
# Wait for a file to exist
95218
wait_for_file("/tmp/ready")
96219

97-
# Wait for a specified duration
98-
wait_for_timeout(10_000) # 10 seconds
220+
# Wait for a specified duration (in milliseconds, minimum 1000)
221+
wait_for_timeout(10_000) # 10 seconds
99222
```
100223

101224
</CodeGroup>

0 commit comments

Comments
 (0)