npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@amond-ai/sandbox-e2b

v0.2.0

Published

An e2b backend for @amond-ai/sandbox — journals process transcripts and exit status to the sandbox filesystem, because e2b forgets a process the moment it exits

Readme

@amond-ai/sandbox-e2b

An e2b backend for @amond-ai/sandbox.

import { createE2bProvider, e2bSandboxApi } from '@amond-ai/sandbox-e2b'

const provider = createE2bProvider({
  api: e2bSandboxApi({ apiKey: process.env.E2B_API_KEY }),
  template: 'claude',
  journalRoot: '/home/user/.agent-runs',
})
const session = provider.session(sandboxIdForRun(runId))

In apps/cf-orchestrator you do not construct it directly — set SANDBOX_BACKEND=e2b and the E2B_API_KEY secret, and sandboxProvider(env) builds this instead of the Cloudflare one.

The template

The provider's default template is e2b's prebuilt claude image, which ships the CLI and nothing else of ours. The sdk turn driver execs /opt/turn-host/bridge.mjs — a bundle only docker/Dockerfile bakes — so on the stock template it is simply not there, and sandboxProvider refuses that pairing rather than starting a turn host that cannot run (#385).

The template that does carry it is pleaseworks, built from the Dockerfile's e2b-sandbox stage. CI (.github/workflows/docker-sandbox.yml, build-push) publishes that stage to ghcr.io/chatbot-pf/pleaseworks-e2b on pushes to main that touch the image inputs (the workflow's paths), naming the immutable sha- tag it just pushed as a job output.

The e2b-template job then rebuilds the alias in three steps — candidate → probe → promote — because no rollback exists for an alias:

  1. build pleaseworks-candidate from that sha- tag (scripts/build-template.ts),
  2. boot it and assert the four things a turn depends on (scripts/check-template.ts),
  3. rebuild the live pleaseworks alias from the candidate (E2B_TEMPLATE_FROM), which pulls nothing from a registry, and probe it once more.

So the live alias is only ever repointed at a template that has already run a turn's dependencies, and a failed build, a failed probe, or a cancelled run leaves it untouched.

The job runs on main only: a workflow_dispatch from a branch still publishes the image under its sha- tag, but the alias a deployed Worker boots is not repointed from an unmerged ref, and build-push says so. The rebuild also needs the E2B_API_KEY repository secret; without it the image is still published and the job reports itself skipped, leaving the alias on whatever image it was last built from.

Build it by hand only when CI cannot — the same two scripts, from a machine that holds the key:

# The image is private, so e2b's builder needs a GHCR login of its own.
infisical run --silent -- env GHCR_USERNAME=<login> GHCR_TOKEN=<read:packages token> \
  E2B_TEMPLATE_ALIAS=pleaseworks-candidate bun packages/sandbox-e2b/scripts/build-template.ts
infisical run --silent -- env E2B_TEMPLATE=pleaseworks-candidate \
  bun packages/sandbox-e2b/scripts/check-template.ts
# Promote only once the candidate has passed.
infisical run --silent -- env E2B_TEMPLATE_ALIAS=pleaseworks \
  E2B_TEMPLATE_FROM=pleaseworks-candidate bun packages/sandbox-e2b/scripts/build-template.ts

| Variable | Default | Read by | | --- | --- | --- | | E2B_API_KEY | (required) | both scripts, through the SDK | | E2B_TEMPLATE_IMAGE | ghcr.io/chatbot-pf/pleaseworks-e2b:latest (CI passes the sha- tag) | build, from an image | | E2B_TEMPLATE_FROM | (unset) — set it to build from that template alias instead of an image, needing no GHCR credentials | build | | E2B_TEMPLATE_ALIAS | pleaseworks | build | | E2B_TEMPLATE_CPU / E2B_TEMPLATE_MEMORY_MB | 2 / 4096 | build | | GHCR_USERNAME / GHCR_TOKEN | (both required unless E2B_TEMPLATE_FROM is set) | build | | E2B_TEMPLATE | pleaseworks | check |

The alias is what E2B_TEMPLATE in apps/cf-orchestrator/wrangler.jsonc must name: a Worker pointed at a template this script never built boots e2b's stock image instead. The parsing lives in src/template-config.ts rather than in the script, so it is testable without the SDK.

The per-command timeout is disabled on purpose

e2b's CommandStartOpts.timeoutMs defaults to 60 seconds, and it applies to background commands — measured, not inferred (scripts/spike-e2b-command-timeout.ts): a background wrapper sleeping 95s left only its first marker under the default and completed under 0.

Every claude turn and every repository clone longer than a minute would be killed, and the kill lands before the journal wrapper's trailing printf '%s' "$?", so it arrives as SandboxNoExitRecordError rather than as a timeout — the same shape as a crashed wrapper.

commandTimeoutMs therefore defaults to 0. A turn's bounds belong to the orchestrator that started it: the liveness watchdog, the workflow step timeouts, and the sandbox lifetime. Pass a non-zero value only if you want a budget none of those know about.

Why this package is not thin

e2b forgets a process the moment it exits. Measured, not inferred (research note 027):

| | Measured | | --- | --- | | commands.connect(pid) on a running command | replays nothing — only output produced after the reconnect | | commands.connect(pid) on an exited command | throws [not_found] | | commands.list() after exit | 0 processes | | a file the command redirected into | survives exit and Sandbox.connect(sandboxId) |

The run workflow reads a turn's transcript after it exits, so the first three rows are the whole problem and the fourth is the whole answer. This backend journals four files per process into journalRoot:

<id>.out        stdout          <id>.exit       printf '%s' "$?"
<id>.err        stderr          <id>.meta.json  id, pid, argv, cwd, startedAt

logs({ follow: true }) tails those files rather than snapshotting them (log-follow.ts), because a live consumer exists: @amond-ai/harness-sandbox follows the AI SDK bridge, and @ai-sdk/harness reads end-of-stream as "the bridge exited". Until 2026-08-27 this backend answered follow with the same EOF-terminated snapshot every other read used — invisible to the orchestrator, which reads a turn after it exits, and fatal to the harness, whose bridge readiness became a race. Measured with scripts/spike-e2b-follow.ts: the stream closed at 1489ms against a process that ran to 16680ms; it now stays open to 17025ms. The tail polls on its own interval because e2b has no byte-range read, so every poll re-transfers the file — on every poll, not only the idle ones, because a process that is always mid-write would otherwise never let the loop rest.

Where it starts is replay's to decide, in the contract's own words — the retained log from the beginning, or the live tail. A follower that omits it gets the tail, which costs one full read of each journal file at subscribe time and nothing afterwards; harness-sandbox passes replay: true precisely because it wants the bridge's startup banner. That positioning read is the one place a failed read may not be treated as silence: answering 0 would put the tail at the beginning and replay the whole transcript into a subscriber that asked for none of it, so an absent file is 0 and anything else fails the subscription.

It ends on e2b's process table, not on the exit file, for the reason statusOf gives: the turn can write that file itself, and a wrapper that was killed never writes one at all — the trailing printf '%s' "$?" dies with its session. So an exit record only forces a liveness probe, and a process that is gone with no record ends the stream as the no_exit_record terminal rather than as silence. Measured in the same spike: a killed wrapper closed the stream at 6467ms with terminal/error.

stdout and stderr are separate files rather than one interleaved stream because ProcessLogEvent is tagged per stream and demuxProcessEvents splits on that tag — the NDJSON turn output must not be polluted by whatever the CLI writes to stderr. logs() then projects those files back into ProcessLogEvents, and status()/waitForExit() answer from the exit file. A cold provider that never saw the run reconnects by sandbox id and replays a byte-identical transcript; scripts/spike-e2b-turn.ts measures exactly that against a live claude turn.

Two things e2b's shape forced

Identity. The contract addresses a sandbox by the id the orchestrator chose (sandboxIdForRun(runId)); e2b mints its own. The orchestrator's id is written into e2b metadata at create time and looked up through Sandbox.list({ query: { metadata } }), whose default state filter covers paused sandboxes as well as running ones — a retried workflow step must reach the sandbox its predecessor left behind, whatever state e2b put it in.

Timing. SandboxProvider.session is synchronous by contract, because the Cloudflare backend resolves a Durable Object stub with no I/O. Acquiring an e2b sandbox is a network call, so it is deferred to the session's first use and memoised — session(id) on its own costs nothing, one sandbox is created per id, and concurrent first calls share a single acquisition rather than racing to create two.

One thing improves. listProcesses() reports exited processes too, since it scans the journal rather than e2b's live-only table. The idempotency guard filters with isLive(status), so this is extra information, not a behaviour change.

Layout

| File | Role | | --- | --- | | provider.ts | createE2bProvider — identity, lazy acquisition, session cache | | e2b-session.ts | The SandboxSession/SandboxProcessHandle implementation | | journal.ts | Paths, the redirect wrapper, and the meta record | | log-reads.ts | The three shapes logs() answers in — whole transcript, positioned, following | | log-replay.ts | Journal bytes → ProcessLogEvents, with a byte-offset cursor | | log-follow.ts | The tail: polls the journal until the process exits or the caller aborts | | shell-quote.ts | The double-layer quoting search e2b alone needs; the quoting itself is shared via @amond-ai/sandbox/journal | | e2b-api.ts | The only file that touches the real e2b SDK | | template-config.ts | What scripts/build-template.ts needs, read off the environment |

Everything except e2b-api.ts takes e2b as a structural interface, so the whole backend is testable against a fake with no network (bun test).

Upstream

The AI SDK tracks a first-party E2B provider in vercel/ai#17636, with an open PR in vercel/ai#21891. This repository tracks the upstream provider issues in amond-ai/harness#64.