mirror of
https://github.com/desplega-ai/agent-fs.git
synced 2026-09-14 20:46:59 +08:00
2pac
a50663796c
QA on a fresh Hetzner cx23 Ubuntu 24.04 VM (post-v0.7.0 release) surfaced two install papercuts the docs were perpetuating: 1. `npm install -g @desplega.ai/agent-fs` aborts on stock Ubuntu/Debian Node 18.x because `node-llama-cpp@3.18` postinstall ships an ES2023 `import ... with { type: 'json' }` syntax that Node <18.20 rejects. Bun's installer doesn't share this code path. All install snippets now use `bun install -g`. Tracking the deeper fix (move node-llama-cpp to optionalDependencies or pin to a pre-3.18 release) in DES-455. 2. `bun.sh/install` requires `unzip` on Linux; missing from the apt line in the Hetzner doc. Added it. 3. Hetzner retired the `cx22` server type. Updated the example to `cx23` (x86, same 2 vCPU/4 GB tier) with a note for `cax11` on ARM.
105 lines
3.9 KiB
Markdown
105 lines
3.9 KiB
Markdown
# Mounting agent-fs on E2B
|
|
|
|
> **Status**: untested. Best-effort instructions follow based on E2B's documented FUSE support. Please report results at <https://github.com/desplega-ai/agent-fs/issues>.
|
|
|
|
E2B sandboxes run on Firecracker microVMs whose kernel ships `CONFIG_FUSE_FS=y` — FUSE is a first-class capability. E2B's `connect-bucket` API uses FUSE (s3fs / gcsfuse / R2 helpers) under the hood, so the kernel-side plumbing is known to work. What we have **not** validated as of 2026-05-18 is `agent-fs mount` specifically running inside an E2B sandbox.
|
|
|
|
> See [`README.md`](./README.md) for the general overview and architecture. See [`fuse-compat.md`](../fuse-compat.md#e2b) for the upstream compatibility note.
|
|
|
|
## Expected prerequisites
|
|
|
|
E2B's default sandbox image (`base`) does **not** ship `fuse3`. You'll need a custom sandbox built from a Dockerfile that adds it.
|
|
|
|
### Dockerfile snippet (best-effort)
|
|
|
|
```dockerfile
|
|
FROM e2bdev/code-interpreter:latest
|
|
|
|
# fuse3 for agent-fs mount
|
|
RUN apt-get update -qq \
|
|
&& apt-get install -y --no-install-recommends fuse3 ca-certificates curl \
|
|
&& rm -rf /var/lib/apt/lists/*
|
|
|
|
# Bun (for `bun install -g @desplega.ai/agent-fs` — npm install -g aborts on stock Node 18.x)
|
|
RUN curl -fsSL https://bun.sh/install | bash
|
|
ENV PATH="/root/.bun/bin:${PATH}"
|
|
|
|
# Pre-install agent-fs (so the FUSE sub-package is resolved at image build time)
|
|
RUN bun install -g @desplega.ai/agent-fs
|
|
|
|
# fuse.conf — only needed if you mount with --allow-other
|
|
RUN echo user_allow_other >> /etc/fuse.conf
|
|
|
|
# /etc/mtab → /proc/mounts symlink (E2B base may or may not have this)
|
|
RUN [ -e /etc/mtab ] || ln -sf /proc/mounts /etc/mtab
|
|
```
|
|
|
|
Build with the E2B CLI:
|
|
|
|
```bash
|
|
e2b template build --name agent-fs-fuse --dockerfile e2b.Dockerfile
|
|
```
|
|
|
|
## Expected mount flow
|
|
|
|
Inside the sandbox (Python SDK example — adapt to JS as needed):
|
|
|
|
```python
|
|
from e2b_code_interpreter import Sandbox
|
|
|
|
sandbox = Sandbox(template="agent-fs-fuse")
|
|
|
|
# Configure auth
|
|
sandbox.commands.run("mkdir -p ~/.agent-fs")
|
|
sandbox.files.write("~/.agent-fs/config.json", """{
|
|
"apiUrl": "https://agent-fs-taras.fly.dev",
|
|
"apiKey": "<YOUR_API_KEY>"
|
|
}""")
|
|
|
|
# Mount
|
|
sandbox.commands.run("mkdir -p ~/mnt")
|
|
sandbox.commands.run("agent-fs mount ~/mnt --remote", background=True)
|
|
|
|
# Use
|
|
sandbox.commands.run("ls ~/mnt/current")
|
|
sandbox.commands.run("echo 'hello from e2b' > ~/mnt/current/e2b-test.txt")
|
|
```
|
|
|
|
## What might still go wrong
|
|
|
|
E2B's runtime documentation states FUSE works, but there are degrees of "works":
|
|
|
|
| Risk | What to check |
|
|
|---|---|
|
|
| `/dev/fuse` not exposed to the sandbox user | `ls -l /dev/fuse` inside the sandbox. If missing or unreadable, the E2B template may need to be configured to expose it — open a ticket. |
|
|
| `SYS_ADMIN` capability not granted | `agent-fs mount` will return `Operation not permitted`. E2B's stock template should have it; custom templates may strip it. |
|
|
| `fusermount3` not on `PATH` | Confirm the Dockerfile snippet above installed `fuse3`. |
|
|
| Sandbox lifecycle terminates the mount | Sandboxes can be paused/resumed. The mount may need to be re-established after resume. |
|
|
|
|
## Fallback: CLI / HTTP without mount
|
|
|
|
If `agent-fs mount` doesn't work in your E2B sandbox, fall back to direct CLI / HTTP. All file operations are reachable without FUSE:
|
|
|
|
```bash
|
|
agent-fs ls /
|
|
agent-fs cat /path/to/file
|
|
echo "..." | agent-fs write /path/to/file --stdin
|
|
```
|
|
|
|
## Help us validate this
|
|
|
|
If you successfully mount agent-fs in an E2B sandbox, please open a PR updating this doc with:
|
|
|
|
- E2B SDK version
|
|
- Sandbox template used (or full Dockerfile)
|
|
- Any extra steps not listed here
|
|
- A session log of `agent-fs mount ~/mnt --remote && ls ~/mnt`
|
|
|
|
Report at <https://github.com/desplega-ai/agent-fs/issues>.
|
|
|
|
## See also
|
|
|
|
- [`README.md`](./README.md) — overview and shared prerequisites
|
|
- [`fuse-compat.md`](../fuse-compat.md#e2b) — E2B in the sandbox compatibility matrix
|
|
- [`fuse-troubleshooting.md`](../fuse-troubleshooting.md) — full error catalogue
|