diff --git a/src/content/docs/sandbox/coding-agents/claude-code.mdx b/src/content/docs/sandbox/coding-agents/claude-code.mdx index e11a3b99275..a05841cb510 100644 --- a/src/content/docs/sandbox/coding-agents/claude-code.mdx +++ b/src/content/docs/sandbox/coding-agents/claude-code.mdx @@ -38,7 +38,8 @@ Run [Claude Code](https://code.claude.com/docs/en/overview) in a Linux sandbox t RUN npm install --global @anthropic-ai/claude-code@2.1.308 - COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim + COPY --from=docker.io/cloudflare/sandbox:1.0.1 \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim WORKDIR /workspace CMD ["sleep", "infinity"] diff --git a/src/content/docs/sandbox/coding-agents/codex.mdx b/src/content/docs/sandbox/coding-agents/codex.mdx index 7cd7b596b93..100d2ac7652 100644 --- a/src/content/docs/sandbox/coding-agents/codex.mdx +++ b/src/content/docs/sandbox/coding-agents/codex.mdx @@ -38,7 +38,8 @@ Run the [Codex CLI](https://developers.openai.com/codex/cli) in a Linux sandbox RUN npm install --global --ignore-scripts @openai/codex@0.156.1 - COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim + COPY --from=docker.io/cloudflare/sandbox:1.0.1 \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim WORKDIR /workspace CMD ["sleep", "infinity"] diff --git a/src/content/docs/sandbox/coding-agents/cursor.mdx b/src/content/docs/sandbox/coding-agents/cursor.mdx index 265d85e9c2c..ca0eee246b1 100644 --- a/src/content/docs/sandbox/coding-agents/cursor.mdx +++ b/src/content/docs/sandbox/coding-agents/cursor.mdx @@ -216,7 +216,7 @@ To stream controller and container logs, run: npx wrangler tail ``` -To list container instances, find the ID of the container application, then list its instances: +To list containers, find the ID of the container application, then list its containers: ```sh npx wrangler containers list diff --git a/src/content/docs/sandbox/coding-agents/opencode.mdx b/src/content/docs/sandbox/coding-agents/opencode.mdx index b3fc2394484..89f7a7bb27b 100644 --- a/src/content/docs/sandbox/coding-agents/opencode.mdx +++ b/src/content/docs/sandbox/coding-agents/opencode.mdx @@ -39,7 +39,8 @@ Run [OpenCode](https://opencode.ai) in a Linux sandbox to edit a GitHub reposito RUN npm install --global --ignore-scripts opencode-linux-x64-baseline@1.19.4 \ && ln -s /usr/local/lib/node_modules/opencode-linux-x64-baseline/bin/opencode /usr/local/bin/opencode - COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim + COPY --from=docker.io/cloudflare/sandbox:1.0.1 \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim WORKDIR /workspace CMD ["sleep", "infinity"] diff --git a/src/content/docs/sandbox/coding-agents/pi.mdx b/src/content/docs/sandbox/coding-agents/pi.mdx index 064775f9a9f..879426aa7a7 100644 --- a/src/content/docs/sandbox/coding-agents/pi.mdx +++ b/src/content/docs/sandbox/coding-agents/pi.mdx @@ -38,7 +38,8 @@ Run the [Pi](https://github.com/earendil-works/pi) coding agent in a Linux sandb RUN npm install --global --ignore-scripts @earendil-works/pi-coding-agent@0.87.1 - COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim + COPY --from=docker.io/cloudflare/sandbox:1.0.1 \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim WORKDIR /workspace CMD ["sleep", "infinity"] diff --git a/src/content/docs/sandbox/commands/follow-a-background-process.mdx b/src/content/docs/sandbox/commands/follow-a-background-process.mdx index 539104e0f62..f279a8eb0f6 100644 --- a/src/content/docs/sandbox/commands/follow-a-background-process.mdx +++ b/src/content/docs/sandbox/commands/follow-a-background-process.mdx @@ -170,7 +170,7 @@ A development server prints a line, such as `ready`, when it accepts requests. T ```ts // Prints the first matching line and exits with 0. Exits with 3 when the // process ends without printing one, 4 when there is no such process, and - // 5 when the process was lost, for example in an earlier instance. + // 5 when the process was lost, for example in an earlier container. const WAIT = `${CURRENT} dir=$1; pattern=$2 [ -d "$dir" ] || exit 4 diff --git a/src/content/docs/sandbox/commands/run-a-server-in-the-background.mdx b/src/content/docs/sandbox/commands/run-a-server-in-the-background.mdx index 69900a10004..1346f950433 100644 --- a/src/content/docs/sandbox/commands/run-a-server-in-the-background.mdx +++ b/src/content/docs/sandbox/commands/run-a-server-in-the-background.mdx @@ -16,7 +16,7 @@ import { PackageManagers, Steps, TypeScriptExample } from "~/components"; Start a server that runs until the container stops, such as a development server, a tunnel, or a code kernel. Unlike a job, nothing waits for the server to exit. Your Durable Object starts it on first use, waits until it answers, and starts it again in each new container. -For a process that runs until it finishes, such as a build or an agent task, refer to [Run background processes](/sandbox/commands/run-background-processes/). If the sandbox runs one server and keeps no files that you need, you can make the server the main process instead, as in [Preview a web application](/sandbox/previews/). The main process is the process that the container starts with, and the container stops when it exits. For more information, refer to [What stops an instance](/sandbox/concepts/lifetime/#what-stops-an-instance). +For a process that runs until it finishes, such as a build or an agent task, refer to [Run background processes](/sandbox/commands/run-background-processes/). If the sandbox runs one server and keeps no files that you need, you can make the server the main process instead, as in [Preview a web application](/sandbox/previews/). The main process is the process that the container starts with, and the container stops when it exits. For more information, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/#what-stops-an-instance). ## Prerequisites @@ -35,7 +35,7 @@ For a process that runs until it finishes, such as a build or an agent task, ref const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000; // Defines current(), which reads the process ID in a directory into $pid - // when the process started in this instance. + // when the process started in this container. const CURRENT = `current() { read -r pid boot 2>/dev/null <"$1/pid" && [ "$boot" = "$(cat /proc/sys/kernel/random/boot_id)" ] diff --git a/src/content/docs/sandbox/commands/run-background-processes.mdx b/src/content/docs/sandbox/commands/run-background-processes.mdx index cdf725a3b01..64cd49fd977 100644 --- a/src/content/docs/sandbox/commands/run-background-processes.mdx +++ b/src/content/docs/sandbox/commands/run-background-processes.mdx @@ -42,7 +42,7 @@ For a process that runs until the container stops, such as a development server echo "$?" >"$dir/exit-code.tmp" && mv "$dir/exit-code.tmp" "$dir/exit-code"`; // Defines current(), which reads the process ID in a directory into $pid - // when the process started in this instance. + // when the process started in this container. const CURRENT = `current() { read -r pid boot 2>/dev/null <"$1/pid" && [ "$boot" = "$(cat /proc/sys/kernel/random/boot_id)" ] diff --git a/src/content/docs/sandbox/concepts/security.mdx b/src/content/docs/sandbox/concepts/security.mdx index 31edccef517..ac8cb71ce75 100644 --- a/src/content/docs/sandbox/concepts/security.mdx +++ b/src/content/docs/sandbox/concepts/security.mdx @@ -22,7 +22,7 @@ Isolation does not limit what the code does inside its own sandbox. Assume that ## Everything in one sandbox is shared -Every process in a Container runs in the same Linux environment, the [container instance](/sandbox/concepts/lifetime/). The processes can read the same files, see each other, and connect to the servers that other processes run on `localhost`. Code loaded into one Dynamic Worker shares its memory in the same way. +Every process in a [Container](/sandbox/concepts/lifetime/) runs in the same Linux environment. The processes can read the same files, see each other, and connect to the servers that other processes run on `localhost`. Code loaded into one Dynamic Worker shares its memory in the same way. A separate Linux user does not keep a command away from files. `root` is the privileged Linux user. In a deployed sandbox, every process has the Linux capabilities of `root`, even when it runs under another user ID, so file permissions do not restrict it, and it can switch back to `root`. For more information, refer to the [`exec()` `user` option](/containers/api/durable-object-container/#exec). @@ -50,7 +50,7 @@ A Container keeps its files while it runs. A snapshot saves those files, includi The name decides which sandbox, and which saved files, a request reaches. It does not show who sent the request. Authenticate the caller in your Worker, and derive the sandbox name from that identity. Reusing a name or a snapshot for someone else gives them the earlier user's files. The how-to guides read the name from the URL only to keep the examples short. -For more information about what a sandbox keeps between instances, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/#snapshots-carry-files-to-the-next-instance). +For more information about what a sandbox keeps between containers, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/#snapshots-carry-files-to-the-next-instance). ## Every opening is also a way out diff --git a/src/content/docs/sandbox/files/back-up-a-directory-to-r2.mdx b/src/content/docs/sandbox/files/back-up-a-directory-to-r2.mdx index 53724707f63..d0a2e812719 100644 --- a/src/content/docs/sandbox/files/back-up-a-directory-to-r2.mdx +++ b/src/content/docs/sandbox/files/back-up-a-directory-to-r2.mdx @@ -1,6 +1,6 @@ --- title: Back up a directory to R2 -description: Save a directory from a Linux sandbox to your R2 bucket, and restore it into the same sandbox after its instance or image changes. +description: Save a directory from a Linux sandbox to your R2 bucket, and restore it into the same sandbox after its container or image changes. pcx_content_type: how-to sidebar: order: 4 @@ -21,7 +21,7 @@ import { WranglerConfig, } from "~/components"; -The `DirectoryBackup` class from `@cloudflare/sandbox` saves one directory as one object in your R2 bucket and restores it as ordinary files. R2 keeps each backup until you delete it. A container instance, the Linux virtual machine that your Durable Object starts, loses its files when it stops. You can restore a backup into a later instance, including one that runs a different image. For more information, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/#deploys-keep-instances-running). +The `DirectoryBackup` class from `@cloudflare/sandbox` saves one directory as one object in your R2 bucket and restores it as ordinary files. R2 keeps each backup until you delete it. A container loses its files when it stops. You can restore a backup into a later container, including one that runs a different image. For more information, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/#deploys-keep-instances-running). In this example, the directory is a project in `/workspace/project`. @@ -37,14 +37,15 @@ In this example, the directory is a project in `/workspace/project`. 1. Install the package: - + 2. Copy the helper binary into your image. If your project has no `Dockerfile`, create one in your project root: ```dockerfile title="Dockerfile" FROM node:24-trixie-slim - COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim + COPY --from=docker.io/cloudflare/sandbox:1.0.1 \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim RUN mkdir /workspace CMD ["sleep", "infinity"] diff --git a/src/content/docs/sandbox/files/index.mdx b/src/content/docs/sandbox/files/index.mdx index c8471ae7737..7c2b1810f08 100644 --- a/src/content/docs/sandbox/files/index.mdx +++ b/src/content/docs/sandbox/files/index.mdx @@ -1,6 +1,6 @@ --- title: Work with files in a sandbox -description: Move files in and out of a sandbox, keep a workspace after its instance stops, and share files through R2. +description: Move files in and out of a sandbox, keep a workspace after its container stops, and share files through R2. pcx_content_type: navigation sidebar: order: 6 @@ -15,7 +15,7 @@ products: The `Files` class from `@cloudflare/sandbox` moves files between your Worker and a running sandbox, and provides common file system operations. For more information, refer to [Move files in and out of a sandbox](/sandbox/files/manage-files/). -Each sandbox name reaches a [Durable Object](/durable-objects/), which starts a container instance when needed: a Linux virtual machine that runs your image. Stopping the instance deletes the files on its disk. For more information, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/#snapshots-carry-files-to-the-next-instance). +Each sandbox name reaches a [Durable Object](/durable-objects/), which starts a container when needed. Stopping the container deletes the files on its disk. For more information, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/#snapshots-carry-files-to-the-next-instance). ## Persistence diff --git a/src/content/docs/sandbox/files/manage-files.mdx b/src/content/docs/sandbox/files/manage-files.mdx index f51e6f47673..7338ade758f 100644 --- a/src/content/docs/sandbox/files/manage-files.mdx +++ b/src/content/docs/sandbox/files/manage-files.mdx @@ -23,7 +23,7 @@ import { This guide streams an uploaded file into a sandbox, compresses it with `gzip`, and streams the compressed file back to the caller. -The `Files` class from `@cloudflare/sandbox` reads and writes files in a running [container instance](/sandbox/concepts/lifetime/), the Linux virtual machine that your Durable Object starts. [`exec()`](/containers/api/durable-object-container/#exec) runs the command. `Files` does not start the instance, so your Durable Object starts it before each file operation. +The `Files` class from `@cloudflare/sandbox` reads and writes files in a running [container](/sandbox/concepts/lifetime/). [`exec()`](/containers/api/durable-object-container/#exec) runs the command. `Files` does not start the container, so your Durable Object starts it before each file operation. ## Prerequisites @@ -37,14 +37,15 @@ The `Files` class from `@cloudflare/sandbox` reads and writes files in a running 1. Install the package: - + 2. To give `Files` its helper binary, create a `Dockerfile` in the project root. If you already have one, add the `COPY` line to it: ```dockerfile title="Dockerfile" FROM node:24-trixie-slim - COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim + COPY --from=docker.io/cloudflare/sandbox:1.0.1 \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim RUN mkdir /workspace CMD ["sleep", "infinity"] @@ -77,7 +78,7 @@ The `Files` class from `@cloudflare/sandbox` reads and writes files in a running The `workspace` key names the image. Your code starts it as `container.images.workspace`. -4. To start an instance before each file operation, replace the import and the `MyContainer` class in `src/index.ts` with a class that has a `startSandbox()` method. Keep the default export until step 6 replaces it: +4. To start a container before each file operation, replace the import and the `MyContainer` class in `src/index.ts` with a class that has a `startSandbox()` method. Keep the default export until step 6 replaces it: @@ -111,7 +112,7 @@ The `Files` class from `@cloudflare/sandbox` reads and writes files in a running } } - // Files does not start an instance, so start one before each operation. + // Files does not start a container, so start one before each operation. private async startSandbox(): Promise { if (!this.container.running) { this.container.start({ @@ -126,7 +127,7 @@ The `Files` class from `@cloudflare/sandbox` reads and writes files in a running - The constructor creates one `Files` object for the Durable Object, because `this.ctx.container` stays the same object for as long as the Durable Object runs. `startSandbox()` starts the `workspace` image when no instance is running, and sets the inactivity timeout after `start()`. For more information, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/#the-timeout-does-not-survive-a-restart). + The constructor creates one `Files` object for the Durable Object, because `this.ctx.container` stays the same object for as long as the Durable Object runs. `startSandbox()` starts the `workspace` image when no container is running, and sets the inactivity timeout after `start()`. For more information, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/#the-timeout-does-not-survive-a-restart). 5. To write the upload, run the command, and return the output file, add a `compress()` method to `MyContainer`: @@ -213,7 +214,7 @@ The `Files` class from `@cloudflare/sandbox` reads and writes files in a running ## Remove output files -Compressed files stay in `/workspace` until the instance stops. To delete a file sooner, call `remove()` after the caller has read the response. +Compressed files stay in `/workspace` until the container stops. To delete a file sooner, call `remove()` after the caller has read the response. For other file operations, such as listing a directory or renaming a file, refer to [Files API](/sandbox/reference/files/). @@ -283,5 +284,5 @@ For more information, refer to [Sandbox security](/sandbox/concepts/security/#ev ## Related resources - [Files API](/sandbox/reference/files/): every method, including `readDirectory()`, `rename()`, and `remove()`. -- [Save and restore a sandbox with snapshots](/sandbox/files/save-and-restore-a-workspace/): keep the files after the instance stops. +- [Save and restore a sandbox with snapshots](/sandbox/files/save-and-restore-a-workspace/): keep the files after the container stops. - [Mount an R2 bucket](/sandbox/files/mount-an-r2-bucket/): write files that other systems read. diff --git a/src/content/docs/sandbox/files/mount-an-r2-bucket.mdx b/src/content/docs/sandbox/files/mount-an-r2-bucket.mdx index c51a924b17d..c717b2de765 100644 --- a/src/content/docs/sandbox/files/mount-an-r2-bucket.mdx +++ b/src/content/docs/sandbox/files/mount-an-r2-bucket.mdx @@ -36,7 +36,7 @@ The `S3Mount` class from `@cloudflare/sandbox` mounts one prefix of a bucket as 1. Install the package: - + 2. Create a `Dockerfile` in your project root. It installs FUSE and `s3fs`, and copies `sandbox-shim`, the helper binary that `S3Mount` runs in the container: @@ -47,7 +47,8 @@ The `S3Mount` class from `@cloudflare/sandbox` mounts one prefix of a bucket as && apt-get install -y --no-install-recommends ca-certificates fuse3 s3fs \ && rm -rf /var/lib/apt/lists/* - COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim + COPY --from=docker.io/cloudflare/sandbox:1.0.1 \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim CMD ["sleep", "infinity"] ``` @@ -177,7 +178,7 @@ The `S3Mount` class from `@cloudflare/sandbox` mounts one prefix of a bucket as Any process in the sandbox can read, change, or delete every object under the prefix. Mount the narrowest prefix the job needs, and use `access: "read-only"` when the job only reads. The sandbox receives placeholder credentials, because `s3fs` requires a key pair. The mount works with `enableInternet: false`. For short-lived credentials, refer to [Credentials](/sandbox/reference/s3-mounts/#credentials). - Calling `mount()` again with the same settings reuses the existing mount. Each new mount adds an outbound intercept, and `unmount()` does not remove it. An instance supports a [limited number of intercepts](/containers/api/durable-object-container/#interceptoutboundhttp). Give each job its own sandbox name instead of mounting a new prefix in the same instance. + Calling `mount()` again with the same settings reuses the existing mount. Each new mount adds an outbound intercept, and `unmount()` does not remove it. A container supports a [limited number of intercepts](/containers/api/durable-object-container/#interceptoutboundhttp). Give each job its own sandbox name instead of mounting a new prefix in the same container. 7. Add a method that runs a command in the mounted directory: @@ -321,5 +322,5 @@ Under `wrangler dev`, the container runs in Docker on your machine, and `S3Gatew - [S3Mount API](/sandbox/reference/s3-mounts/): every option and error. - [Artifact workspace example](https://github.com/cloudflare/sandbox-sdk/tree/main/examples/artifact-workspace): a deployable Worker that mounts a prefix for each sandbox and processes a file in it. -- [Save and restore a sandbox with snapshots](/sandbox/files/save-and-restore-a-workspace/): keep files on the sandbox disk between instances. Snapshots do not include mounted directories. +- [Save and restore a sandbox with snapshots](/sandbox/files/save-and-restore-a-workspace/): keep files on the sandbox disk between containers. Snapshots do not include mounted directories. - [S3 API compatibility](/r2/api/s3/api/): the S3 operations that R2 supports. diff --git a/src/content/docs/sandbox/files/save-a-sandbox-automatically.mdx b/src/content/docs/sandbox/files/save-a-sandbox-automatically.mdx index c0029777df8..2efc43e2e39 100644 --- a/src/content/docs/sandbox/files/save-a-sandbox-automatically.mdx +++ b/src/content/docs/sandbox/files/save-a-sandbox-automatically.mdx @@ -16,7 +16,7 @@ reviewed: 2026-09-24 import { PackageManagers, Steps } from "~/components"; -An [alarm](/durable-objects/api/alarms/), a call that the Durable Object schedules for itself, saves a Container snapshot of an idle sandbox and stops its instance. The instance is the Linux virtual machine that runs your image, and a snapshot is a saved copy of the files on its disk. While the sandbox is in use, the alarm also saves checkpoints. The next request starts a new instance from the last snapshot. For more information, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/). +An [alarm](/durable-objects/api/alarms/), a call that the Durable Object schedules for itself, saves a Container snapshot of an idle sandbox and stops its container. A snapshot is a saved copy of the files on the disk of a container. While the sandbox is in use, the alarm also saves checkpoints. The next request starts a new container from the last snapshot. For more information, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/). :::note[Public beta] Container snapshots are in public beta. Features and behavior may change. @@ -39,9 +39,9 @@ Container snapshots are in public beta. Features and behavior may change. const INACTIVITY_TIMEOUT_MS = 5 * 60 * 1000; ``` - The inactivity timeout is longer than the check interval, so the instance keeps running between checks. If the checks stop, the timeout still stops the instance, and the sandbox keeps the files from its last save. + The inactivity timeout is longer than the check interval, so the container keeps running between checks. If the checks stop, the timeout still stops the container, and the sandbox keeps the files from its last save. -2. In `MyContainer`, add a constructor. It sets the inactivity timeout again when a restarted Durable Object finds the container running, so the instance does not stop before the next check: +2. In `MyContainer`, add a constructor. It sets the inactivity timeout again when a restarted Durable Object finds the container running, so the container does not stop before the next check: ```ts title="src/index.ts" constructor(ctx: DurableObjectState, env: Env) { @@ -55,7 +55,7 @@ Container snapshots are in public beta. Features and behavior may change. } ``` - Then replace `exec()`. It starts a new instance from the stored snapshot when there is one, schedules the first check, and records activity: + Then replace `exec()`. It starts a new container from the stored snapshot when there is one, schedules the first check, and records activity: ```ts title="src/index.ts" busy = 0; @@ -129,7 +129,7 @@ Container snapshots are in public beta. Features and behavior may change. try { await this.save(); } catch (error) { - // Keep the instance and try again at the next check. + // Keep the container and try again at the next check. console.error("Saving the sandbox failed", error); await container.setInactivityTimeout(INACTIVITY_TIMEOUT_MS); await this.ctx.storage.setAlarm(Date.now() + CHECK_INTERVAL_MS); @@ -150,7 +150,7 @@ Container snapshots are in public beta. Features and behavior may change. } ``` - A save takes a few seconds, and the instance keeps running commands during it. If a request arrives during the save, the alarm does not stop the instance. A later snapshot saves the files written during the save. If a save fails, the handler keeps the instance running and schedules the next check, which tries again. If a deploy interrupts a save, the runtime [runs the alarm again](/durable-objects/api/alarms/). + A save takes a few seconds, and the container keeps running commands during it. If a request arrives during the save, the alarm does not stop the container. A later snapshot saves the files written during the save. If a save fails, the handler keeps the container running and schedules the next check, which tries again. If a deploy interrupts a save, the runtime [runs the alarm again](/durable-objects/api/alarms/). Checkpoints limit what a sandbox loses when something other than the alarm stops it, such as the inactivity timeout after the checks stop. The sandbox restores the last checkpoint, without the changes made after it. @@ -218,7 +218,7 @@ Container snapshots are in public beta. Features and behavior may change. } ``` - The sandbox saved a snapshot and stopped. The next request starts a new instance from the snapshot. Read the file: + The sandbox saved a snapshot and stopped. The next request starts a new container from the snapshot. Read the file: ```sh curl https://..workers.dev/sandboxes/ada --json '{"argv":["cat","/workspace/notes.txt"]}' @@ -236,6 +236,6 @@ Container snapshots are in public beta. Features and behavior may change. ## Related resources - [Save and restore a sandbox with snapshots](/sandbox/files/save-and-restore-a-workspace/): save when your application decides, copy a sandbox, and start a sandbox over. -- [Sandbox lifetime](/sandbox/concepts/lifetime/#snapshots-carry-files-to-the-next-instance): what a snapshot saves, and what a restored instance starts with. +- [Sandbox lifetime](/sandbox/concepts/lifetime/#snapshots-carry-files-to-the-next-instance): what a snapshot saves, and what a restored container starts with. - [Run code when a sandbox stops](/sandbox/manage/run-code-when-a-sandbox-stops/) - [`snapshotContainer()`](/containers/api/durable-object-container/#snapshotcontainer) diff --git a/src/content/docs/sandbox/files/save-and-restore-a-workspace.mdx b/src/content/docs/sandbox/files/save-and-restore-a-workspace.mdx index 69b12ce1cf1..71a3e182eef 100644 --- a/src/content/docs/sandbox/files/save-and-restore-a-workspace.mdx +++ b/src/content/docs/sandbox/files/save-and-restore-a-workspace.mdx @@ -1,6 +1,6 @@ --- title: Save and restore a sandbox with snapshots -description: Save the filesystem of a sandbox as a Container snapshot, stop its Linux instance, and restore the files in a new instance. +description: Save the filesystem of a sandbox as a Container snapshot, stop its container, and restore the files in a new container. pcx_content_type: how-to sidebar: order: 2 @@ -17,7 +17,7 @@ reviewed: 2026-09-24 import { PackageManagers, Steps, TypeScriptExample } from "~/components"; -A Durable Object saves the filesystem of a sandbox as a Container snapshot, stores the snapshot ID, and starts the next instance from the snapshot. An instance is the Linux virtual machine that runs your image, and a snapshot is a saved copy of the files on its disk. For more information, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/). In this example, the sandbox keeps a notes file in `/workspace`. +A Durable Object saves the filesystem of a sandbox as a Container snapshot, stores the snapshot ID, and starts the next container from the snapshot. A snapshot is a saved copy of the files on the disk of a container. For more information, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/). In this example, the sandbox keeps a notes file in `/workspace`. :::note[Public beta] Container snapshots are in public beta. Features and behavior may change. @@ -31,7 +31,7 @@ Container snapshots are in public beta. Features and behavior may change. -1. Add an inactivity timeout to your Durable Object. A Durable Object [restarts](/sandbox/concepts/lifetime/#the-timeout-does-not-survive-a-restart) when it leaves memory and runs its constructor again, and its instance can keep running. The constructor sets the timeout again when it finds the container running: +1. Add an inactivity timeout to your Durable Object. A Durable Object [restarts](/sandbox/concepts/lifetime/#the-timeout-does-not-survive-a-restart) when it leaves memory and runs its constructor again, and its container can keep running. The constructor sets the timeout again when it finds the container running: ```ts title="src/index.ts" const INACTIVITY_TIMEOUT_MS = 10 * 60 * 1000; @@ -84,7 +84,7 @@ Container snapshots are in public beta. Features and behavior may change. A snapshot is tied to the image it was saved from, and it cannot be applied to a different image. To carry files to a new image, [back up a directory to R2](/sandbox/files/back-up-a-directory-to-r2/) instead. For more information, refer to [Container snapshots](/containers/guides/snapshots/#create-a-container-snapshot). -2. Add a method that runs one operation at a time, and a method that saves the filesystem and stops the instance: +2. Add a method that runs one operation at a time, and a method that saves the filesystem and stops the container: ```ts title="src/index.ts" export class MyContainer extends DurableObject { @@ -113,9 +113,9 @@ Container snapshots are in public beta. Features and behavior may change. } ``` - A command that writes a file while the snapshot runs can succeed and then disappear when `destroy()` stops the instance. `exclusive()` makes every operation that touches the disk wait for the save, and the save wait for them. Run each such method through it. + A command that writes a file while the snapshot runs can succeed and then disappear when `destroy()` stops the container. `exclusive()` makes every operation that touches the disk wait for the save, and the save wait for them. Run each such method through it. - Finish writing files before you save. For what a snapshot saves and what a restored instance starts with, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/#snapshots-carry-files-to-the-next-instance). + Finish writing files before you save. For what a snapshot saves and what a restored container starts with, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/#snapshots-carry-files-to-the-next-instance). 3. Add a method that adds a line to a file and returns the file, so you can check what a restore brings back: @@ -190,7 +190,7 @@ Container snapshots are in public beta. Features and behavior may change. curl https://..workers.dev/sandboxes/ada/notes ``` - The save responds with the snapshot ID and its size in bytes, such as `{"snapshotId":"","size":123456}`. The last request starts a new instance from the snapshot, and the note is back: + The save responds with the snapshot ID and its size in bytes, such as `{"snapshotId":"","size":123456}`. The last request starts a new container from the snapshot, and the note is back: ```txt output Continue from this checkpoint. @@ -216,7 +216,7 @@ A snapshot ID restores in any Durable Object of the same class. To copy the file async useSnapshot(snapshotId: string) { return this.exclusive(async () => { - // Replacing a running instance would discard files it has not saved. + // Replacing a running container would discard files it has not saved. if (this.ctx.container?.running) { return false; } @@ -262,7 +262,7 @@ A snapshot ID restores in any Durable Object of the same class. To copy the file ## Start a sandbox over -To discard the files of a sandbox, destroy its instance and delete the stored snapshot ID. The next request starts from the image: +To discard the files of a sandbox, destroy its container and delete the stored snapshot ID. The next request starts from the image: ```ts title="src/index.ts" export class MyContainer extends DurableObject { diff --git a/src/content/docs/sandbox/get-started/build-a-coding-agent-runner.mdx b/src/content/docs/sandbox/get-started/build-a-coding-agent-runner.mdx index 1850fb4dcf4..6266fe76d67 100644 --- a/src/content/docs/sandbox/get-started/build-a-coding-agent-runner.mdx +++ b/src/content/docs/sandbox/get-started/build-a-coding-agent-runner.mdx @@ -93,7 +93,8 @@ You also need: # The install script from the Claude Code package puts its native binary in place RUN npm install --global @anthropic-ai/claude-code@2.1.308 - COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim + COPY --from=docker.io/cloudflare/sandbox:1.0.1 \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim WORKDIR /workspace # Keep the container running between requests @@ -282,7 +283,7 @@ setsid sh -c 'echo "$$ $(cat /proc/sys/kernel/random/boot_id)" >"$0/pid"; exec " "$dir" "$@" >"$dir/stdout.log" 2>"$dir/stderr.log" echo "$?" >"$dir/exit-code.tmp" && mv "$dir/exit-code.tmp" "$dir/exit-code"`; -// Succeeds while the process in the file runs and started in this instance. +// Succeeds while the process in the file runs and started in this container. const taskRunningScript = `read -r pid boot <"$1" && [ "$boot" = "$(cat /proc/sys/kernel/random/boot_id)" ] && kill -0 "$pid"`; @@ -666,7 +667,7 @@ Claude Code exits successfully even when a model request fails. The outcome come While no exit code exists, the Durable Object runs `kill -0` to check whether the process still exists. The command runs through `sh`, because `kill` is a shell built-in and the slim image has no separate `kill` binary. If the process is gone, the Durable Object reads the exit code again, because the task can finish between the two reads. Only a process that ended without an exit code is `lost`. -The process ID file also records the boot ID, which changes in every instance. A new instance can reuse the same process IDs, so the check ignores a process ID that another instance recorded. +The process ID file also records the boot ID, which changes in every container. A new container can reuse the same process IDs, so the check ignores a process ID that another container recorded. `readDiff()` marks new files with `git add --intent-to-add` so that the diff includes them. `git diff HEAD` compares the files with the checked-out commit, so the diff also includes changes that the agent staged. @@ -919,7 +920,7 @@ If you do not plan to add authentication, delete the Container application and t -2. Delete the application and its container instances: +2. Delete the application and its containers: - `start()` starts an instance of the container from the `cloudflare/debian-trixie` image. The `entrypoint` is the command that the instance runs when it starts. `sleep infinity` never exits, so the instance keeps running and accepts commands from `exec()`. + `start()` starts a container from the `cloudflare/debian-trixie` image. The `entrypoint` is the command that the container runs when it starts. `sleep infinity` never exits, so the container keeps running and accepts commands from `exec()`. 5. Generate types for the binding. Wrangler reads the `MyContainer` class from `src/index.ts` to type `env.MY_CONTAINER`: -6. Start Docker. `wrangler dev` runs the instance in Docker on your machine. To install Docker, follow the [Docker Desktop installation docs](https://docs.docker.com/desktop/). Check that Docker is running: +6. Start Docker. `wrangler dev` runs the container in Docker on your machine. To install Docker, follow the [Docker Desktop installation docs](https://docs.docker.com/desktop/). Check that Docker is running: ```sh docker info @@ -161,11 +161,11 @@ You will send `uname -a` in the body of an HTTP POST request to a [Worker](/work -The JSON body includes `"exitCode":0`. `stdout` contains `Linux`. The Worker started a Linux container and ran the command you sent. When you deploy, each instance runs in its own virtual machine instead of in Docker. +The JSON body includes `"exitCode":0`. `stdout` contains `Linux`. The Worker started a Linux container and ran the command you sent. When you deploy, each container runs in its own virtual machine instead of in Docker. ## Next steps - Run another command or change startup options. Refer to the [Durable Object container API](/containers/api/durable-object-container/). -- Deploy your Worker. Refer to [Deploy Containers](/containers/guides/deploy/). A deploy does not replace a running instance. Refer to [Sandbox lifetime](/sandbox/concepts/lifetime/#deploys-keep-instances-running). +- Deploy your Worker. Refer to [Deploy Containers](/containers/guides/deploy/). A deploy does not replace a running container. Refer to [Sandbox lifetime](/sandbox/concepts/lifetime/#deploys-keep-instances-running). - Run JavaScript. Refer to [Run JavaScript](/sandbox/get-started/dynamic-workers/). - Start a project from the [minimal sandbox template](https://github.com/cloudflare/sandbox-sdk/tree/main/examples/minimal). It adds a `Dockerfile`, a sandbox for each name in the URL, and file reads and writes with `@cloudflare/sandbox`. diff --git a/src/content/docs/sandbox/index.mdx b/src/content/docs/sandbox/index.mdx index 5eab2a3680a..5b22b29720e 100644 --- a/src/content/docs/sandbox/index.mdx +++ b/src/content/docs/sandbox/index.mdx @@ -1,6 +1,6 @@ --- title: Sandboxes on Cloudflare -description: Execute untrusted or generated code in Linux virtual machines or isolated Workers. +description: Execute untrusted or generated code in Linux containers or isolated Workers. pcx_content_type: overview sidebar: order: 1 @@ -46,13 +46,13 @@ If your application uses `@cloudflare/sandbox` 0.x, refer to [Sandbox SDK 0.x](/ [Containers](/containers/) run an image you provide. An image holds the files, packages, and default command of a Linux environment. -Each Linux sandbox is a [Durable Object](/durable-objects/), an object with a unique name and its own storage. The Durable Object starts a container instance: a Linux virtual machine that runs your image. The instance is a full Linux environment, so you can run any language and keep processes running. Your Worker reaches the Durable Object by name and sends it work. HTTP from the Internet reaches the instance only through your Worker. For how the Durable Object and the instance relate, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/). +Each Linux sandbox is a [Durable Object](/durable-objects/), an object with a unique name and its own storage. The Durable Object starts a [container](/containers/) from your image. The container is a full Linux environment, so you can run any language and keep processes running. Your Worker reaches the Durable Object by name and sends it work. HTTP from the Internet reaches the container only through your Worker. For how the Durable Object and the container relate, refer to [Sandbox lifetime](/sandbox/concepts/lifetime/). -No other workload shares an instance. For how each environment isolates code, refer to [Choose a sandbox environment](/sandbox/concepts/#how-each-environment-isolates-code). +No other workload shares a container. For how each environment isolates code, refer to [Choose a sandbox environment](/sandbox/concepts/#how-each-environment-isolates-code). A sandbox container uses the [Durable Object scheduling policy](/containers/configuration/scheduling-policy/#use-the-durable-object-scheduling-policy), which is in public beta. -Inside the Durable Object, `this.ctx.container` controls the instance. This excerpt starts the instance from an image and runs a command in it: +Inside the Durable Object, `this.ctx.container` controls the container. This excerpt starts the container from an image and runs a command in it: ```ts const container = this.ctx.container; @@ -151,7 +151,7 @@ const result = await entrypoint.evaluate(); - Move files, keep a workspace between instances, and mount an R2 bucket. + Move files, keep a workspace between containers, and mount an R2 bucket. diff --git a/src/content/docs/sandbox/previews/index.mdx b/src/content/docs/sandbox/previews/index.mdx index 7c27a03716e..6c2091c36ad 100644 --- a/src/content/docs/sandbox/previews/index.mdx +++ b/src/content/docs/sandbox/previews/index.mdx @@ -50,7 +50,7 @@ Use a browser to open a web server that runs in a sandbox. The server has no pub - The server must listen on `0.0.0.0`, because `getTcpPort()` cannot reach a server that listens only on `127.0.0.1`. Many development servers listen on `localhost` by default and provide an option to change the address. The next step passes the command as the `entrypoint` of `start()`, so the server runs as the main process. When it exits, for example after a crash, the [container instance stops](/sandbox/concepts/lifetime/#what-stops-an-instance), and the files on its disk end with it. If commands in the sandbox change files that you need, start the server as described in [Run a server in the background](/sandbox/commands/run-a-server-in-the-background/) instead. + The server must listen on `0.0.0.0`, because `getTcpPort()` cannot reach a server that listens only on `127.0.0.1`. Many development servers listen on `localhost` by default and provide an option to change the address. The next step passes the command as the `entrypoint` of `start()`, so the server runs as the main process. When it exits, for example after a crash, the [container stops](/sandbox/concepts/lifetime/#what-stops-an-instance), and the files on its disk end with it. If commands in the sandbox change files that you need, start the server as described in [Run a server in the background](/sandbox/commands/run-a-server-in-the-background/) instead. After you deploy, servers built on the Python `http.server` module, such as `python3 -m http.server`, exit on startup, because they look up the container hostname. For a Python command that serves files, refer to [Differences after you deploy](/containers/guides/local-dev/#the-hostname-is-longer-than-a-dns-label). @@ -215,7 +215,7 @@ Use a browser to open a web server that runs in a sandbox. The server has no pub ## Keep WebSocket connections open -The `fetch()` handler in the previous section passes WebSocket upgrade requests to the server, so WebSocket connections work. A connection that only passes through the Durable Object does not [keep the sandbox running](/sandbox/concepts/lifetime/#activity-keeps-an-instance-running), so the connection closes when the inactivity timeout stops the instance. +The `fetch()` handler in the previous section passes WebSocket upgrade requests to the server, so WebSocket connections work. A connection that only passes through the Durable Object does not [keep the sandbox running](/sandbox/concepts/lifetime/#activity-keeps-an-instance-running), so the connection closes when the inactivity timeout stops the container. To keep the sandbox running while a page has a connection open, accept both ends of the connection in the Durable Object: diff --git a/src/content/docs/sandbox/reference/index.mdx b/src/content/docs/sandbox/reference/index.mdx index c3fb4897f67..f0bcc7f0624 100644 --- a/src/content/docs/sandbox/reference/index.mdx +++ b/src/content/docs/sandbox/reference/index.mdx @@ -27,16 +27,19 @@ For `start()`, `exec()`, snapshots, and the other methods of the container itsel ## Install - + + +Install an exact version. The helper binary in your image comes from the `cloudflare/sandbox` image with the same version, as [Requirements](#requirements) describes. Your package manager can save a version range, such as `^1.0.1`, so set the version in `package.json` to `1.0.1`. To upgrade, change both versions together. ## Requirements Every class in the package has these requirements. A class page lists any others. -- The [container image](/containers/api/durable-object-container/#images), which supplies the filesystem of the container, contains the helper binary at `/usr/local/bin/sandbox-shim`. Copy it from the `cloudflare/sandbox` image whose tag matches the installed `@cloudflare/sandbox` version: +- The [container image](/containers/api/durable-object-container/#images), which supplies the filesystem of the container, contains the helper binary at `/usr/local/bin/sandbox-shim`. Copy it from the `cloudflare/sandbox` image whose tag matches the installed `@cloudflare/sandbox` version. A helper from another release can reject the commands of the package: ```dockerfile - COPY --from=docker.io/cloudflare/sandbox: /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim + COPY --from=docker.io/cloudflare/sandbox: \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim ``` The helper is a statically linked `linux/amd64` binary. It runs in any `linux/amd64` image. @@ -51,7 +54,8 @@ This configuration meets every requirement. The `Dockerfile` copies the helper i ```dockerfile title="Dockerfile" FROM node:24-trixie-slim -COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim +COPY --from=docker.io/cloudflare/sandbox:1.0.1 \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim RUN mkdir /workspace CMD ["sleep", "infinity"] diff --git a/src/content/docs/sandbox/sdk/migrate/backups.mdx b/src/content/docs/sandbox/sdk/migrate/backups.mdx index 5c95a2d06b6..aa1bbf8d497 100644 --- a/src/content/docs/sandbox/sdk/migrate/backups.mdx +++ b/src/content/docs/sandbox/sdk/migrate/backups.mdx @@ -29,12 +29,13 @@ This page replaces `createBackup()`, `restoreBackup()`, their options, and the b 1. Install the package, if your Worker does not use it yet: - + 2. Copy the helper binary into your image, if the `Dockerfile` does not copy it yet: ```dockerfile title="Dockerfile" - COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim + COPY --from=docker.io/cloudflare/sandbox:1.0.1 \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim ``` Use the `cloudflare/sandbox` tag that matches the installed package version. diff --git a/src/content/docs/sandbox/sdk/migrate/code-interpreter.mdx b/src/content/docs/sandbox/sdk/migrate/code-interpreter.mdx index dc2031149ea..8812c1e5887 100644 --- a/src/content/docs/sandbox/sdk/migrate/code-interpreter.mdx +++ b/src/content/docs/sandbox/sdk/migrate/code-interpreter.mdx @@ -17,7 +17,7 @@ In Sandbox SDK 0.12, `runCode()` ran Python, JavaScript, and TypeScript in an in ## Before you start -Your 1.0 class replaces the 0.12 `Sandbox` class, and has the `container` getter, the `ensureRunning()` and `startContainer()` methods, and the `ENV` constant from [Replace the Sandbox class](/sandbox/sdk/migrate/replace-the-sandbox-class/). To keep variables between calls, `src/index.ts` also needs the scripts and functions from step 1 of [Run a server in the background](/sandbox/commands/run-a-server-in-the-background/#run-a-server). +Your 1.0 class replaces the 0.12 `Sandbox` class, and has the `container` getter, the `ensureRunning()` and `startContainer()` methods, and the `ENV` constant from [Replace the Sandbox class](/sandbox/sdk/migrate/replace-the-sandbox-class/). To keep variables between calls, `src/index.ts` also needs the scripts and functions from step 1 of [Run a server in the background](/sandbox/commands/run-a-server-in-the-background/#run-a-server). Leave out its `INACTIVITY_TIMEOUT_MS` constant, which your class file already defines. A `runCode()` call without a `context` used a default context for its language, so plain calls in one sandbox shared variables: @@ -54,7 +54,8 @@ A kernel is a Python process that runs the code of each call with IPython, and k python3-numpy python3-pandas \ && rm -rf /var/lib/apt/lists/* - COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim + COPY --from=docker.io/cloudflare/sandbox:1.0.1 \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim WORKDIR /workspace COPY kernel.py /opt/kernel.py diff --git a/src/content/docs/sandbox/sdk/migrate/move-side-by-side.mdx b/src/content/docs/sandbox/sdk/migrate/move-side-by-side.mdx index e678f482fa0..f29d5f55da6 100644 --- a/src/content/docs/sandbox/sdk/migrate/move-side-by-side.mdx +++ b/src/content/docs/sandbox/sdk/migrate/move-side-by-side.mdx @@ -30,9 +30,9 @@ Keep the 0.12 exports, variables, and secrets that other migration pages tell yo 1. Install version 1 of the package, and keep 0.12 under the alias `sandbox-0x`: - + - Your package manager can save a version range. In `package.json`, set `sandbox-0x` to `npm:@cloudflare/sandbox@0.12.14`, so the 0.12 code stays on that version. In your 0.12 code, change each import from `@cloudflare/sandbox` to `sandbox-0x`. + Your package manager can save a version range. In `package.json`, set `@cloudflare/sandbox` to `1.0.1`, the version of the `cloudflare/sandbox` image in your `Dockerfile`, and `sandbox-0x` to `npm:@cloudflare/sandbox@0.12.14`, so the 0.12 code stays on that version. In your 0.12 code, change each import from `@cloudflare/sandbox` to `sandbox-0x`. 2. Give the 0.12 class a method that reports whether its container runs, and one that returns the storage that your 1.0 code reads. If your code exports the class from the package, replace that export with a subclass: @@ -66,7 +66,8 @@ Keep the 0.12 exports, variables, and secrets that other migration pages tell yo ```dockerfile title="Dockerfile.v1" FROM node:24-trixie-slim - COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim + COPY --from=docker.io/cloudflare/sandbox:1.0.1 \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim WORKDIR /workspace CMD ["sleep", "infinity"] diff --git a/src/content/docs/sandbox/sdk/migrate/other-features.mdx b/src/content/docs/sandbox/sdk/migrate/other-features.mdx index 13f17f07786..2722007bf15 100644 --- a/src/content/docs/sandbox/sdk/migrate/other-features.mdx +++ b/src/content/docs/sandbox/sdk/migrate/other-features.mdx @@ -40,7 +40,8 @@ The 0.x Docker setup starts from `docker:dind-rootless`, switches to `USER root` ```dockerfile title="Dockerfile" FROM docker:dind - COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim + COPY --from=docker.io/cloudflare/sandbox:1.0.1 \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim ENTRYPOINT ["sh", "-c", "dockerd-entrypoint.sh dockerd --iptables=false --ip6tables=false --ip-forward=false > /var/log/dockerd.log 2>&1 & exec sleep infinity"] ``` @@ -223,7 +224,7 @@ In 0.12, `createOpencode()` started `opencode serve` in the sandbox, and returne -3. Replace `createOpencode()` with a method that starts the server once for each container. It uses the scripts and functions from step 1 of [Run a server in the background](/sandbox/commands/run-a-server-in-the-background/#run-a-server): +3. Replace `createOpencode()` with a method that starts the server once for each container. It uses the scripts and functions from step 1 of [Run a server in the background](/sandbox/commands/run-a-server-in-the-background/#run-a-server), without its `INACTIVITY_TIMEOUT_MS` constant, which your class file already defines: ```ts title="src/index.ts (0.12)" const sandbox = getSandbox(env.Sandbox, "my-agent"); diff --git a/src/content/docs/sandbox/sdk/migrate/replace-the-sandbox-class.mdx b/src/content/docs/sandbox/sdk/migrate/replace-the-sandbox-class.mdx index 919dd2bab5a..499ac7b8875 100644 --- a/src/content/docs/sandbox/sdk/migrate/replace-the-sandbox-class.mdx +++ b/src/content/docs/sandbox/sdk/migrate/replace-the-sandbox-class.mdx @@ -28,7 +28,7 @@ The steps keep your class name, which moves every sandbox in place. To move sand 1. Install version 1 of the package: - + 2. Replace the `FROM docker.io/cloudflare/sandbox` line in your `Dockerfile` with a base image that has the tools your commands use, and copy the `sandbox-shim` helper into it: @@ -40,7 +40,8 @@ The steps keep your class name, which moves every sandbox in place. To move sand ca-certificates git python3 \ && rm -rf /var/lib/apt/lists/* - COPY --from=docker.io/cloudflare/sandbox:1.0.1 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim + COPY --from=docker.io/cloudflare/sandbox:1.0.1 \ + /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim WORKDIR /workspace CMD ["sleep", "infinity"] diff --git a/src/content/docs/sandbox/sdk/migrate/tunnels.mdx b/src/content/docs/sandbox/sdk/migrate/tunnels.mdx index 097d27b960c..ae38682d342 100644 --- a/src/content/docs/sandbox/sdk/migrate/tunnels.mdx +++ b/src/content/docs/sandbox/sdk/migrate/tunnels.mdx @@ -18,7 +18,7 @@ Your Worker already routes requests to the container, so most tunnels can become ## Before you start -Your 1.0 class replaces the 0.12 `Sandbox` class, and has the `container` getter and the `ensureRunning()` and `startContainer()` methods from [Replace the Sandbox class](/sandbox/sdk/migrate/replace-the-sandbox-class/). `src/index.ts` has the scripts and functions from step 1 of [Run a server in the background](/sandbox/commands/run-a-server-in-the-background/#run-a-server), which start `cloudflared` and stop it. +Your 1.0 class replaces the 0.12 `Sandbox` class, and has the `container` getter and the `ensureRunning()` and `startContainer()` methods from [Replace the Sandbox class](/sandbox/sdk/migrate/replace-the-sandbox-class/). `src/index.ts` has the scripts and functions from step 1 of [Run a server in the background](/sandbox/commands/run-a-server-in-the-background/#run-a-server), which start `cloudflared` and stop it. Leave out its `INACTIVITY_TIMEOUT_MS` constant, which your class file already defines. `startContainer()` must start the container with `enableInternet: true`, because `cloudflared` connects out to Cloudflare. Code in the sandbox can then reach the Internet too. For what that allows, refer to [Sandbox security](/sandbox/concepts/security/#every-opening-is-also-a-way-out).