From fce2734a08fd3d4ddf6f2ecfb654d272012ec621 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Thu, 22 Oct 2026 12:15:15 +0200 Subject: [PATCH] docs: clarify how kits and environment files work together (#26405) Environment files were introduced mainly as an alternative to publishing a kit set, leaving their broader role unclear. Explain near the top of both pages how kits package software and its requirements while environment files capture sandbox configuration, add reciprocal links, and shorten the kit-set comparison. Scoped rumdl and Vale checks pass for both changed pages. @netlify /ai/sandboxes/customize/ Generated by Codex --- .../configuration/environment-files.md | 7 +++++++ .../manuals/ai/sandboxes/customize/_index.md | 17 ++++++++++------- 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/environment-files.md b/content/manuals/ai/sandboxes/configuration/environment-files.md index fda1730a52..13f5e596a6 100644 --- a/content/manuals/ai/sandboxes/configuration/environment-files.md +++ b/content/manuals/ai/sandboxes/configuration/environment-files.md @@ -24,6 +24,13 @@ A sandbox environment file captures the setup for a local or cloud sandbox in a same agent, tools, resources, and credentials without reproducing CLI flags and setup steps. +Kits package software and declare what it needs to run. An environment file +selects those kits and configures the sandbox that uses them, including its +workspace, resources, credentials, and lifecycle commands. You can change or +share that configuration without repackaging the tools. See +[Kits](/manuals/ai/sandboxes/customize/_index.md) for how kits supply agents, +tools, and their runtime requirements. + > [!NOTE] > `sbx env` is experimental. The command interface and file format may change. diff --git a/content/manuals/ai/sandboxes/customize/_index.md b/content/manuals/ai/sandboxes/customize/_index.md index 20c6527dbe..22c51638ef 100644 --- a/content/manuals/ai/sandboxes/customize/_index.md +++ b/content/manuals/ai/sandboxes/customize/_index.md @@ -19,6 +19,13 @@ A kit can define the whole environment or add something to an existing one, such as a toolchain or your team's shared configuration. Package those choices once, then reuse them across projects and share them with your team. +To keep the configuration for a sandbox in an editable, shareable file, use a +[sandbox environment file](/manuals/ai/sandboxes/configuration/environment-files.md). +It selects kits alongside workspace paths, resources, credentials, and lifecycle +commands. Keep a tool's requirements in its kit so they follow the tool across +environments. Use the environment file for the choices involved in setting up +your sandbox. + Docker recommends v3 kits. This section covers v3. For the supported v2 format, see [Kits v2](/manuals/ai/sandboxes/customize/kits-v2.md). @@ -81,13 +88,9 @@ combined environment. If the set includes a workload, you run the published kit with `sbx run`. If it contains only mixins, you add it to a workload with `--kit`. -To share a combination without publishing another kit, list the workload and -mixins in a [sandbox environment file](/manuals/ai/sandboxes/configuration/environment-files.md). -Docker Sandboxes composes those kits when it creates the sandbox. An environment -file can also configure the workspace and host resources. Choose a set when you -want one published reference with a fixed list of components; the set records -their image digests when you build it. You can also use a set in an environment -file. +An environment file can select individual kits or a published set. Choose a set +when you want one published reference with a fixed list of components. The set +records their image digests when you build it. See [Use kits](/manuals/ai/sandboxes/customize/use-kits.md) for how to run kits and add mixins. To customize and publish your own combination, see