From ab66c2e18d8c41f365a1fe6d91a02ae0f657ade1 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 09:05:44 +0000 Subject: [PATCH 1/2] docs: explain sandbox guest page-size selection Sandbox configuration did not explain how to select a guest memory page size. Document the page-size flag, defaults, platform limits, and behavior across restarts and reconnections. --- .../ai/sandboxes/configuration/_index.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/content/manuals/ai/sandboxes/configuration/_index.md b/content/manuals/ai/sandboxes/configuration/_index.md index 10263715d76b..d5b025b3457f 100644 --- a/content/manuals/ai/sandboxes/configuration/_index.md +++ b/content/manuals/ai/sandboxes/configuration/_index.md @@ -25,3 +25,32 @@ sandbox, see [Customize](../customize/). in-sandbox Docker image pulls through an organization's registry mirror. - [Upstream proxy](upstream-proxy.md) routes sandbox and daemon traffic through an operating system or corporate proxy. + +## Guest page size + +For local sandboxes, use `--page-size` with `sbx create` or `sbx run` to choose +the guest kernel's memory page size. For example, select `4k` for workloads +that require 4 KB pages: + +```console +$ sbx create --page-size 4k claude . +``` + +Without the flag, the guest uses the host's page size when the matching kernel +is installed, and falls back to `4k` otherwise. + +Supported values depend on the host platform: + +| Host platform | Page sizes | +| :------------ | :--------- | +| Linux arm64 | `4k`, `16k`, `64k` | +| macOS on Apple silicon | `4k`, `16k` | +| Other platforms | `4k` | + +The CPU must support the selected page size, and the corresponding guest kernel +must be installed. The experimental `--4k` flag is equivalent to `--page-size 4k`; +combining `--4k` with another page size is rejected. + +Page size is set when you create a sandbox and persists across restarts. +When `sbx run` reconnects to an existing sandbox, `--page-size` has no effect. +To choose a different page size, create another sandbox. From 55418ed2b399df9831417ea752c7a73551964b4e Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 09:38:53 +0000 Subject: [PATCH 2/2] docs: troubleshoot sandbox build failures caused by page size Page-size guidance belongs with recovery steps for incompatible build tools. Move it from configuration to troubleshooting and show how to inspect the guest page size and create a sandbox with 4 KB pages. --- .../ai/sandboxes/configuration/_index.md | 29 ------------------- .../manuals/ai/sandboxes/troubleshooting.md | 25 ++++++++++++++++ 2 files changed, 25 insertions(+), 29 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/_index.md b/content/manuals/ai/sandboxes/configuration/_index.md index d5b025b3457f..10263715d76b 100644 --- a/content/manuals/ai/sandboxes/configuration/_index.md +++ b/content/manuals/ai/sandboxes/configuration/_index.md @@ -25,32 +25,3 @@ sandbox, see [Customize](../customize/). in-sandbox Docker image pulls through an organization's registry mirror. - [Upstream proxy](upstream-proxy.md) routes sandbox and daemon traffic through an operating system or corporate proxy. - -## Guest page size - -For local sandboxes, use `--page-size` with `sbx create` or `sbx run` to choose -the guest kernel's memory page size. For example, select `4k` for workloads -that require 4 KB pages: - -```console -$ sbx create --page-size 4k claude . -``` - -Without the flag, the guest uses the host's page size when the matching kernel -is installed, and falls back to `4k` otherwise. - -Supported values depend on the host platform: - -| Host platform | Page sizes | -| :------------ | :--------- | -| Linux arm64 | `4k`, `16k`, `64k` | -| macOS on Apple silicon | `4k`, `16k` | -| Other platforms | `4k` | - -The CPU must support the selected page size, and the corresponding guest kernel -must be installed. The experimental `--4k` flag is equivalent to `--page-size 4k`; -combining `--4k` with another page size is rejected. - -Page size is set when you create a sandbox and persists across restarts. -When `sbx run` reconnects to an existing sandbox, `--page-size` has no effect. -To choose a different page size, create another sandbox. diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index d354114de74d..4ec2e52be9a0 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -63,6 +63,31 @@ directory is on eCryptfs. If [`sbx diagnose`](#run-diagnostics) reports `state directory is on eCryptfs`, use a filesystem other than eCryptfs for sandbox state. +## Builds fail because of unsupported memory page sizes + +If a build tool fails because it requires 4 KB memory pages, create a local +sandbox with `--page-size 4k`. Some tools are incompatible with the larger +pages used by default on arm64 hosts. Without an explicit page size, the guest +matches the host's page size when the corresponding kernel is installed, +and falls back to `4k` otherwise. + +Check the page size in bytes inside the affected sandbox: + +```console +$ sbx exec getconf PAGESIZE +``` + +If the tool requires 4 KB pages and the sandbox reports a larger value, +create another sandbox with 4 KB pages and retry the build there: + +```console +$ sbx create --name --page-size 4k claude . +``` + +You can also pass `--page-size 4k` to `sbx run` when creating a sandbox. +The page size persists across restarts. Passing the flag when reconnecting to +an existing sandbox doesn't change its page size. + ## Sandbox is not responding If `sbx ls` shows `running (not responding)`, Docker Sandboxes has detected