Skip to content

Commit a35be52

Browse files
mintlify[bot]dobrac
mintlify[bot]
and
dobrac
authored
Improve start & ready command documentation (#191)
Co-authored-by: Jakub Dobry <jakub.dobry8@gmail.com> Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
1 parent 0c20e14 commit a35be52

1 file changed

Lines changed: 139 additions & 22 deletions

File tree

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

Lines changed: 139 additions & 22 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,159 @@ 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&nbsp;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'
3536

36-
// Set custom start and ready command
37-
template.setStartCmd('npm start', 'curl -s -o /dev/null -w "200"')
37+
// Start a Python HTTP server and wait for it to listen on port 8000
38+
const template = Template()
39+
.fromUbuntuImage("22.04")
40+
.aptInstall(["curl", "python3"])
41+
.setStartCmd('python3 -m http.server 8000', waitForPort(8000))
42+
```
3843

39-
// Set only ready command
40-
template.setReadyCmd(waitForTimeout(10_000))
44+
```python Python
45+
from e2b import Template, wait_for_port, wait_for_url, wait_for_timeout
46+
47+
# Start a Python HTTP server and wait for it to listen on port 8000
48+
template = (
49+
Template()
50+
.from_ubuntu_image("22.04")
51+
.apt_install(["curl", "python3"])
52+
.set_start_cmd("python3 -m http.server 8000", wait_for_port(8000))
53+
)
54+
```
55+
56+
</CodeGroup>
57+
58+
You can also pass a custom shell command as the ready command instead of using a helper:
59+
60+
<CodeGroup>
61+
62+
```typescript JavaScript & TypeScript
63+
// Start command with a custom ready command
64+
template.setStartCmd('npm start', 'curl -s http://localhost:3000/health')
4165
```
4266

4367
```python Python
44-
# Set both start command and ready command
45-
template.set_start_cmd("npm start", wait_for_port(3000))
68+
# Start command with a custom ready command
69+
template.set_start_cmd("npm start", "curl -s http://localhost:3000/health")
70+
```
4671

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

50-
# Set only ready command
51-
template.set_ready_cmd(wait_for_timeout(10_000))
74+
More examples:
75+
76+
<CodeGroup>
77+
78+
```typescript JavaScript & TypeScript
79+
import { Template, waitForURL, waitForPort } from 'e2b'
80+
81+
// Next.js app — wait for the dev server URL
82+
template.setStartCmd('npx next --turbo', waitForURL('http://localhost:3000'))
83+
84+
// Python HTTP server — wait for port 8000
85+
template.setStartCmd('python -m http.server 8000', waitForPort(8000))
86+
87+
// VNC desktop — wait for the VNC port
88+
template.setStartCmd('/start_command.sh', waitForPort(6080))
89+
```
90+
91+
```python Python
92+
from e2b import Template, wait_for_url, wait_for_port
93+
94+
# Next.js app — wait for the dev server URL
95+
template.set_start_cmd("npx next --turbo", wait_for_url("http://localhost:3000"))
96+
97+
# Python HTTP server — wait for port 8000
98+
template.set_start_cmd("python -m http.server 8000", wait_for_port(8000))
99+
100+
# VNC desktop — wait for the VNC port
101+
template.set_start_cmd("/start_command.sh", wait_for_port(6080))
52102
```
53103

54104
</CodeGroup>
55105

56-
The ready command is used to determine when the sandbox is ready to accept connections.
106+
## `setReadyCmd` / `set_ready_cmd`
107+
108+
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.
109+
110+
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.
111+
112+
<CodeGroup>
113+
114+
```typescript JavaScript & TypeScript
115+
import { Template, waitForTimeout, waitForPort, waitForFile } from 'e2b'
116+
117+
// Wait 10 seconds before taking the snapshot
118+
const template = Template()
119+
.fromUbuntuImage("22.04")
120+
.runCmd("apt-get install -y nginx && service nginx start")
121+
.setReadyCmd(waitForPort(80))
122+
```
123+
124+
```python Python
125+
from e2b import Template, wait_for_timeout, wait_for_port, wait_for_file
126+
127+
# Wait for nginx to start listening before taking the snapshot
128+
template = (
129+
Template()
130+
.from_ubuntu_image("22.04")
131+
.run_cmd("apt-get install -y nginx && service nginx start")
132+
.set_ready_cmd(wait_for_port(80))
133+
)
134+
```
135+
136+
</CodeGroup>
137+
138+
More examples:
139+
140+
<CodeGroup>
141+
142+
```typescript JavaScript & TypeScript
143+
// Wait for a file to be created by a background process
144+
template.setReadyCmd(waitForFile('/tmp/ready'))
145+
146+
// Wait a fixed duration for the system to stabilize
147+
template.setReadyCmd(waitForTimeout(10_000))
148+
149+
// Custom readiness check
150+
template.setReadyCmd('curl -s http://localhost:8080/health')
151+
```
152+
153+
```python Python
154+
# Wait for a file to be created by a background process
155+
template.set_ready_cmd(wait_for_file("/tmp/ready"))
156+
157+
# Wait a fixed duration for the system to stabilize
158+
template.set_ready_cmd(wait_for_timeout(10_000))
159+
160+
# Custom readiness check
161+
template.set_ready_cmd("curl -s http://localhost:8080/health")
162+
```
163+
164+
</CodeGroup>
57165

58166
## Ready command helpers
59167

60-
The SDK provides helper functions for common ready command patterns:
168+
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`.
61169

62170
<CodeGroup>
63171

64172
```typescript JavaScript & TypeScript
65173
import {
66174
waitForPort,
175+
waitForURL,
67176
waitForProcess,
68177
waitForFile,
69178
waitForTimeout,
@@ -72,30 +181,38 @@ import {
72181
// Wait for a port to be available
73182
waitForPort(3000)
74183

184+
// Wait for a URL to return a specific status code (defaults to 200)
185+
waitForURL('http://localhost:3000/health')
186+
waitForURL('http://localhost:3000/health', 200)
187+
75188
// Wait for a process to be running
76189
waitForProcess('node')
77190

78191
// Wait for a file to exist
79192
waitForFile('/tmp/ready')
80193

81-
// Wait for a timeout
194+
// Wait for a specified duration
82195
waitForTimeout(10_000) // 10 seconds
83196
```
84197

85198
```python Python
86-
from e2b import wait_for_port, wait_for_process, wait_for_file, wait_for_timeout
199+
from e2b import wait_for_port, wait_for_url, wait_for_process, wait_for_file, wait_for_timeout
87200

88201
# Wait for a port to be available
89202
wait_for_port(3000)
90203

204+
# Wait for a URL to return a specific status code (defaults to 200)
205+
wait_for_url("http://localhost:3000/health")
206+
wait_for_url("http://localhost:3000/health", 200)
207+
91208
# Wait for a process to be running
92209
wait_for_process("node")
93210

94211
# Wait for a file to exist
95212
wait_for_file("/tmp/ready")
96213

97214
# Wait for a specified duration
98-
wait_for_timeout(10_000) # 10 seconds
215+
wait_for_timeout(10_000) # 10 seconds
99216
```
100217

101218
</CodeGroup>

0 commit comments

Comments
 (0)