Start & ready commands

Define running processes for the sandbox

Start command

The start command specifies a process that runs at the end of the template build — not when a sandbox is created. During the build, E2B executes the start command, waits for the ready command to confirm the process is up, and then takes a snapshot of the entire sandbox including the running process.

When you later create a sandbox from that template, the snapshotted process is already running — there is no startup wait. This is how you get servers, seeded databases, or any long-running process available instantly when spawning sandboxes with the SDK.

The start command runs once during template build and is captured in a snapshot. It does not re-execute each time you create a sandbox. If you need to run a command every time a sandbox is created, use sandbox.commands.run() after creating the sandbox instead.

This also means that environment variables passed to Sandbox.create() are not available to the start command process — it already ran during the build. If your start command needs environment variables, set them in the template definition using setEnvs() / set_envs().

You can see the full build process here.

Ready command

The ready command determines when the sandbox is ready before a snapshot is created. It is executed in an infinite loop until it returns a successful exit code 0. This lets you control how long the build waits for the start command or any other system state to be ready.

setStartCmd / set_start_cmd

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.

JavaScript & TypeScript

import { Template, waitForPort, waitForURL, waitForTimeout } from 'e2b'

// Start a Python HTTP server and wait for it to listen on port 8000
const template = Template()
  .fromUbuntuImage("22.04")
  .aptInstall(["curl", "python3"])
  .setStartCmd('python3 -m http.server 8000', waitForPort(8000))

from e2b import Template, wait_for_port, wait_for_url, wait_for_timeout

# Start a Python HTTP server and wait for it to listen on port 8000
template = (
    Template()
    .from_ubuntu_image("22.04")
    .apt_install(["curl", "python3"])
    .set_start_cmd("python3 -m http.server 8000", wait_for_port(8000))
)

You can also pass a custom shell command as the ready command instead of using a helper:

JavaScript & TypeScript

// Start command with a custom ready command
template.setStartCmd('npm start', 'curl -s http://localhost:3000/health')

# Start command with a custom ready command
template.set_start_cmd("npm start", "curl -s http://localhost:3000/health")

More examples:

JavaScript & TypeScript

import { Template, waitForURL, waitForPort } from 'e2b'

// Next.js app — wait for the dev server URL
template.setStartCmd('npx next --turbo', waitForURL('http://localhost:3000'))

// Python HTTP server — wait for port 8000
template.setStartCmd('python -m http.server 8000', waitForPort(8000))

// VNC desktop — wait for the VNC port
template.setStartCmd('/start_command.sh', waitForPort(6080))

from e2b import Template, wait_for_url, wait_for_port

# Next.js app — wait for the dev server URL
template.set_start_cmd("npx next --turbo", wait_for_url("http://localhost:3000"))

# Python HTTP server — wait for port 8000
template.set_start_cmd("python -m http.server 8000", wait_for_port(8000))

# VNC desktop — wait for the VNC port
template.set_start_cmd("/start_command.sh", wait_for_port(6080))

setReadyCmd / set_ready_cmd

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.

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.

JavaScript & TypeScript

import { Template, waitForTimeout, waitForPort, waitForFile } from 'e2b'

// Wait 10 seconds before taking the snapshot
const template = Template()
  .fromUbuntuImage("22.04")
  .runCmd("apt-get install -y nginx && service nginx start")
  .setReadyCmd(waitForPort(80))

from e2b import Template, wait_for_timeout, wait_for_port, wait_for_file

# Wait for nginx to start listening before taking the snapshot
template = (
    Template()
    .from_ubuntu_image("22.04")
    .run_cmd("apt-get install -y nginx && service nginx start")
    .set_ready_cmd(wait_for_port(80))
)

More examples:

JavaScript & TypeScript

// Wait for a file to be created by a background process
template.setReadyCmd(waitForFile('/tmp/ready'))

// Wait a fixed duration for the system to stabilize
template.setReadyCmd(waitForTimeout(10_000))

// Custom readiness check
template.setReadyCmd('curl -s http://localhost:8080/health')

# Wait for a file to be created by a background process
template.set_ready_cmd(wait_for_file("/tmp/ready"))

# Wait a fixed duration for the system to stabilize
template.set_ready_cmd(wait_for_timeout(10_000))

# Custom readiness check
template.set_ready_cmd("curl -s http://localhost:8080/health")

Ready command helpers

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.

JavaScript & TypeScript

import {
  waitForPort,
  waitForURL,
  waitForProcess,
  waitForFile,
  waitForTimeout,
} from 'e2b'

// Wait for a port to be available
waitForPort(3000)

// Wait for a URL to return a specific status code (defaults to 200)
waitForURL('http://localhost:3000/health')
waitForURL('http://localhost:3000/health', 200)

// Wait for a process to be running
waitForProcess('node')

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

// Wait for a specified duration
waitForTimeout(10_000) // 10 seconds

from e2b import wait_for_port, wait_for_url, wait_for_process, wait_for_file, wait_for_timeout

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

# Wait for a URL to return a specific status code (defaults to 200)
wait_for_url("http://localhost:3000/health")
wait_for_url("http://localhost:3000/health", 200)

# Wait for a process to be running
wait_for_process("node")

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

# Wait for a specified duration
wait_for_timeout(10_000)  # 10 seconds