Open-source, secure environment with real-world tools for enterprise-grade agents.
Python agentaiai-agentai-agentscode-interpretercopilotdevelopmentdevtoolsgptgpt-4javascriptllmnextjsopenaipythonreactsoftwaretypescript
Add option for a template ready check (#750)
Jakub Dobrye244ba72c01d
diff --git a/.changeset/four-numbers-drive.md b/.changeset/four-numbers-drive.mdnew file mode 100644index 000000000..75e713ded--- /dev/null+++ b/.changeset/four-numbers-drive.md@@ -0,0 +1,5 @@+---+'@e2b/cli': minor+---++Add ready command for template builddiff --git a/apps/web/src/app/(docs)/docs/legacy/sandbox/custom/page.mdx b/apps/web/src/app/(docs)/docs/legacy/sandbox/custom/page.mdxindex e21b47066..e8b663ab5 100644--- a/apps/web/src/app/(docs)/docs/legacy/sandbox/custom/page.mdx+++ b/apps/web/src/app/(docs)/docs/legacy/sandbox/custom/page.mdx@@ -20,7 +20,7 @@ Once you build your custom sandbox template, you can spawn multiple isolated san// Create new sandboxconst sandbox = await Sandbox.create({- template: '<sandbox-template-id>', // You get sandbox template ID from the CLI after you run `$ e2b build`+ template: '<sandbox-template-id>', // You get sandbox template ID from the CLI after you run `$ e2b template build`})// Close sandbox once done@@ -32,7 +32,7 @@ Once you build your custom sandbox template, you can spawn multiple isolated san# Create new sandboxsandbox = Sandbox(- template="<sandbox-template>", # You get sandbox template from the CLI after you run `$ e2b build`+ template="<sandbox-template>", # You get sandbox template from the CLI after you run `$ e2b template build`)# Close sandbox once donediff --git a/apps/web/src/app/(docs)/docs/legacy/sandbox/templates/overview/page.mdx b/apps/web/src/app/(docs)/docs/legacy/sandbox/templates/overview/page.mdxindex 2b062e002..837f1f816 100644--- a/apps/web/src/app/(docs)/docs/legacy/sandbox/templates/overview/page.mdx+++ b/apps/web/src/app/(docs)/docs/legacy/sandbox/templates/overview/page.mdx@@ -32,7 +32,7 @@ Follow our [guide](/docs/guide/custom-sandbox) on how to create a custom sandbox// Create new sandboxconst sandbox = await Sandbox.create({- // You get sandbox template from the CLI after you run `$ e2b build`+ // You get sandbox template from the CLI after you run `$ e2b template build`template: '<sandbox-template>', // $HighlightLine})@@ -45,7 +45,7 @@ Follow our [guide](/docs/guide/custom-sandbox) on how to create a custom sandbox# Create new sandboxsandbox = Sandbox(- # You get sandbox template from the CLI after you run `$ e2b build`+ # You get sandbox template from the CLI after you run `$ e2b template build`template="<sandbox-template>", # $HighlightLine)diff --git a/apps/web/src/app/(docs)/docs/sandbox-template/page.mdx b/apps/web/src/app/(docs)/docs/sandbox-template/page.mdxindex 700a75e07..e8de75bea 100644--- a/apps/web/src/app/(docs)/docs/sandbox-template/page.mdx+++ b/apps/web/src/app/(docs)/docs/sandbox-template/page.mdx@@ -106,17 +106,21 @@ print(execution.stdout)```</CodeGroup>+## How it works+Every time you are building a sandbox template, we create a container based on the [`e2b.Dockerfile`](/docs/sandbox-template#3-customize-e2b-dockerfile) file you create in the process.+We extract the container's filesystem, do provisioning and configuration (e.g. installing required dependencies), and start a sandbox.+Then, these steps happen:+ 1. We take the running sandbox.+ 2. (Only if you specified the [start command](/docs/sandbox-template/start-cmd), otherwise this step is skipped) Execute the start command.+ 3. Wait for readiness (by default 20 seconds if start command is specified, otherwise immediately ready). Readiness check can be configured using [ready command](/docs/sandbox-template/ready-cmd).+ 4. Snapshot the sandbox and make it ready for you to spawn it with the SDK.+We call this sandbox snapshot a _sandbox template_.+<Note title="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.+</Note>\ No newline at end of filediff --git a/apps/web/src/app/(docs)/docs/sandbox-template/ready-cmd/page.mdx b/apps/web/src/app/(docs)/docs/sandbox-template/ready-cmd/page.mdxnew file mode 100644index 000000000..823786fb6--- /dev/null+++ b/apps/web/src/app/(docs)/docs/sandbox-template/ready-cmd/page.mdx@@ -0,0 +1,47 @@+# Ready Command+The ready command allows you to specify a command that will determine **template sandbox** readiness before a [snapshot](/docs/sandbox-template#how-it-works) is created.+It is executed in an infinite loop until it returns a successful **exit code 0**.+This way you can control how long should we wait for the [start command](/docs/sandbox-template/start-cmd) or any system state.+++## How to add ready command++When you are building a sandbox template you can specify the ready command by using the [`--ready-cmd`](/docs/sdk-reference/cli/v1.5.0/template#e2b-template-build) option:++```bash+e2b template build --ready-cmd "<your-ready-command>"+```++### Sandbox template config+You can specify the ready command inside the `e2b.toml` in the same directory where you run `e2b template build`.+<CodeGroup isFileName title="e2b.toml" isRunnable={false}>+ ```toml+ # This is a config for E2B sandbox template+ template_id = "1wdqsf9le9gk21ztb4mo"+ dockerfile = "e2b.Dockerfile"+ template_name = "my-agent-sandbox"+ ready_cmd = "<your-ready-command>" # $HighlightLine+ ```+</CodeGroup>++## Default values+By default, the ready command is set to `sleep 0`, which means the sandbox template will be ready immediatelly.+If the [start command](/docs/sandbox-template/start-cmd) is defined, the default is set to `sleep 20`, which means that the template sandbox will wait for 20 seconds before taking the snapshot.++## Examples+Here are some examples of the ready command you can use.++### Wait for URL to return 200 status code+```bash+ready_cmd = 'curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 | grep -q "200"'+```++### Wait for a specific process to start+```bash+ready_cmd = 'pgrep my-process-name > /dev/null'+```++### Wait for a file to exist+```bash+ready_cmd = '[ -f /tmp/ready.flag ]'+```\ No newline at end of filediff --git a/apps/web/src/app/(docs)/docs/sandbox-template/start-cmd/page.mdx b/apps/web/src/app/(docs)/docs/sandbox-template/start-cmd/page.mdxindex 8915a7fbf..ea87c6128 100644--- a/apps/web/src/app/(docs)/docs/sandbox-template/start-cmd/page.mdx+++ b/apps/web/src/app/(docs)/docs/sandbox-template/start-cmd/page.mdx@@ -4,39 +4,29 @@ This way, you can for example have running servers or seeded databases inside thThe 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.+You can see how it works [here](/docs/sandbox-template#how-it-works).## How to add start commandWhen you are building a sandbox template you can specify the start command by using the [`-c`](/docs/sdk-reference/cli/v1.0.9/template#e2b-template-build) option:```bash-e2b build -c "<your-start-command>"+e2b template 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](/docs/sandbox-template), we create a container based on the [`e2b.Dockerfile`](/docs/sandbox-template#3-customize-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.---<Note title="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.-</Note>---## Limits-- We wait 15 seconds after we execute the start command before we snapshot the sandbox.+### Sandbox template config+You can specify the start command also inside the `e2b.toml` in the same directory where you run `e2b template build`.+<CodeGroup isFileName title="e2b.toml" isRunnable={false}>+ ```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>" # $HighlightLine+ ```+</CodeGroup>## Logs@@ -87,15 +77,3 @@ Or you can use the CLI:e2b sandbox logs <sandbox-id>```</CodeGroup>--## 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>"`.-<CodeGroup isFileName title="e2b.toml" isRunnable={false}>-```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>" # $HighlightLine-```-</CodeGroup>diff --git a/apps/web/src/components/Navigation/routes.tsx b/apps/web/src/components/Navigation/routes.tsxindex 5785900fc..ab63229ee 100644--- a/apps/web/src/components/Navigation/routes.tsx+++ b/apps/web/src/components/Navigation/routes.tsx@@ -342,6 +342,10 @@ export const docRoutes: NavGroup[] = [title: 'Start command',href: '/docs/sandbox-template/start-cmd',},+ {+ title: 'Ready command',+ href: '/docs/sandbox-template/ready-cmd',+ },{title: 'Customize CPU & RAM',href: '/docs/sandbox-template/customize-cpu-ram',diff --git a/packages/cli/README.md b/packages/cli/README.mdindex fad54d808..ff8c949ce 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -30,7 +30,7 @@ e2b auth login> To authenticate without the ability to open the browser, provide> `E2B_ACCESS_TOKEN` as an environment variable. Get your `E2B_ACCESS_TOKEN`> from the Personal tab at [e2b.dev/dashboard](https://e2b.dev/dashboard). Then use the CLI like this:-> `E2B_ACCESS_TOKEN=sk_e2b_... e2b build`.+> `E2B_ACCESS_TOKEN=sk_e2b_... e2b template build`.> [!IMPORTANT]> Note the distinction between `E2B_ACCESS_TOKEN` and `E2B_API_KEY`.diff --git a/packages/cli/package.json b/packages/cli/package.jsonindex e238c4d7d..9677eabf7 100644--- a/packages/cli/package.json+++ b/packages/cli/package.json@@ -49,6 +49,7 @@"@types/inquirer": "^9.0.7","@types/json2md": "^1.5.4","@types/node": "^18.18.6",+ "@types/statuses": "^2.0.5","@types/update-notifier": "6.0.5","json2md": "^2.0.1","knip": "^5.43.6",@@ -77,6 +78,7 @@"e2b": "^1.5.2","inquirer": "^9.2.12","open": "^9.1.0",+ "statuses": "^2.0.1","strip-ansi": "^7.1.0","update-notifier": "^6.0.2","yup": "^1.3.2"diff --git a/packages/cli/src/commands/template/build.ts b/packages/cli/src/commands/template/build.tsindex b4eaa7ecb..8d20ff58f 100644--- a/packages/cli/src/commands/template/build.ts+++ b/packages/cli/src/commands/template/build.ts@@ -131,7 +131,7 @@ export const buildCommand = new commander.Command('build')'[template]',`specify ${asBold('[template]'- )} to rebuild it. If you don's specify ${asBold(+ )} to rebuild it. If you dont's specify ${asBold('[template]')} and there is no ${asLocal('e2b.toml'@@ -152,6 +152,10 @@ export const buildCommand = new commander.Command('build')'-c, --cmd <start-command>','specify command that will be executed when the sandbox is started.')+ .option(+ '--ready-cmd <ready-command>',+ 'specify command that will need to exit 0 for the template to be ready.'+ ).addOption(teamOption).addOption(configOption).option(@@ -178,6 +182,7 @@ export const buildCommand = new commander.Command('build')dockerfile?: stringname?: stringcmd?: string+ readyCmd?: stringteam?: stringconfig?: stringcpuCount?: number@@ -218,6 +223,7 @@ export const buildCommand = new commander.Command('build')let dockerfile = opts.dockerfilelet startCmd = opts.cmd+ let readyCmd= opts.readyCmdlet cpuCount = opts.cpuCountlet memoryMB = opts.memoryMblet teamID = opts.team@@ -246,6 +252,7 @@ export const buildCommand = new commander.Command('build')templateID = config.template_iddockerfile = opts.dockerfile || config.dockerfilestartCmd = opts.cmd || config.start_cmd+ readyCmd = opts.readyCmd ||config.ready_cmdcpuCount = opts.cpuCount || config.cpu_countmemoryMB = opts.memoryMb || config.memory_mbteamID = opts.team || config.team_id@@ -291,6 +298,7 @@ export const buildCommand = new commander.Command('build')const body = {alias: name,startCmd: startCmd,+ readyCmd: readyCmd,cpuCount: cpuCount,memoryMB: memoryMB,dockerfile: dockerfileContent,@@ -324,6 +332,7 @@ export const buildCommand = new commander.Command('build')dockerfile: dockerfileRelativePath,template_name: name,start_cmd: startCmd,+ ready_cmd: readyCmd,cpu_count: cpuCount,memory_mb: memoryMB,team_id: teamID,diff --git a/packages/cli/src/config/index.ts b/packages/cli/src/config/index.tsindex dc7cbe02a..7ccda48f0 100644--- a/packages/cli/src/config/index.ts+++ b/packages/cli/src/config/index.ts@@ -30,6 +30,7 @@ export const configSchema = yup.object({template_name: yup.string().optional(),dockerfile: yup.string().required(),start_cmd: yup.string().optional(),+ ready_cmd: yup.string().optional(),cpu_count: yup.number().integer().min(1).optional(),memory_mb: yup.number().integer().min(128).optional(),team_id: yup.string().optional(),diff --git a/packages/cli/src/utils/errors.ts b/packages/cli/src/utils/errors.tsindex 9c1708a9e..f8ece7b3e 100644--- a/packages/cli/src/utils/errors.ts+++ b/packages/cli/src/utils/errors.ts@@ -1,3 +1,5 @@+import status from 'statuses'+/*** Thrown when a request to E2B API occurs.*/@@ -16,7 +18,7 @@ export function handleE2BRequestError<T>(return}- let message = 'unknown error'+ let message: stringconst code = res.error?.code ?? 0switch (code) {case 400:@@ -34,6 +36,9 @@ export function handleE2BRequestError<T>(case 500:message = 'internal server error'break+ default:+ message = status(code) || 'unknown error'+ break}throw new E2BRequestError(diff --git a/packages/js-sdk/package.json b/packages/js-sdk/package.jsonindex e5cb60afc..22333dfc7 100644--- a/packages/js-sdk/package.json+++ b/packages/js-sdk/package.json@@ -28,7 +28,7 @@"dev": "tsup --watch","example": "tsx example.mts","test": "vitest run",- "generate": "python ./../../spec/remove_extra_tags.py sandboxes templates && openapi-typescript ../../spec/openapi_generated.yml -x api_key --array-length --alphabetize --output src/api/schema.gen.ts",+ "generate": "python ./../../spec/remove_extra_tags.py sandboxes templates auth && openapi-typescript ../../spec/openapi_generated.yml -x api_key --array-length --alphabetize --output src/api/schema.gen.ts","generate-envd-api": "openapi-typescript ../../spec/envd/envd.yaml -x api_key --array-length --alphabetize --output src/envd/schema.gen.ts","generate-ref": "./scripts/generate_sdk_ref.sh","check-deps": "knip",diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 9874d774d..8d79e9148 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -271,6 +271,9 @@ importers:open:specifier: ^9.1.0version: 9.1.0+ statuses:+ specifier: ^2.0.1+ version: 2.0.1strip-ansi:specifier: ^7.1.0version: 7.1.0@@ -293,6 +296,9 @@ importers:'@types/node':specifier: ^18.18.6version: 18.18.6+ '@types/statuses':+ specifier: ^2.0.5+ version: 2.0.5'@types/update-notifier':specifier: 6.0.5version: 6.0.5@@ -9808,8 +9814,7 @@ snapshots:'@types/[email protected]': {}- '@types/[email protected]':- optional: true+ '@types/[email protected]': {}'@types/[email protected]':dependencies:@@ -11261,7 +11266,7 @@ snapshots:debug: 4.4.0([email protected])enhanced-resolve: 5.18.1eslint: 8.57.1- eslint-module-utils: 2.8.0(@typescript-eslint/[email protected]([email protected])([email protected]))([email protected])([email protected](@typescript-eslint/[email protected]([email protected])([email protected]))([email protected])([email protected])([email protected]))([email protected])+ eslint-module-utils: 2.8.0(@typescript-eslint/[email protected]([email protected])([email protected]))([email protected])([email protected])([email protected])eslint-plugin-import: 2.28.1(@typescript-eslint/[email protected]([email protected])([email protected]))([email protected])([email protected])fast-glob: 3.3.2get-tsconfig: 4.7.0@@ -11273,7 +11278,7 @@ snapshots:- eslint-import-resolver-webpack- supports-color- [email protected](@typescript-eslint/[email protected]([email protected])([email protected]))([email protected])([email protected](@typescript-eslint/[email protected]([email protected])([email protected]))([email protected])([email protected])([email protected]))([email protected]):+ [email protected](@typescript-eslint/[email protected]([email protected])([email protected]))([email protected])([email protected])([email protected]):dependencies:debug: 3.2.7optionalDependencies:@@ -11294,7 +11299,7 @@ snapshots:doctrine: 2.1.0eslint: 8.57.1eslint-import-resolver-node: 0.3.9- eslint-module-utils: 2.8.0(@typescript-eslint/[email protected]([email protected])([email protected]))([email protected])([email protected](@typescript-eslint/[email protected]([email protected])([email protected]))([email protected])([email protected])([email protected]))([email protected])+ eslint-module-utils: 2.8.0(@typescript-eslint/[email protected]([email protected])([email protected]))([email protected])([email protected])([email protected])has: 1.0.3is-core-module: 2.13.0is-glob: 4.0.3@@ -14319,8 +14324,7 @@ snapshots:dependencies:type-fest: 0.7.1- optional: true+ [email protected]: {}