sbx: document the long-running kit capability

Explain how a kit declares long-running@1 to keep its sandbox running
after sessions end, how required and optional entries behave, and that
cloud sandboxes and sbx kit add can't provide it.

Source: docker/sandboxes#6710

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

content/manuals/ai/sandboxes/customize/author/_index.md

@@ -186,3 +186,34 @@ can override these defaults with `--cpus` and `--memory` when creating a sandbox
 Put these settings on the workload. `sbx` ignores resource settings on
 mixins added separately, and it doesn't use the capability's `gpu` field
 to select GPUs.
+
+## Keep the sandbox running after sessions end
+
+By default, a local sandbox stops automatically shortly after its last session
+disconnects. A kit that runs a service, such as a development server on a
+published port, can ask the sandbox to keep running instead. Declare the
+[`long-running@1` capability](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/long-running@1.md),
+which takes no `config`:
+
+```yaml
+capabilities:
+  - type: com.docker.sandbox/long-running@1
+```
+
+A sandbox created with this kit behaves like one started with
+[`sbx run --detached`](/manuals/ai/sandboxes/usage.md#keep-a-sandbox-running-in-the-background):
+it keeps running until someone stops or removes it, including after you attach
+to it and disconnect. When a workload, mixin, or set declares the capability,
+it applies to the whole sandbox.
+
+A kit that declares the capability runs only where the runtime can provide it.
+If the kit also works when the sandbox stops after its sessions end, set
+`optional: true` on the entry. A runtime that can't provide the capability
+then skips it instead of refusing the kit. In `sbx`, two cases can't provide
+it:
+
+- Cloud sandboxes can't provide this capability. `sbx --cloud` refuses a kit
+  that requires it and skips an optional entry.
+- `sbx kit add` can't apply the capability to a running sandbox. A required
+  entry fails, and an optional entry is skipped with a warning. Recreate the
+  sandbox with the kit to apply it.