@capybara-hq/plugin-sandbox-docker 0.0.0-stage → 0.1.0-rc.1

package/.capybara-plugin/plugin.json

@@ -0,0 +1,144 @@
+{
+  "schemaVersion": 1,
+  "name": "sandbox-docker",
+  "version": "0.1.0-rc.1",
+  "publisher": "Capybara",
+  "description": "Conversation sandboxes (sandbox@1) as Docker containers (runc or gVisor runsc) behind a Docker socket proxy, with an egress allowlist proxy",
+  "displayName": {
+    "zh": "Docker 沙箱",
+    "en": "Docker sandbox"
+  },
+  "homepage": "https://github.com/capybara-hq/plugins/tree/main/plugins/sandbox-docker#readme",
+  "extension": {
+    "entry": "./dist/index.mjs",
+    "manifest": {
+      "name": "sandbox-docker",
+      "version": "0.1.0-rc.1",
+      "sdk": "^0.1.0-rc.0",
+      "provides": [
+        "sandbox@1"
+      ],
+      "requires": [],
+      "optional": [],
+      "permissions": {},
+      "config": {
+        "deployment": [
+          {
+            "path": "allowOpenEgress",
+            "secret": false,
+            "hot": false
+          },
+          {
+            "path": "egressProxyImage",
+            "secret": false,
+            "hot": false
+          },
+          {
+            "path": "endpoint",
+            "secret": false,
+            "hot": false
+          },
+          {
+            "path": "network",
+            "secret": false,
+            "hot": false
+          },
+          {
+            "path": "runtime",
+            "secret": false,
+            "hot": false
+          },
+          {
+            "path": "volumeDriver",
+            "secret": false,
+            "hot": false
+          }
+        ],
+        "org": []
+      }
+    },
+    "configSchemas": {
+      "deployment": {
+        "type": "object",
+        "properties": {
+          "endpoint": {
+            "type": "string",
+            "pattern": "^(tcp:\\/\\/(\\[[^\\]]+\\]|[^:/]+):\\d{1,5}\\/?|unix:\\/\\/\\/.+)$",
+            "x-ui": {
+              "label": {
+                "zh": "Docker 代理地址",
+                "en": "Docker proxy endpoint"
+              }
+            },
+            "title": "Docker proxy endpoint"
+          },
+          "runtime": {
+            "default": "runc",
+            "type": "string",
+            "enum": [
+              "runc",
+              "runsc"
+            ],
+            "x-ui": {
+              "label": {
+                "zh": "容器运行时",
+                "en": "Container runtime"
+              }
+            },
+            "title": "Container runtime"
+          },
+          "network": {
+            "default": "capybara-sandbox",
+            "type": "string",
+            "pattern": "^cap[a-zA-Z0-9_.-]*$",
+            "x-ui": {
+              "label": {
+                "zh": "沙箱网络",
+                "en": "Sandbox network"
+              }
+            },
+            "title": "Sandbox network"
+          },
+          "egressProxyImage": {
+            "default": "capybara-sandbox-egress:latest",
+            "type": "string",
+            "minLength": 1,
+            "x-ui": {
+              "label": {
+                "zh": "出站代理镜像",
+                "en": "Egress proxy image"
+              }
+            },
+            "title": "Egress proxy image"
+          },
+          "volumeDriver": {
+            "type": "string",
+            "minLength": 1,
+            "x-ui": {
+              "label": {
+                "zh": "卷驱动",
+                "en": "Volume driver"
+              }
+            },
+            "title": "Volume driver"
+          },
+          "allowOpenEgress": {
+            "default": false,
+            "type": "boolean",
+            "x-ui": {
+              "label": {
+                "zh": "允许开放出站",
+                "en": "Allow open egress"
+              }
+            },
+            "title": "Allow open egress"
+          }
+        },
+        "required": [
+          "endpoint"
+        ],
+        "additionalProperties": false
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+Capybara
+Copyright 2026 Meta-1 (Tianjin Yuanyilian Technology Co., Ltd.)

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# @capybara-hq/plugin-sandbox-docker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Docker implementation of the conversation sandbox (`sandbox@1`): one container per conversation (`cap-<conversation id>`), with a runtime of either runc or gVisor's runsc.
+The plugin **reaches Docker only through the endpoint** (the socket proxy in capybara-hq/core's [`docker/sandbox-proxy`](https://github.com/capybara-hq/core/tree/main/docker/sandbox-proxy)) and does not mount `docker.sock` itself.
+
+## Deployment config
+
+| Key | Default | Description |
+|---|---|---|
+| `endpoint` | (required) | Socket proxy address: `tcp://sandbox-proxy:2375` or `unix:///path` |
+| `runtime` | `runc` | `runc` or `runsc` (runsc must be registered in the Docker daemon first) |
+| `network` | `capybara-sandbox` | Name of the shared sandbox network; it must start with `cap` (the socket proxy only allows such networks); if it does not exist the plugin creates it as a bridge with `enable_icc=false` (containers cannot reach each other) |
+| `egressProxyImage` | `capybara-sandbox-egress:latest` | Egress proxy image (`egress-proxy/Dockerfile`) |
+| `volumeDriver` | (unset, uses local) | Driver for the workspace volume; when set, `DriverOpts.size=<diskMb>M` is passed |
+| `allowOpenEgress` | `false` | Allow `sandbox.limits.egress = "open"`; when false, `create` fails immediately on open (an English error naming `extensionConfig."sandbox-docker".allowOpenEgress`), and the kernel also logs a warn at startup |
+
+```bash
+export CAPYBARA_EXTENSION_CONFIG='{"sandbox-docker":{"endpoint":"tcp://127.0.0.1:2375"}}'
+```
+
+The deployment config schema is strict: extra keys are errors.
+
+## Images
+
+- The sandbox image `image/Dockerfile` (shared by the Docker plugin and the E2B template). The tag matches the default of the kernel config `sandbox.image`:
+  `docker build -t capybara-sandbox:latest plugins/sandbox-docker/image`.
+  Debian trixie-slim (pinned by digest), with bash, coreutils, GNU find / grep (the kernel's `Glob` / `Grep`
+  depend on them), procps, util-linux (`setsid`), curl, git, jq, python3 (with pip / venv) and so on; it runs as the non-root user `sandbox`
+  (uid 1000), with HOME and the working directory at `/workspace`.
+- The egress proxy image `egress-proxy/Dockerfile`: `docker build -t capybara-sandbox-egress:latest plugins/sandbox-docker/egress-proxy`.
+- Multi-arch (amd64 + arm64): `docker buildx build --platform linux/amd64,linux/arm64 -t <registry>/<name>:<tag> --push <directory>`.
+- Local development: in a [capybara-hq/core](https://github.com/capybara-hq/core) checkout, `docker compose -f docker/compose.dev.yaml --profile sandbox up -d` ([`docker/compose.dev.yaml`](https://github.com/capybara-hq/core/blob/main/docker/compose.dev.yaml)) builds both images and starts the socket proxy
+  (`127.0.0.1:2375`, **for local development only**, see the deployment requirements below). If an image is not local the plugin tries to pull it once.
+- **In a deployment, pre-pull `sandbox.image` and `egressProxyImage` on every Docker node** (`docker pull …`): if an image is not local
+  the plugin pulls it only when a conversation first uses the sandbox, and a pull of several hundred MB eats into the time limit of that tool call (`tools.timeoutMs` plus the lock wait and a 3-minute margin);
+  when it is slow that call fails, and the next one tries again.
+
+## Socket proxy (`docker/sandbox-proxy/haproxy.cfg`)
+
+The proxy and its config live in capybara-hq/core: [`docker/sandbox-proxy/haproxy.cfg`](https://github.com/capybara-hq/core/tree/main/docker/sandbox-proxy/haproxy.cfg).
+
+HAProxy (the official image, pinned by digest); the proxy runs as root (to read the socket). Two checks:
+
+1. **Paths and names**: only the endpoints the plugin actually calls are allowed (container create / inspect / start / stop / kill / restart / unpause / remove,
+   exec create / start / inspect, volume create / inspect / remove, network create / inspect / remove, image inspect / pull,
+   `_ping` / `version`), everything else gets 403. The query string of an image pull (`POST /images/create`) may only be a single `fromImage`: `fromSrc`
+   (importing an arbitrary filesystem from a URL or the request body), `repo` / `tag` (renaming to overwrite an image), `message` and `changes` always get 403. Containers and volumes accept only names starting with `cap-` (creating a container requires `?name=cap-…`), and networks accept only names starting with `cap`;
+   the plugin always accesses containers by name and never by id. Exec instances (`/exec/{id}/…`) cannot be filtered by name, but creating an exec already requires
+   a `cap-` container.
+2. **Request body (defense in depth)**: an endpoint with a body must be JSON, carry Content-Length, be ≤ 32 KiB and be fully buffered (a body larger than the buffer
+   is always rejected, so an oversized body cannot be used to bypass it). Rejected (case-insensitively): privileged, keys such as `Binds` / `CapAdd` / `Devices` /
+   `VolumesFrom` / `CgroupParent` / `Sysctls` / `Annotations` / `MaskedPaths` / `PortBindings`, mount types other than `volume` /
+   `tmpfs`, mounts whose `Source` does not start with `cap-` (the kernel's or another service's volumes cannot be mounted), host / container namespace modes, a `SecurityOpt` other than `no-new-privileges`, runtimes other than runc / runsc,
+   networks other than `none` / `cap…`, any `\u` escape and non-ASCII byte (Go's JSON decoding folds key names by Unicode,
+   so `"Bindſ"` would be treated as `Binds`; an exec command may contain Chinese, and only `\u` and non-ASCII in key names are rejected), duplicate keys that would bypass a "must be a given value" check;
+   a volume cannot carry the local driver's `device` / `o` / `type` (which could make it a bind), and a network can only be bridge. The create container / volume /
+   network request bodies the plugin generates itself are all ASCII, and a non-ASCII value (image names, tags and allowlist host names must use punycode) is reported as an English error in the plugin itself.
+   **This is only a regex backstop, not JSON parsing; the main line of defense is network position** (see the deployment requirements below).
+
+**Deployment requirement**: whoever can reach the proxy can almost control Docker (the second check is only a backstop). **Never publish it on any host address**, including
+`127.0.0.1`: on Docker Desktop a container on an ordinary bridge network can reach the host loopback through `host.docker.internal`; on Linux
+the bridge gateway address can also reach ports the host listens on. In production, put it only on the internal network the kernel is on, with no port mapping, and do not attach sandboxes to that network.
+To let the local kernel connect, the dev compose publishes it on `127.0.0.1:2375`: use that for local development only, and do not turn on `allowOpenEgress`.
+
+## Lifecycle
+
+| Operation | What it does |
+|---|---|
+| `create` | First deletes any old instance of the same name (the kernel may have exited before recording the handle), then creates the volumes, (for allowlist) the internal network and egress proxy, and the sandbox container, and starts it; the handle id is the name |
+| `suspend` | Stops the sandbox container and the egress proxy (files stay on the volumes). **Processes are not preserved**: all background processes in the sandbox end and `/tmp` (tmpfs) is cleared; E2B's pause, in contrast, keeps memory too |
+| `resume` | Starts (or unpauses one that was `docker pause`d); if the container does not exist it returns `gone`. If the allowlist's egress proxy or internal network is gone, it is rebuilt from the allowlist recorded in the container labels |
+| Auto-start | When `exec` / `readFile` / `writeFile` / `stat` / `killAll` find the container still exists but is not running (Docker returns 409: the host or daemon restarted, the idle sweep stopped the container before it could record `suspended`, someone ran `docker pause` on it…), they recover it the way `resume` does (egress proxy and network in place; unpause a paused one, start a stopped one) and retry once (the `sandbox@1` contract: the kernel trusts only the `running` it recorded itself) |
+| `killAll` | Kills every command started through `exec` that is still running (finds the wrapper by command line and sends SIGKILL by process group and session); called when the kernel takes over from a crashed previous lock holder. A process that a command puts in the background in a session of its own (`setsid`) is not guaranteed to be killed |
+| Concurrent use (`concurrentExec`, `killTagged`) | Declares `concurrentExec: true`: parallel sub-agents of one conversation run commands and file operations in its sandbox at the same time (independent `docker exec` instances; the socket proxy rules are unchanged). Each exec's control file carries the holder's tag (`/tmp/.capybara-exec-<tag>-<uuid>`, tags checked against `SANDBOX_TAG_RE`); `killTagged` kills only the commands of the given tags (a variant of the `killAll` script), used when the kernel takes over from a crashed holder while others keep running. Concurrent auto-starts of a stopped container are idempotent (`start` answers 304; a concurrent egress proxy create answers 409, tolerated). Concurrent commands share the container's `PidsLimit` (1024) and memory. When the kill exec itself cannot start, the container restarts, which also ends live siblings' commands (a last resort) |
+| `destroy` / `destroyByName` | Deletes the container, egress proxy, internal network and both volumes; a missing one also counts as success |
+| `exec` | `docker exec` (sandbox user, bash); on timeout or abort it SIGKILLs the command and all processes it spawned by session. Commands run through `timeout -s KILL <timeout + 5 seconds>`: when a kernel replica crashes (the timer on the plugin side is gone, and a dropped connection does not end the command) the time limit inside the sandbox is the backstop. When the exec used to kill processes cannot itself start (for example the process count has hit its limit), it falls back to restarting the whole container (`restart?t=0`): files are all on the volumes, `/tmp` is cleared, and the remaining processes in the sandbox all end. When output is truncated it backs up to a full UTF-8 character boundary |
+| `readFile` / `writeFile` / `stat` | Run small `head` / `stat` scripts in the container as the sandbox user (permissions and symlinks are resolved as the sandbox user, and the volume is not written as root through the daemon) |
+
+Resources for each conversation: the container `<name>`, the egress proxy `<name>-egress`, the internal network `<name>-net`, and the volumes `<name>-workspace`
+(`/workspace`) and `<name>-skills` (`/skills`). All carry the labels `dev.capybara.sandbox=1` and `dev.capybara.sandbox.name=<name>`.
+
+## Isolation and limits
+
+- Commands and file operations run as non-root (uid 1000); the container's main processes (`Init`'s tini and `sleep infinity`) run as root
+  (`User: 0:0`, with all capabilities dropped too): the sandbox user cannot signal them, and `kill 1`, `pkill sleep` and `kill -9 -1` cannot stop
+  the container. Every exec specifies the user explicitly; a manual `docker exec` without `-u` runs as root (with no capabilities).
+- `CapDrop: ALL`, `no-new-privileges`, a read-only root filesystem, `Init` (reaps zombie processes), `PidsLimit` 1024, private IPC.
+- cpu → `NanoCpus`; memory → `Memory` (`MemorySwap` the same value, so no swap is used).
+- `/tmp` is tmpfs (`nosuid,nodev`), sized at half the memory and no more than `diskMb`, and counts against the memory quota; it is cleared after suspension.
+- `/skills` is **mounted read-only**; the same volume is also mounted writable at `/opt/capybara/skills` (`/opt/capybara` is owned by root, 0700,
+  so the sandbox user cannot enter it, nor get in through a symlink), and the plugin's `writeFile("/skills/…")` writes through it as root inside the container.
+- **Disk**: the root filesystem is read-only, and all writes land on the workspace volume and `/tmp`. `--storage-opt size` limits only the container's writable layer,
+  which is meaningless for a read-only root filesystem, so it is not used. The workspace volume size takes effect only when `volumeDriver` is set and that driver supports the `size` option;
+  **the default local driver does not limit volume size** (`diskMb` has no effect). When you need a hard limit, use a volume driver that supports quotas, or configure an XFS project quota and the like
+  on the Docker volume directory on the host.
+
+**Command time limit**: a single command runs at most `sandbox.limits.maxCommandSeconds`, and no more than the time left in the run it belongs to (`runtime.maxRunSeconds`,
+default 900 seconds, Ruling M20). To run long commands, raise `runtime.maxRunSeconds` to at least `maxCommandSeconds`.
+
+**Limits take effect only at creation**: the `cpu` / `memoryMb` / `diskMb` / `egress` / `allowHosts` of `sandbox.limits` are written into the container,
+volumes and egress proxy (the allowlist is recorded in the container labels); changing the config affects only sandboxes created afterwards; existing sandboxes (including ones resumed after hibernation) keep the
+limits from creation until they are destroyed and rebuilt (destroyed for inactivity, or by deleting the `cap-<conversation>` family of resources).
+
+## Egress (`limits.egress`)
+
+- `none`: `NetworkMode: none`, loopback only.
+- `open`: attached to the shared network `network` (an ordinary bridge), and **can reach everything the host network can reach**: services listening on the host (on Docker
+  Desktop it reaches the host loopback through `host.docker.internal`, so a socket proxy published on 127.0.0.1 can also be reached by it), the intranet, and
+  the cloud metadata address. The deployment config `allowOpenEgress` must be turned on explicitly (off by default); use it only in trusted environments.
+- `allowlist` (default): the sandbox joins only an `Internal` internal network, on which there is only its egress proxy; the proxy's other leg joins the shared network.
+  `HTTP_PROXY` / `HTTPS_PROXY` (and the lowercase ones) are already set, and `NO_PROXY` is loopback. The proxy (`egress-proxy/proxy.mjs`, dependency-free Node):
+  - A host name matches `allowHosts` exactly, or `*.example.com` matches any subdomain (**not** `example.com` itself); IP literals are never allowed;
+  - It resolves first, and **every resolved IP** must not be a private, loopback, link-local (including 169.254.169.254), CGNAT (100.64/10), ULA
+    (fc00::/7), unspecified, multicast, reserved or documentation address (IPv4-mapped / NAT64 / 6to4 are judged by the embedded IPv4), otherwise 403; this blocks
+    DNS rebinding (such as `10.0.0.1.nip.io`); it then connects directly to the IP it checked, without resolving a second time;
+  - HTTPS goes through CONNECT (only ports 443 and 80 are allowed; the proxy container's environment variable `ALLOW_CONNECT_PORTS` can change this), and HTTP is forwarded by absolute URL;
+    when the first address cannot be reached it tries the other checked addresses in turn; a direct connection that bypasses the proxy does not work (the internal network has no exit).
+  - The internal network has no default route, and Docker's built-in DNS does not resolve external domains for it either (verified on Docker 29); protocols that do not go through the HTTP proxy
+    (ssh, git://) are unavailable.
+  - Known limitation: on Linux hosts with older Docker, a container in the internal network may be able to reach services the host listens on at that bridge address;
+    do not have host services listen on 0.0.0.0, or use a firewall to block inbound traffic from the sandbox subnet.
+
+**What the allowlist guards against and what it does not**: it blocks the intranet, the host and the cloud metadata address, and also hosts outside the allowlist; but it **cannot stop data being sent to a host
+on the allowlist**: `git push` to github.com, publishing to npm / PyPI, and uploading to GitHub APIs other than the raw / release addresses
+are all within the allowlist. The proxy sees only the host name and destination IP, not the request content. Attachments in a conversation and data the agent has read can all leak this way.
+For orgs that handle sensitive data: in the org settings set `sandboxToolPolicy` to `ask` (execute, write and deliver need approval), and / or set the sandbox network
+`sandboxEgress` to `none`; at the deployment level you can also narrow `sandbox.limits.allowHosts`.
+
+**Org-level egress** (org setting `sandboxEgress`, Ruling M19): an org can swap in its own allowlist (replacing the deployment's list) or cut the network; at
+`create` the kernel passes the org's effective `egress` / `allowHosts` to the plugin; an org cannot set `open`, and when the deployment is `none` the org can only be `none` too.
+
+## Test-only options
+
+The second parameter of `createDockerSandbox(config, testOptions)` can be passed only by code that calls it directly; the plugin config cannot set it:
+
+- `labels`: adds extra labels to all resources (tests clean up by label);
+- `egressTestHosts`: the egress proxy pins these host names to the given IPs and exempts them from the private-address check (they still must be on the allowlist),
+  so that a local HTTP service in a test can serve as an allowed target. It is passed in through the proxy container's environment variable `CAPYBARA_EGRESS_TEST_HOSTS`.
+
+## Tests
+
+`test/egress-proxy.test.ts` does not need Docker; `test/sandbox-docker.test.ts` needs Docker (the whole group is skipped without it),
+builds a uniquely tagged test image, starts the socket proxy, and cleans up by label at the end; the runsc cases run only when the daemon has runsc registered.
+Through a real kernel: `test/sandbox-tools.smoke.test.ts` (the kernel's sandbox tools in one process) and `test/sandbox-artifacts.dual.test.ts` (the M5 segment 2 flow across two replicas: attachments, delivery, takeover after a killed replica, idle suspend and resume). The socket proxy starts from `test/sandbox-proxy/haproxy.cfg`, an exact copy of capybara-hq/core's [`docker/sandbox-proxy/haproxy.cfg`](https://github.com/capybara-hq/core/tree/main/docker/sandbox-proxy/haproxy.cfg). Nothing in this repository compares them; core's `check:bootstrap --network` (rule `bootstrap-haproxy`) will check the copy against the commit core pins.