@capybara-hq/plugin-device-e2b 0.0.0-stage → 0.1.0-rc.21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.capybara-plugin/plugin.json +152 -0
- package/LICENSE +202 -0
- package/NOTICE +2 -0
- package/README.md +407 -2
- package/dist/index.mjs +3612 -0
- package/guides/connect.md +7 -0
- package/guides/connect.zh.md +5 -0
- package/icon.svg +1 -0
- package/package.json +19 -4
package/README.md
CHANGED
|
@@ -1,3 +1,408 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @capybara-hq/plugin-device-e2b
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The E2B implementation of devices (`device-provider@1`): one E2B sandbox per device (E2B cloud or self-hosted E2B). E2B has no volume
|
|
4
|
+
separate from a micro-VM, so the device's file system **is** the E2B sandbox kept paused without memory, and an instance is the same sandbox
|
|
5
|
+
resumed through connect. It can run alongside `@capybara-hq/plugin-device-docker` and other device providers (`device-provider@1` is a multi
|
|
6
|
+
point: each device stays bound to the provider that made it), and uses the same image. Renamed from `@capybara-hq/plugin-sandbox-e2b` (no alias:
|
|
7
|
+
devices made by the old plugin read as unavailable and are recreated).
|
|
8
|
+
|
|
9
|
+
**Device page**: `report` describes the device as an E2B sandbox (microVM) whose files are kept by pausing it, names the metadata-service residual
|
|
10
|
+
(see "Network policy"), lists no limits (the template fixes cpu, memory and disk) and offers a files reset. New devices are made from the short
|
|
11
|
+
`device-connection` guide (`guides/connect.md`): name it and create it.
|
|
12
|
+
|
|
13
|
+
## Deployment config
|
|
14
|
+
|
|
15
|
+
| Key | Default | Description |
|
|
16
|
+
|---|---|---|
|
|
17
|
+
| `apiKey` | (required, secret) | E2B API key (`e2b_…`) |
|
|
18
|
+
| `template` | (empty) | Template name or id. Empty: the plugin builds the template `capybara-sandbox-<tag>` from the published image on first use (see "Template") |
|
|
19
|
+
| `apiUrl` | `https://api.<domain>` | Control plane API address; for self-hosted E2B, use your own address |
|
|
20
|
+
| `domain` | `e2b.app` | Sandbox domain: the envd address is `https://49983-<sandbox id>.<domain>`; when the API returns the sandbox's own `domain`, the returned one wins |
|
|
21
|
+
| `timeoutSeconds` | `3600` | Sandbox timeout (60–86400 seconds); when it expires E2B **auto-pauses** (does not delete), see "Lifecycle" |
|
|
22
|
+
| `domainAllowlist` | `true` | Whether E2B supports a per-domain network allowlist; set `false` for self-hosted versions that do not, and an allowlist degrades to no network with a warning |
|
|
23
|
+
| (removed) `openEgress` / `allowOpenEgress` | — | Both fail the strict schema with a pointer to the network policy: the org's cloud network (`limits.network`) decides (see "Network policy") |
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
export CAPYBARA_EXTENSIONS='["@capybara-hq/plugin-device-e2b"]'
|
|
27
|
+
export CAPYBARA_EXTENSION_CONFIG='{"device-e2b":{"apiKey":"e2b_…"}}'
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The deployment config schema is strict: extra keys are errors. The kernel config `sandbox.image` has no effect on this plugin: `device-provider@1` passes
|
|
31
|
+
the image only to `create`, but on E2B the image is fixed when the file system (the E2B sandbox) is created, from the template.
|
|
32
|
+
|
|
33
|
+
## Template (the same image as the Docker plugin)
|
|
34
|
+
|
|
35
|
+
**Built for you (default).** With `template` empty, the first `createFileSystem` of a provider instance looks up the alias
|
|
36
|
+
`capybara-sandbox-<tag>` (`GET /templates/aliases/{alias}`); when it does not exist, it builds that template from the image
|
|
37
|
+
`ghcr.io/capybara-hq/capybara-sandbox:<tag>` with the calls `Template.build(Template().fromImage(image), alias, { cpuCount: 1, memoryMB: 2048 })`
|
|
38
|
+
makes in `e2b@2.58.0` (`POST /v3/templates`, `POST /v2/templates/{templateID}/builds/{buildID}` with `{fromImage, steps: [], force: false}`,
|
|
39
|
+
then `GET /templates/{templateID}/builds/{buildID}/status?logsOffset=` every second until `ready`, at most 30 minutes and never past the
|
|
40
|
+
extension's lifetime (`ctx.signal`); `error` fails with E2B's reason and tells you to set `template`). E2B credentials alone are enough.
|
|
41
|
+
`<tag>` is **this plugin's own version**: the images are published by this repository's images workflow tagged with device-docker's version,
|
|
42
|
+
and device-docker and device-e2b are one changesets `fixed` group, so both always share one version (= the image tag). The alias replaces
|
|
43
|
+
each `.` with `-` (`0.1.0-rc.3` → `capybara-sandbox-0-1-0-rc-3`), so a new version builds a new template and an existing one is reused.
|
|
44
|
+
**Only a private template of your team is used:** the alias is a predictable name, so an alias lookup answering `public: true`, or 403 (an
|
|
45
|
+
alias of another team), and a build request answered 403 / 409 or creating a public template fail with "template alias … is owned by another
|
|
46
|
+
E2B team or is public; set the device-e2b setting `template` to a template of your own"; the plugin never runs sandboxes from a template it
|
|
47
|
+
did not build or you did not name. The result is memoised per provider instance (a failure is not); concurrent first uses share one build, and two replicas
|
|
48
|
+
starting at once may both build (wasteful but correct). An alias that exists does not mean its build is ready (another replica's build in flight,
|
|
49
|
+
or a failed build): when creating a sandbox from it answers E2B's 404, the plugin builds the alias itself, polls until ready and retries once.
|
|
50
|
+
CPU and memory are the kernel's defaults (1 core, 2048 MB); E2B templates are amd64.
|
|
51
|
+
**Unverified: the image's `ENV`.** The image sets the package cache variables (`npm_config_cache`, `PIP_CACHE_DIR`, `XDG_CACHE_HOME`, …,
|
|
52
|
+
all under `/workspace/.cache`) and `NODE_USE_ENV_PROXY=1` with `ENV`. Whether a template built with `fromImage` (or your own
|
|
53
|
+
`fromDockerfile` template) passes them to the processes envd starts is not yet confirmed on real E2B; the live test logs it
|
|
54
|
+
(`[e2b-live] image env: …`). Without them caches land in the tools' defaults under `HOME` (`/workspace`), so they still persist with the
|
|
55
|
+
files. `NODE_USE_ENV_PROXY` has no effect on E2B (no proxy variables are set there).
|
|
56
|
+
|
|
57
|
+
**Your own template.** Set `template` to a template name or id, for example one built from `plugins/device-docker/image/Dockerfile`
|
|
58
|
+
(E2B's Template SDK parses the Dockerfile's FROM / RUN / COPY / ADD / WORKDIR / USER / ENV / ARG / CMD / ENTRYPOINT). From the repository root:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
export E2B_API_KEY=e2b_… # for self-hosted, also set E2B_DOMAIN / E2B_API_URL
|
|
62
|
+
mkdir -p /tmp/e2b-build && cd /tmp/e2b-build && npm init -y >/dev/null && npm i e2b@2.58.0
|
|
63
|
+
cat > build.mjs <<'EOF'
|
|
64
|
+
import { readFileSync } from "node:fs";
|
|
65
|
+
import { defaultBuildLogger, Template } from "e2b";
|
|
66
|
+
const dockerfile = readFileSync(process.argv[2], "utf8");
|
|
67
|
+
await Template.build(Template().fromDockerfile(dockerfile), "capybara-sandbox", {
|
|
68
|
+
cpuCount: 1, // matches the kernel's sandbox.cpu default
|
|
69
|
+
memoryMB: 2048, // matches the kernel's sandbox.memoryMb default
|
|
70
|
+
onBuildLogs: defaultBuildLogger(),
|
|
71
|
+
});
|
|
72
|
+
EOF
|
|
73
|
+
node build.mjs <repo path>/plugins/device-docker/image/Dockerfile
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Then set `template` to `capybara-sandbox`. Image conventions (the plugin depends on them): the user `sandbox` (uid 1000), with HOME and the working directory at
|
|
77
|
+
`/workspace`; `/skills` owned by root (0755); `/opt/capybara` owned by root and 0700; `runuser` / `setsid` (util-linux),
|
|
78
|
+
`pkill` / `pgrep` (procps) and GNU coreutils installed. Rebuild the template after changing the Dockerfile.
|
|
79
|
+
|
|
80
|
+
## Lifecycle
|
|
81
|
+
|
|
82
|
+
| `device-provider@1` | E2B call |
|
|
83
|
+
|---|---|
|
|
84
|
+
| `createFileSystem` | Lists by the metadata `capybara-sandbox-name=<name>` (`GET /v2/sandboxes?metadata=…&state=running,paused`, paginated) and returns an existing sandbox of that name (the kernel may have stopped before recording the handle); otherwise ensures the template (above), `POST /v2/sandboxes` (`templateID`, `metadata`, `timeout`, `autoPause: true`, `autoPauseMemory: false`, `secure: true`, network settings), then pauses it without memory (`POST /sandboxes/{id}/pause` `{memory: false}`); the file system handle is E2B's sandbox id. An older kernel's limits are refused before any E2B call |
|
|
85
|
+
| `create` (instance) | `POST /v2/sandboxes/{id}/connect` `{timeout}` on the file system's sandbox (resumed; a 409 while another resume is in flight is retried); the instance handle carries the same id. E2B's 404 → `FileSystemGoneError` (the files are lost, never replaced by an empty sandbox); other failures, a bare 404 included, are ordinary errors. `image` and `limits` are ignored: they were fixed at `createFileSystem` |
|
|
86
|
+
| `update` (`limitsApplyAt: "fileSystem"`) | Applies the new network policy to the running sandbox without recreating it: connect first (resumes a paused one), then `PUT /sandboxes/{id}/network` (see "Network policy"); returns `"updated"`. E2B's 404 at either step → `SandboxGoneError`; an older kernel's limits are refused before any call |
|
|
87
|
+
| `resume` | `POST /v2/sandboxes/{id}/connect` (a paused one is resumed, and a running one gets its timeout pushed back); 404 → `gone` |
|
|
88
|
+
| `suspend`, `destroy` (instance) | `POST /sandboxes/{id}/pause` `{memory: false}` (the SDK's `mode: "filesystem"`): every process ends, the files stay, like the Docker plugin stopping or removing its container; a missing one (404) or an already paused one (409) also counts as success |
|
|
89
|
+
| `destroyByName` | Lists running sandboxes by the metadata name and pauses each without memory (files kept) |
|
|
90
|
+
| `destroyFileSystem` / `destroyFileSystemByName` | `DELETE /sandboxes/{id}` (a missing one also counts as success); by name it first lists by metadata (running and paused), which also removes a `sandbox@1` sandbox under a `cap-<conversationId>` name |
|
|
91
|
+
| Inactivity destruction | Nothing to do on E2B's side (the sandbox is already paused) |
|
|
92
|
+
| `killAll` | After connect (a paused one is resumed first; paused without memory, no process comes back), runs a script as the sandbox user that kills every command started through `exec` that is still running (SIGKILL by process group and session); called when the kernel takes over from a crashed previous lock holder |
|
|
93
|
+
| Concurrent use (`concurrentExec`, `killTagged`) | Declares `concurrentExec: true`: envd runs each `process.Start` independently, so the sessions of one device (and their sub-agents) run commands and file operations in its sandbox at the same time. Each exec's control file carries the holder's tag (`/tmp/.capybara-exec-<tag>-<uuid>`, tags checked against `SANDBOX_TAG_RE`); `killTagged` runs a script as the sandbox user that kills only the commands of the given tags. Concurrent `connect` calls are idempotent (a running sandbox only gets its timeout extended); a 409 answered while another call's resume is in flight is retried briefly (5 × 500 ms; to be confirmed on real E2B, see `test/live`). Uploads use UUID names in the staging directory. When a kill cannot run, the reboot fallback (pause + cold `connect`) also ends live siblings' commands (a last resort) |
|
|
94
|
+
| `exec` / file operations | First connect (a paused one is resumed, which is the contract's "auto-start"; the envd access token is fetched. **If no token can be obtained it does not connect and sends no request without a token; it reports `SandboxGoneError` (`resume` returns `gone`), and the kernel tries a new instance once, but `create` reconnects the same E2B sandbox and fails the same way, so the device stays unusable until its files are reset
|
|
95
|
+
or the device is recreated**; the timeout is pushed to at least "command timeout + 120 seconds", and not beyond 24 hours), then calls envd; a connect that returns an E2B-format 404 (`{code: 404, …}`) → `SandboxGoneError`; a bare 404 (a proxy, a misconfigured `apiUrl`), 401 / 5xx / network errors → ordinary errors. pause / delete also treat only an E2B-format 404 as "does not exist" |
|
|
96
|
+
|
|
97
|
+
- **Timeout**: an E2B sandbox is handled when its timeout (`timeoutSeconds`) expires; this plugin sets `autoPause: true` and `autoPauseMemory: false` when creating a sandbox,
|
|
98
|
+
so on expiry it is **paused** (without memory, like `suspend`) instead of deleted, and files are not lost even when the kernel has no chance to `suspend` (for example the whole kernel is down). Every use pushes it back through connect (it only extends, never shortens).
|
|
99
|
+
Idle hibernation and expiry destruction are handled by the kernel's maintenance tasks. E2B's continuous run limit (24 hours on Pro, 1 hour on Hobby) is recounted after pause / resume.
|
|
100
|
+
- **Hobby plan**: the `timeout` of connect / create is at most 1 hour, so the deployment config `timeoutSeconds` must be ≤ 3600, and a single command can actually run at most
|
|
101
|
+
about 1 hour minus 2 minutes; however large the `Bash` `timeout` (in milliseconds) is (capped by `sandbox.limits.maxCommandSeconds`, default 7200 seconds), it will be interrupted by the pause when the sandbox expires.
|
|
102
|
+
On Hobby, set `sandbox.limits.maxCommandSeconds` to below 3480.
|
|
103
|
+
- **Retention**: E2B's current documentation says paused sandboxes have no time to live and are never removed by E2B
|
|
104
|
+
([persistence](https://e2b.dev/docs/sandbox/persistence)); an older beta page said 30 days. Not yet confirmed against the live API (a
|
|
105
|
+
sandbox paused for more than 30 days, see `test/live`). The files live until the device is deleted (`destroyFileSystem`); a paused sandbox
|
|
106
|
+
that is gone nevertheless surfaces as `FileSystemGoneError` from `create` (`gone` from `resume`), and the kernel shows the device's files as
|
|
107
|
+
lost, never a silent empty workspace. Phase 1 has no export to object storage.
|
|
108
|
+
|
|
109
|
+
## exec and files
|
|
110
|
+
|
|
111
|
+
- **exec**: envd's `process.Process/Start` (a server stream of the Connect protocol), run as the `sandbox` user:
|
|
112
|
+
`setsid -w /bin/sh -c <wrapper> … timeout -s KILL <timeout + 5 seconds> /bin/bash -c <command>`; the wrapper first writes the session id to
|
|
113
|
+
`/tmp/.capybara-exec-<uuid>.pid`. The `timeout` inside the sandbox is the backstop: when a kernel replica crashes the timer on the plugin side is gone, disconnecting envd's stream does not end
|
|
114
|
+
the process, and pause then resume would bring the process back; on expiry it kills the process group the command is in.
|
|
115
|
+
On timeout or abort: a kill-processes script runs as the sandbox user, SIGKILLing all processes the command spawned by process group and session (the same as the Docker plugin),
|
|
116
|
+
then every process whose environment carries the command's marker `CAPYBARA_EXEC=<control file>` (set on every exec, so a child that left the
|
|
117
|
+
session with `setsid` or as a daemon is found too; only a process that clears its own environment escapes it), then envd's `SendSignal` by pid serves as a backstop (it only ends the session's first process); it returns only after the kill finishes, and disconnects after a 3-second grace period (disconnecting itself does not
|
|
118
|
+
end the processes in the sandbox).
|
|
119
|
+
The in-sandbox `timeout` path kills the marked processes as well. Real envd ends a command's output stream when the command itself exits, even while
|
|
120
|
+
an escaped child still holds the output (verified on E2B 2026-11-08), so the stream alone cannot show that a kill missed something: the marker scan does.
|
|
121
|
+
**Last resort: reboot the sandbox.** When the kill-processes script did not finish (could not start, for example process count exhausted, timeout, or unreachable),
|
|
122
|
+
marked processes are still there after it, or the output stream still has not ended 3 seconds after the kill: first pause, then `POST /v2/sandboxes/{id}/connect` `{timeout, memory: false}`
|
|
123
|
+
(that is, the SDK `e2b@2.58.0`'s `Sandbox.connect(id, { onResume: "reboot" })`) to cold-start from the disk state: all processes in memory end,
|
|
124
|
+
files such as `/workspace` are kept, writes not flushed before the pause may be lost, and whether things in `/tmp` survive depends on whether they are on disk. A warn log is written;
|
|
125
|
+
the call returns as usual with `timedOut: true` or the abort result. The SDK notes: this requires the control plane to support connect's `memory` field (E2B cloud; self-hosted must be a
|
|
126
|
+
`e2b-dev/runtime` after 2026-08-20), and an older control plane will **ignore the field** and restore the memory snapshot (processes still there), and an
|
|
127
|
+
environment without "restore only the filesystem" enabled will reject the request; in both cases the backstop is ineffective (only logged).
|
|
128
|
+
When a command is ended by a signal we did not send (envd's end event `exited: false`, such as OOM): by shell convention it returns `128 + signal number`
|
|
129
|
+
(when Go's signal name is recognized), and when it is not recognized it returns `exitCode: null, timedOut: false` (the kernel hints "the command did not finish, the result may be incomplete").
|
|
130
|
+
A timeout resolves `timedOut: true, exitCode: null`; an abort after start resolves `exitCode: null, timedOut: false` (with the output collected so far);
|
|
131
|
+
an already aborted call rejects immediately. stdout + stderr together are truncated by `maxOutputBytes` and set `truncated`; when truncating it backs up to a full
|
|
132
|
+
UTF-8 character boundary. envd sends a keepalive event every 50 seconds, so a command with no output for a long time is not disconnected by an intermediate proxy.
|
|
133
|
+
- **readFile / stat**: small `head -c` / `stat` scripts run in the sandbox as the sandbox user (permissions and symlinks are resolved as the sandbox user). A missing file → null,
|
|
134
|
+
and readFile on a directory also returns null.
|
|
135
|
+
- **list / scan** (projects): a `python3 -I` script (`src/listing.ts`, the same file as the Docker plugin's; it follows the rules of core's local device docker mode) runs in the sandbox as the
|
|
136
|
+
sandbox user under `timeout -s KILL 30` with `PATH=/usr/local/bin:/usr/bin:/bin`, the normalized path passed as argv. The reachable area is `/workspace` (core spec 2026-11-14 project root §4.2; the kernel scopes a cloud device's projects to it): a path
|
|
137
|
+
outside it, also through a link, is refused; a link whose target leaves it is not a directory. `scan` walks breadth-first, at most 500 directories, two levels below the
|
|
138
|
+
base, without following links. An abort returns at once; the read-only script ends at its time limit at worst. A template without python3 or timeout gets a clear error (the
|
|
139
|
+
published template has both), and so does a listing that hits the 30 s limit.
|
|
140
|
+
- **writeFile**: envd's upload endpoint opens the target as root and follows symlinks, so writing to the target directly could bypass permissions with something like `/workspace/l -> /etc`.
|
|
141
|
+
So the plugin only transfers the bytes to a root-only staging directory `/opt/capybara/upload/<uuid>` (`/opt/capybara` owned by root, 0700), then runs as root
|
|
142
|
+
`runuser -u sandbox -- sh -c 'mkdir -p …; cat > target' < staging file`: root only opens the staging file, while creating the directory and writing the target are both resolved as the
|
|
143
|
+
sandbox user; the staging file is deleted whether it succeeds or not (when aborted it may remain in the root-only directory and is removed with the sandbox).
|
|
144
|
+
- **/skills is read-only**: `/skills` is owned by root (0755) and the sandbox user can only read it. `writeFile("/skills/…")` writes directly as root (`umask 022`,
|
|
145
|
+
file mode 0644); the sandbox user cannot place symlinks in `/skills`, so root's writes cannot be redirected elsewhere.
|
|
146
|
+
|
|
147
|
+
## Network policy (`limits.network`)
|
|
148
|
+
|
|
149
|
+
The kernel sends the device's effective sandbox network as `limits.network` (`{ kind: "open-public" | "allowlist", hosts }`; the
|
|
150
|
+
limits carry no mode: the microVM is the sandbox, see "Permission profiles"). This plugin enforces the network and never reads any
|
|
151
|
+
org or device setting. Every network policy uses **the same template** (one image for all); the policy changes only the network. cpu / memory / disk stay those of the template (see
|
|
152
|
+
"Resources").
|
|
153
|
+
|
|
154
|
+
E2B's network control ([docs](https://docs.e2b.dev/sandbox/internet-access); the allowlist mapping was verified against the live
|
|
155
|
+
API on 2026-11-14, the field names against the `e2b@2.58.0` SDK's `SandboxNetworkConfig` / `SandboxNetworkUpdateConfig`):
|
|
156
|
+
|
|
157
|
+
| `limits.network` | Setting when creating the sandbox | Body of `update` (`PUT /sandboxes/{id}/network`) |
|
|
158
|
+
|---|---|---|
|
|
159
|
+
| `{ kind: "allowlist", hosts: [...] }` with hosts | `network: { allowOut: hosts, denyOut: DENIED }` | `{ allowOut: hosts, denyOut: DENIED }` |
|
|
160
|
+
| `{ kind: "allowlist", hosts: [] }` | `allow_internet_access: false` | `{ allow_internet_access: false }` |
|
|
161
|
+
| `{ kind: "open-public", hosts }` | `allow_internet_access: true, network: { denyOut: OPEN_DENIED }` | `{ allow_internet_access: true, denyOut: OPEN_DENIED }` |
|
|
162
|
+
|
|
163
|
+
`DENIED` is `["0.0.0.0/0", "fc00::/7", "fe80::/10", "::1/128"]`: all IPv4, plus IPv6 unique-local,
|
|
164
|
+
link-local and loopback.
|
|
165
|
+
|
|
166
|
+
`OPEN_DENIED` (`OPEN_PUBLIC_DENIED` in `src/e2b-api.ts`) is every IPv4 range the SDK closes in open-public mode, taken from
|
|
167
|
+
plugin-sdk's `OPEN_PUBLIC_DENIED_CIDRS` (private, CGNAT, loopback, link-local and metadata including `168.63.129.16`, multicast,
|
|
168
|
+
broadcast and the reserved and documentation ranges, `198.18.0.0/15` among them), plus `fc00::/7`, `fe80::/10` and `::1/128`.
|
|
169
|
+
`open-public` sends no `allowOut` (E2B's allowed entries take precedence over denied ones) and ignores its `hosts`. The expanded
|
|
170
|
+
list is accepted on create and on `update` (live 2026-11-19). `0.0.0.0/8` is not listed: E2B rejects it as an invalid CIDR (live
|
|
171
|
+
2026-11-14). A connection to `0.1.2.3` from inside an open-public VM does not reach a service, but it is not refused by the VM
|
|
172
|
+
either: E2B's network layer accepts the TCP connection and closes it without data (`curl: (52) Empty reply from server`, live
|
|
173
|
+
2026-11-19), so where E2B's layer would send such traffic is E2B's to say; treat `0.0.0.0/8` as a residual next to MMDS. The SDK's
|
|
174
|
+
IPv6 closed ranges are not sent (E2B rejects `::/0`; the microVM has no IPv6 route, below). E2B enforces `denyOut` by resolved destination IPv4 (`curl --resolve example.com:80:10.0.0.1`
|
|
175
|
+
is refused, verified live 2026-11-14), so a public name that resolves to a private address is refused too.
|
|
176
|
+
|
|
177
|
+
**Residual: the E2B metadata endpoint (MMDS) is reachable under every network policy.** The sandbox's own Firecracker MMDS at
|
|
178
|
+
`169.254.169.254` is not subject to E2B's egress filter: it answers `GET /latest/meta-data/` (401 without a token) and hands out
|
|
179
|
+
a token with `PUT /latest/api/token` even with `denyOut: ["169.254.169.254/32"]`, with every private range denied, under an
|
|
180
|
+
allowlist and with the network fully closed (`allow_internet_access: false`) — verified live on 2026-11-14. With a session token,
|
|
181
|
+
`GET /` answers 200 with the fields `accessTokenHash`, `address`, `envID` and `instanceID` (field names recorded live on
|
|
182
|
+
2026-11-19, values not). Refusing
|
|
183
|
+
`open-public` therefore removed no exposure, so the plugin maps it (decision D1 of core's 2026-11-15 auto mode hardening spec)
|
|
184
|
+
and states the residual here instead. Deployments for which the MMDS exposure is not acceptable run their devices on the Docker
|
|
185
|
+
plugin, whose egress proxy refuses private and metadata addresses by resolved IP.
|
|
186
|
+
|
|
187
|
+
**An older kernel is refused**: one that sends `tier` / `egress` / `allowHosts` (or a `network.kind` this plugin does not know)
|
|
188
|
+
gets an English error instead of a guessed policy, so a plugin upgraded without its kernel never opens the network. This plugin
|
|
189
|
+
version goes together with the approval-only profiles core release (support v2, limits without `mode`); upgrade the kernel and the
|
|
190
|
+
sandbox plugins together.
|
|
191
|
+
|
|
192
|
+
E2B's allowlist ([docs](https://docs.e2b.dev/sandbox/internet-access), verified 2026-10-21):
|
|
193
|
+
|
|
194
|
+
- Per-domain filtering applies only to **HTTP on port 80 (by the Host header) and TLS on port 443 (by SNI)**; other ports are filtered
|
|
195
|
+
only by IP / CIDR, and with only domains in the allowlist they are always blocked. UDP (QUIC / HTTP3) does not support per-domain
|
|
196
|
+
filtering.
|
|
197
|
+
- When a domain allowlist is used, E2B automatically allows **all traffic** to `8.8.8.8`, not only DNS on port 53, and adding
|
|
198
|
+
`8.8.8.8/32` to `denyOut` does not remove it (E2B documents this). The DNS queries themselves can be used to exfiltrate small
|
|
199
|
+
amounts of data. E2B's `dnsServers` setting (up to 10 IPv4 addresses, or an empty list) is the only documented control; it has an
|
|
200
|
+
effect only when a domain is in `allowOut`.
|
|
201
|
+
- **The per-domain allowlist is not a destination-IP control.** Domain matching inspects only the Host header on port 80 and the
|
|
202
|
+
SNI on 443; it does not check the destination IP. A live check (2026-11-14) showed that an allowed Host / SNI aimed at a
|
|
203
|
+
*private* IP is refused (the `denyOut` list wins), but the same Host / SNI aimed at any *public* IP is accepted: `curl --resolve
|
|
204
|
+
example.com:80:1.1.1.1` works. So an allowed name reaches any public IP on 80 / 443, and the plugin cannot resolve-and-pin the
|
|
205
|
+
destination the way the Docker egress proxy does. Only the destinations in `DENIED` are refused. The sandbox's metadata endpoint
|
|
206
|
+
is reachable regardless of the policy (see above).
|
|
207
|
+
- **IPv6**: `DENIED` covers IPv6 loopback (`::1/128`), link-local (`fe80::/10`) and unique-local (`fc00::/7`) as well as all IPv4.
|
|
208
|
+
E2B rejects `::/0` as an invalid denied CIDR (live 2026-11-14), so public IPv6 is not denied by CIDR; it is unreachable anyway
|
|
209
|
+
because the microVM has no global IPv6 address or route: `ip -6 addr` shows only `::1/128` and a link-local address, and a
|
|
210
|
+
control sandbox without the IPv6 deny list could not reach public IPv6 either (verified live 2026-11-14). If E2B ever gives the
|
|
211
|
+
microVM public IPv6, this list does not cover it.
|
|
212
|
+
- Other sites on the same CDN / object storage may also be allowed along with it (the E2B docs say this too).
|
|
213
|
+
- **For self-hosted E2B, network isolation is the operator's responsibility**: intranet services and cloud metadata addresses
|
|
214
|
+
(169.254.169.254 and so on) that the sandbox node can reach must be blocked at E2B's node / network layer; this plugin cannot do it
|
|
215
|
+
for you.
|
|
216
|
+
- If an egress that "checks the destination IP after resolving" is wanted later, E2B's `network.egressProxy` can be used (SOCKS5, see
|
|
217
|
+
SDK 2.58 `buildEgressProxyBody`): it sends all sandbox egress to our own proxy (for example the same checks as the Docker plugin's
|
|
218
|
+
egress proxy); this plugin does not use it yet.
|
|
219
|
+
- A rejected TCP connection may look "connected" inside the sandbox; you only know it was rejected from the application layer (HTTP
|
|
220
|
+
status, TLS handshake).
|
|
221
|
+
- `*.example.com` matches subdomains (same as the Docker plugin, not including `example.com` itself).
|
|
222
|
+
- For self-hosted E2B that does not support per-domain filtering, set `domainAllowlist: false`: an allowlist degrades to no network with
|
|
223
|
+
a warning (it never silently opens up).
|
|
224
|
+
- **The allowlist cannot stop data sent to allowlisted hosts** (the same as the Docker version): `git push` to github.com and publishing
|
|
225
|
+
to npm / PyPI are within the allowlist, and attachments in a conversation and data the agent has read can leak this way. Orgs that
|
|
226
|
+
handle sensitive data should set `sandboxToolPolicy` to `ask` in the org settings, and / or set the org's network to an empty
|
|
227
|
+
allowlist (no network at all).
|
|
228
|
+
|
|
229
|
+
**Limits apply at the file system** (`limitsApplyAt: "fileSystem"`): an instance is the same E2B sandbox resumed, so `create` cannot
|
|
230
|
+
change what `createFileSystem` set. A change of network policy reaches an existing device through **`update`**: the kernel calls it
|
|
231
|
+
under the exclusive lease, right after `resume`, when the device's network differs from what its instance applies. `update` sends `PUT /sandboxes/{id}/network` (the `e2b@2.58.0` SDK's `Sandbox.updateNetwork`), which replaces the whole network
|
|
232
|
+
configuration at once, with no restart: running commands keep running, new connections follow the new rules. Its limits:
|
|
233
|
+
|
|
234
|
+
- **Only a running sandbox can be updated**: a paused sandbox answers E2B's 404 (verified on E2B 2026-11-08; the live test keeps
|
|
235
|
+
recording it as `[e2b-live] paused network update: …`). `update` therefore connects first (a paused sandbox is resumed), then sends
|
|
236
|
+
the update; a 404 after that means the sandbox is gone (`SandboxGoneError`). Limits the plugin cannot read throw before the connect.
|
|
237
|
+
- **Only the network changes.** cpu / memory / disk and the template stay. A new allowlist host needs a change of the device's
|
|
238
|
+
network list (a host cannot be granted per call: the VM's network policy covers the whole instance).
|
|
239
|
+
- **A failed update answers `"recreate"`** (other than a gone VM, an abort, or a 401 / 403 credential error, which stay
|
|
240
|
+
errors): the VM keeps its old policy, and the kernel records the limits unapplied and offers a file reset, so the device always
|
|
241
|
+
has a way forward.
|
|
242
|
+
- Connections already open when the rules narrow are E2B's business; the docs do not say whether they are cut.
|
|
243
|
+
|
|
244
|
+
**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`,
|
|
245
|
+
default 900 seconds, Ruling M20); to run long commands, raise `runtime.maxRunSeconds` to at least `maxCommandSeconds`.
|
|
246
|
+
|
|
247
|
+
## Permission profiles (operation contract)
|
|
248
|
+
|
|
249
|
+
The provider implements the permission operation contract of `device-provider@1`: `permissionSupport`, a
|
|
250
|
+
fresh immutable `operation` per invocation, owner `browse`, trusted `prepare` (skills and
|
|
251
|
+
attachments), `revokeOperation` and exact `background` supervision (`start`, `status`, `tail`,
|
|
252
|
+
`readOutput`, `stop`). It changes nothing about the device: one VM, its OS user, files, installed
|
|
253
|
+
environment and network stay shared, no conversation grant updates the VM's network, and no other
|
|
254
|
+
VM is ever made from copied files.
|
|
255
|
+
|
|
256
|
+
**The instance is the sandbox** (core `2026-11-19-approval-only-profiles-design.md`, decision 1):
|
|
257
|
+
the microVM is the boundary; its whole filesystem is every operation's scope and its network
|
|
258
|
+
policy (above) is the sandbox network. All three profiles are offered and differ only in who
|
|
259
|
+
approves sensitive commands. There are no directory crossings, no running outside the sandbox and
|
|
260
|
+
no per-call host grants. So:
|
|
261
|
+
|
|
262
|
+
- `permissionSupport` answers `{ version: 2, boundary: "instance", restricted: null, network: {
|
|
263
|
+
openPublic: true, allowlist, perOperationHosts: false }, outsideSandbox: false, background: true
|
|
264
|
+
}`, with `allowlist: false` where `domainAllowlist` is off. It stages the runtime when the VM has
|
|
265
|
+
none yet and checks its owners, modes and digests; a runtime it cannot trust offers nothing
|
|
266
|
+
(`background: false`, both network kinds false) and says why in `unavailableReason`. It answers
|
|
267
|
+
only for a running VM and never resumes one.
|
|
268
|
+
- `operation` and `background.start` run the kernel's whole-instance scope (`filesystem: scoped`
|
|
269
|
+
with `/` and the working root readable and writable) under every profile: the provider's ordinary
|
|
270
|
+
exec wrapper (the existing OS user, environment and VM network) behind the admission check, and
|
|
271
|
+
native file calls through the SDK native helper on `/` as the device user. The VM's network
|
|
272
|
+
policy covers every operation, so an operation must allow at least what the VM applies, read from
|
|
273
|
+
`GET /sandboxes/{id}` (no connect): `allowInternetAccess: false` is no network, `network.allowOut`
|
|
274
|
+
an allowlist, internet access with `network.denyOut` covering this version's `OPEN_DENIED`
|
|
275
|
+
open-public (field names verified live 2026-11-19). A narrower operation is refused with
|
|
276
|
+
`SandboxScopeDeniedError` before any VM call, never silently widened. An open-public VM made by
|
|
277
|
+
an earlier version with a shorter deny list is upgraded, not refused: `resume` and the network
|
|
278
|
+
check of every operation re-apply the current open-public policy (`PUT /sandboxes/{id}/network`,
|
|
279
|
+
connecting the VM first). A failed re-apply is an ordinary error, retried on the next use; a
|
|
280
|
+
file reset also applies the current policy.
|
|
281
|
+
- They refuse before any VM call, with `SandboxPermissionUnsupportedError` and never widened, the
|
|
282
|
+
escalated pair (device files plus the environment network: an instance has no outside) and any
|
|
283
|
+
filesystem grant narrower than the whole instance (restricted filters: the SDK launcher needs
|
|
284
|
+
Landlock ABI 6, which the tested template, `capybara-sandbox-0-1-0-rc-13` with Linux `6.1.189+`
|
|
285
|
+
and Landlock ABI 2, does not provide).
|
|
286
|
+
|
|
287
|
+
**Runtime staging.** Templates built before the runtime existed have none, so the provider stages
|
|
288
|
+
it in the VM itself on first use: the SDK's `native-files.py` and `linux-sandbox.py` (unchanged
|
|
289
|
+
bytes) and this provider's agent `runtime/capybara-operation.py` (an adapted copy of
|
|
290
|
+
device-docker's agent without the restricted launch path; embedded in
|
|
291
|
+
`src/operation-agent-source.ts`, regenerate with `node plugins/device-e2b/scripts/gen-agent-source.mjs`)
|
|
292
|
+
are uploaded as root to the root-only `/opt/capybara/upload`, checked by root against `SHA256SUMS`
|
|
293
|
+
and moved with one rename into `/opt/capybara-e2b-runtime/<digest prefix of SHA256SUMS>/` (root, 0755 /
|
|
294
|
+
0644). The directory is named after the digest of every staged file, so each provider version runs
|
|
295
|
+
only its own agent next to its own SDK bytes (an SDK upgrade stages a fresh directory); the agent
|
|
296
|
+
re-checks the SDK files' digests and owners on every launch, and
|
|
297
|
+
`permissionSupport` checks owners, modes and digests before reporting anything.
|
|
298
|
+
|
|
299
|
+
**Records.** Consume records, tombstones, cancellation markers and background records live in
|
|
300
|
+
`/opt/capybara-e2b-ops` (root, 0711; records 0600) on the VM's disk, so they survive a pause
|
|
301
|
+
(which ends every process) and are out of the device user's reach on the whole instance. Every
|
|
302
|
+
method consumes its operation ID before any effect: a retry with the same method and input is an
|
|
303
|
+
unknown outcome (never a repeat), a different one a validation error. `revokeOperation` writes the
|
|
304
|
+
tombstone first, kills the operation's foreground wrapper and its background execution, and
|
|
305
|
+
reports a retry when the VM rebooted meanwhile. On a paused VM it stays pending (it throws, the
|
|
306
|
+
kernel retries) even past the admission deadline: the provider pauses without memory, but a paused
|
|
307
|
+
VM cannot confirm that nothing of the operation survives (a control plane that restores a memory
|
|
308
|
+
snapshot would bring its processes back), so success waits for a running VM. A native call
|
|
309
|
+
(read, write, list) that passed its admission check before the tombstone was written runs to its
|
|
310
|
+
end: revocation stops executions, not an in-flight native call, as on Docker (the kernel aborts
|
|
311
|
+
the call first).
|
|
312
|
+
|
|
313
|
+
**Root runs only a verified agent.** Every root run of the agent goes through an inline
|
|
314
|
+
`python3 -I -c` check: `/`, `/opt`, the runtime base and directory and the agent file must be
|
|
315
|
+
root-owned, not group or world writable and of the right type, and the agent's bytes must match the
|
|
316
|
+
provider's pinned digest; only then is the agent executed in the same process. A missing or
|
|
317
|
+
untrusted runtime (for example a planted directory) is restaged, which replaces an untrusted
|
|
318
|
+
directory, and the call is retried once. An aborted or timed-out agent command is killed in the
|
|
319
|
+
VM (envd SIGKILL by pid, also when the abort came before envd reported the pid), never left
|
|
320
|
+
running; an aborted background start's detached supervisor is then stopped by its recorded
|
|
321
|
+
identity. A kill that cannot be confirmed (the signal fails, or the stream stays open past the
|
|
322
|
+
grace period) reboots the VM, as for exec; on the paths that never resume a paused VM (status,
|
|
323
|
+
output, stop, revocation, support) a VM that is not running is left paused and the call reports
|
|
324
|
+
an unknown outcome.
|
|
325
|
+
|
|
326
|
+
**Background executions** (on the whole instance) use the same design as device-docker: a detached
|
|
327
|
+
supervisor per operation, a root recorder that accepts the supervisor's frames only on the root
|
|
328
|
+
UNIX socket connection whose `SO_PEERCRED` pid, start time, exact argv, stdin token and admitted
|
|
329
|
+
request digest match, an acceptance byte before any launch, and an unacknowledged start kept for
|
|
330
|
+
the same-ID retry only when `bg-start` exited 0 with exactly one result frame. Requests reach the
|
|
331
|
+
agent only on its stdin (envd `SendInput` / `CloseStdin`), never argv or the environment. Status,
|
|
332
|
+
tail, output reads and stop use `GET /sandboxes/{id}` (state and envd token, no connect) and never
|
|
333
|
+
resume a paused VM; work of a previous boot reports `lost`.
|
|
334
|
+
|
|
335
|
+
Residual trust (as on Docker, "M5"): the work of every conversation shares the device uid, so it can signal or
|
|
336
|
+
ptrace sandbox-user processes such as a background supervisor (the template has no Yama
|
|
337
|
+
restriction); it cannot change root-owned records or runtime files. Stop and revocation end the
|
|
338
|
+
background supervisor and the process group it owns; descendants that escaped it (`setsid`, a
|
|
339
|
+
daemon) survive them, as on Docker. The foreground wrapper also finds escaped processes by their
|
|
340
|
+
environment marker; background work has no such marker. Only a VM pause ends them.
|
|
341
|
+
|
|
342
|
+
## Resources (`limits.cpu` / `memoryMb` / `diskMb`)
|
|
343
|
+
|
|
344
|
+
E2B's CPU and memory are fixed **when the template is built** (`cpuCount` / `memoryMB` of `Template.build`) and cannot be specified per sandbox at creation; disk size is decided by
|
|
345
|
+
E2B's plan / template. So for `limits` cpu / memoryMb / diskMb this plugin only validates them (at `createFileSystem`) and **does not apply them per sandbox**: the template it builds
|
|
346
|
+
itself has the kernel defaults of 1 core / 2048 MB; for another spec build your own template (the example above) and set `template`. The sandbox CPU / memory overrides the super admin sets for an org in the admin console
|
|
347
|
+
(deployment setting `sandboxLimitOverrides`) likewise **have no effect on this plugin**: to give some orgs a bigger spec, the only way is to switch to a different deployment
|
|
348
|
+
(or template).
|
|
349
|
+
|
|
350
|
+
## Client
|
|
351
|
+
|
|
352
|
+
It does not use the official `e2b` SDK and instead has a minimal hand-written client (`src/e2b-api.ts`, the global `fetch`, no third-party dependencies):
|
|
353
|
+
|
|
354
|
+
- Every request carries the caller's AbortSignal directly, so abort semantics are controllable (the command stream is disconnected by the plugin itself: kill the process first, then disconnect);
|
|
355
|
+
- The official SDK reads process environment variables such as `E2B_API_KEY` / `E2B_DOMAIN` / `E2B_SANDBOX_URL` / `E2B_DEBUG` and caches a connection pool at module level
|
|
356
|
+
(the multi-replica discipline does not allow module-level mutable state in a plugin), and it also brings undici, Connect, protobuf and a string of other dependencies;
|
|
357
|
+
- It uses only 10 control plane endpoints (4 of them for the template build) and 3 envd endpoints, with the protocol following the SDK `e2b@2.58.0` implementation (listed in the header comment of `src/e2b-api.ts`).
|
|
358
|
+
|
|
359
|
+
Protocol sources (verified 2026-10-21): `dist/index.mjs` of `e2b@2.58.0`; the E2B docs
|
|
360
|
+
[internet-access](https://docs.e2b.dev/sandbox/internet-access), [persistence](https://docs.e2b.dev/sandbox/persistence),
|
|
361
|
+
[sandbox lifecycle](https://docs.e2b.dev/sandbox), [template quickstart](https://docs.e2b.dev/template/quickstart),
|
|
362
|
+
[template migration (fromDockerfile)](https://docs.e2b.dev/template/migration-v2); the envd source
|
|
363
|
+
[upload.go](https://github.com/e2b-dev/infra/blob/main/packages/envd/internal/api/upload.go).
|
|
364
|
+
|
|
365
|
+
## Test-only options
|
|
366
|
+
|
|
367
|
+
The third parameter of `createE2BSandbox(config, { log }, testOptions)` can be passed only by code that calls it directly; the plugin config cannot set it:
|
|
368
|
+
|
|
369
|
+
- `envdUrl`: the envd address is changed to this (routed by the `E2b-Sandbox-Id` request header), instead of being assembled from the sandbox id and domain.
|
|
370
|
+
- `listPath`: the PATH `list` / `scan` run with (the fake E2B runs commands on the test machine).
|
|
371
|
+
- `loseBackgroundAck(taskId)`: drops a background start's acknowledgement as if the transport lost
|
|
372
|
+
it (the live lost-acknowledgement test).
|
|
373
|
+
- `backgroundStartCommand(taskId, cmd)`: replaces the real `bg-start` command of a background start.
|
|
374
|
+
|
|
375
|
+
## Tests
|
|
376
|
+
|
|
377
|
+
- `test/device-e2b.test.ts`: against `startFakeE2B` from `@capybara-hq/testing` (control plane API + envd, Connect stream protocol,
|
|
378
|
+
commands really run in a local temp directory), covering each method, error mapping (404 → gone, 401 / 5xx → ordinary errors), abort, kill on timeout,
|
|
379
|
+
file reads and writes and the way `/skills` is written, the network policy mapping (an allowlist, an empty allowlist as no network,
|
|
380
|
+
`open-public` as internet access with `OPEN_DENIED` covering the SDK's closed IPv4 classes, an older kernel's limits refused before any E2B call), `update` (against a stub of
|
|
381
|
+
`PUT /sandboxes/{id}/network` in front of the fake, which has no network route: resume first, the bodies, gone and refused cases), and the reboot backstop when killing fails / the output stream does not end (the fake server's `memory: false` connect ends all processes);
|
|
382
|
+
file systems and instances (files survive destroy and recreate, connect 404 → `FileSystemGoneError`, pause drops memory, cleanup by name), and the template
|
|
383
|
+
auto-build (built once from the image, polled until ready, an existing alias reused, a not-ready alias rebuilt, a failed build not memoised).
|
|
384
|
+
- `test/permission-scopes.test.ts`: the staged runtime bytes (SDK files unchanged, the embedded
|
|
385
|
+
agent equal to `runtime/capybara-operation.py` and its digest), the envd stdin calls, and every
|
|
386
|
+
path that must refuse before any VM call (the escalated pair and narrower grants, a malformed scope, foreign
|
|
387
|
+
references, preparation roots, browsing inside the records, output bounds) or must never resume a
|
|
388
|
+
paused VM (status, tail, output, stop, support, revocation).
|
|
389
|
+
- `test/live/permission-scopes.live.test.ts`: real E2B (same switches as below): support v2 and
|
|
390
|
+
the template's kernel facts, `runSandboxPermissionConformance` and `runSandboxNativeConformance`
|
|
391
|
+
(through whole-instance operations) on the actual provider, every profile's OS rights and VM
|
|
392
|
+
network (positive and negative) without a network update, the escalated pair refused,
|
|
393
|
+
consume-once, revocation, overlap orders, background executions, records out of reach,
|
|
394
|
+
preparation, browsing, and a paused VM never resumed. One VM, deleted and asserted absent at the
|
|
395
|
+
end.
|
|
396
|
+
- `test/live`: real E2B, run only when `CAPYBARA_TEST_E2B_API_KEY` is set (optionally `CAPYBARA_TEST_E2B_TEMPLATE`, unset to exercise the auto-build,
|
|
397
|
+
and `CAPYBARA_TEST_E2B_API_URL` / `CAPYBARA_TEST_E2B_DOMAIN`), otherwise skipped: the template, the file system created paused, the sandbox user, files, `/skills` read-only (including a write through a symlink being
|
|
398
|
+
rejected), the network allowlist, `open-public` (a public host reachable, private / loopback / CGNAT / link-local destinations
|
|
399
|
+
refused, at create and by `update`), the metadata endpoint staying reachable under every policy (the documented residual), output truncation, kill on timeout (including nohup child processes), abort, long periods with no output, a
|
|
400
|
+
child process that escaped the session being killed by its environment marker,
|
|
401
|
+
files surviving instance destroy, whether a paused sandbox's network rules can change, `destroyFileSystem` → `FileSystemGoneError`. The file header lists the "assumptions that can only be confirmed on real E2B"; check them one by one on the first run.
|
|
402
|
+
|
|
403
|
+
## Icon
|
|
404
|
+
|
|
405
|
+
`icon.svg`: the E2B symbol (owner: E2B), downloaded on 2026-11-08 from the E2B brand page, https://e2b.dev/brand
|
|
406
|
+
(e2b-symbol-fire-orange-s.svg). It is a trademark of its owner, used only to identify the service
|
|
407
|
+
this plugin connects to; the plugin is not affiliated with or endorsed by the owner. The artwork is
|
|
408
|
+
unchanged except for removing editor metadata and setting a square viewBox.
|