Start Command

The start command allows you to specify a command that will be already running when you spawn your custom sandbox. This way, you can for example have running servers or seeded databases inside the sandbox that are already fully ready when you spawn the sandbox using the SDK and with zero waiting time for your users during the runtime.

The idea behind the start command feature is to lower the wait times for your users and have everything ready for your users when you spawn your sandbox.

How to add start command

When you are building a sandbox template you can specify the start command by using the -c option:

e2b build -c "<your-start-command>"

When you spawn the custom sandbox you built, the start command will be already running if there was no error when we tried to execute it.

How it works

Every time you are building a custom sandbox, we create a container based on the e2b.Dockerfile file you create in the process. We extract the container's filesystem and start a sandbox with this extracted filesystem. We call this sandbox a template sandbox.

Then, these steps happen:

  1. We take the running template sandbox.
  2. (Only if you specified the start command, otherwise this step is skipped) Execute the start command and wait 15 seconds.
  3. Snapshot the sandbox and make it ready for you to spawn it with the SDK.
Sandbox Snapshot

Snapshots are saved running sandboxes. We serialize and save the whole sandbox's filesystem together with all the running processes in a way that can be loaded later.

This allows us to load the sandbox in a few hundred milliseconds any time later with all the processes already running and the filesystem exactly as it was.

Limits

  • The network isn't accessible when running the start command.
  • We wait 15 seconds after we execute the start command before we snapshot the sandbox.

Logs

You can retrieve the start command's logs using the SDK during runtime:

Check start command logs

import { Sandbox } from 'e2b'

// Spawn your custom sandbox
const sandbox = await Sandbox.create({
  id: 'my-agent-sandbox',
  // If you specify onStderr and onStdout handlers when spawning the sandbox
  // you will see logs from the start command.
  onStderr: output => console.log("stderr", output.line), 
  onStdout: output => console.log("stdout", output.line), 
})

// Close sandbox once done
await sandbox.close()

Sandbox template config

The start command is specified inside the e2b.toml in the same directory where you ran e2b build -c "<your-start-command>".

e2b.toml

# This is a config for E2B sandbox template
template_id = "1wdqsf9le9gk21ztb4mo"
dockerfile = "e2b.Dockerfile"
template_name = "my-agent-sandbox"
start_cmd = "<your-start-command>"