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-local

v0.2.0

Published

A local-process backend for @amond-ai/sandbox — runs the command on this machine and journals it to disk, so a desktop app that was killed and relaunched can still find the turn it started

Readme

@amond-ai/sandbox-local

A local-process backend for @amond-ai/sandbox: the command runs on this machine, in a directory named after the sandbox id.

import { createLocalProvider } from '@amond-ai/sandbox-local'

const provider = createLocalProvider({ root: `${Deno.env.get('HOME')}/.myapp/sandboxes` })
const session = provider.session(sandboxIdForRun(runId))

It exists for the desktop case. e2b works from a desktop app, but every turn ships the user's workspace to a remote host, needs an account and an API key, and turns an offline-capable app into one that fails without network — which inverts the design of an app whose whole premise is local files. Docker gives real isolation and is the honest answer for a server, but it is a prerequisite the user has to install and keep running, and it does not help the offline case any more than a local process does.

This is not a sandbox

The name is the contract's, not a claim about this backend. There is no filesystem boundary, no network policy and no resource limit. A command started through exec can read and write anything the user can, reach the network, and use the whole machine.

What the backend does do is narrower, and worth stating exactly so nobody assumes the rest:

  • paths passed to readFile/writeFile/mkdir/exists and to exec's cwd are resolved inside the sandbox directory, and a leading / means the sandbox's root rather than the machine's — so readFile('/etc/passwd') reads the sandbox's copy or nothing at all. That is a path mapping, so that callers written against container-absolute paths keep working; it does not follow symlinks, and it constrains nothing a running command does;
  • the sandbox directory the provider created is the only tree destroy() will remove.

For the desktop case this is acceptable, because the code and the machine belong to the same person. On a server it is not a security boundary, and reaching for it as one is the mistake this section exists to prevent.

What it costs to run a turn

This backend installs nothing, and a turn needs the turn host on the machine itself. The driver execs node /opt/turn-host/bridge.mjs, and exec passes a command's arguments through as written — only cwd and the file operations map a leading / into the sandbox — so the bundle and its Agent SDK have to be installed at that path, as @amond-ai/harness-claude-code-bridge describes for an image. The SDK brings its own claude binary. A command inherits the orchestrator's own environment by default — that is how PATH finds node, and it is one more way this is not a sandbox. Pass env to narrow it.

Where things live

<root>/
  <sandboxId>/                  the working directory, when the provider owns it
  .state/
    <sandboxId>/
      .nonce                    what this sandbox's wrappers are recognised by
      <processId>.out           stdout, as the wrapper redirected it
      <processId>.err           stderr
      <processId>.pid           the command's own pid, for aiming a signal
      <processId>.exit          $?, written by the wrapper after it waits
      <processId>.timeout       present when the wrapper's own watchdog killed the command
      <processId>.meta.json     the process record

The bookkeeping never lives inside the working directory, which is what lets the two be owned separately — and what keeps anything shared between sandboxes (a bootstrap, a package store, a bridge bundle) safe from a destroy(). Nothing removes <root> or <root>/.state.

| Option | Default | What it decides | | --- | --- | --- | | root | (required) | Where the provider puts the sandbox directories it owns. | | stateRoot | <root>/.state | Where the journals and process records go. | | resolveRoot | (unset) | Name the working directory yourself — and keep it; see below. | | env | the orchestrator's own | The environment a command starts with. | | host | the Node builtins | The host primitives, for a runtime that needs its own binding. | | loopbackHost | 127.0.0.1 | The address portEndpoint answers with. |

Ownership, and what destroy() removes

By default a sandbox id resolves to <root>/<id>, the provider created it, and destroy() removes it. Pass resolveRoot when the app already has a workspace layout:

createLocalProvider({ root, resolveRoot: id => workspacePathFor(id) })

The provider then stops owning that directory. destroy() still ends the sandbox's processes and still removes the provider's own state for it, and it does not delete a tree it was merely pointed at. The decision is taken at resolution rather than argued about at deletion, so the dangerous case cannot be reached by getting one line wrong.

Finding a process after the app was quit

A desktop app is killed and relaunched far more casually than a worker is evicted, and the contract requires getProcess/listProcesses to answer about a sandbox this process may never have started. Three things make that work, and each is a decision rather than a detail:

  1. The exit code is written by the shell, not by the parent. A host-side 'exit' listener is the obvious implementation and it is wrong in exactly this case: quit the app mid-turn and nothing is left to observe the exit, so a turn that finished perfectly comes back as SandboxNoExitRecordError. The wrapper records $? from inside the tree.
  2. Liveness is verified, never inferred from the record. Pids are reused, so the pid alone is not an answer. What identifies a process is the wrapper's own marker in its command line — which carries a nonce minted once per sandbox and kept in its state directory, because every other part of that marker is public and destroy() signals the process group of whatever recovery claims; the kernel's start time is the fallback for a host that cannot report one. That ordering is deliberate — ps -o lstart resolves to a whole second on both supported platforms, so a pid recycled inside that second compares equal, and there is no portable finer clock (/proc is Linux-only). A row whose command line is unreadable falls back to the time rather than to a verdict: truncated argv is not evidence of a stranger, and calling a live turn dead is the expensive mistake. macOS ps prints (bash) for a live wrapper whose arguments it momentarily failed to read, so that stand-in counts as unreadable, and recovery reads such a row again before passing over it. A process this check cannot confirm is never signalled. kill reports the non-delivery and leaves the caller's bounded wait to escalate, as SandboxProcessHandle.kill requires.
  3. A process is over when its group is empty, not when the wrapper exited. A command that detaches a child and returns leaves that child writing to the checkout, and a caller told "finished" starts a second one beside it.

A timeout on exec is enforced by the wrapper too, for the same reason as (1): a host-side timer would quietly stop existing the moment the app was quit. It asks with SIGTERM, escalates to SIGKILL after a grace period so a command that ignores the ask cannot outlast its deadline, and — only on a timeout — ends what the command left running in the wrapper's process group. Without that last step the deadline would bound nothing: sh -c 'sleep 300 & wait' answers SIGTERM with exit 143 while its child keeps running, and a process group that is not empty is a process this backend correctly reports as still alive.

The nonce authenticates against coincidence, not against a local attacker: it is in the wrapper's command line, so anything on the machine that can run ps can read it and reproduce it. That is the same bar the rest of this package holds — a command here runs unconfined with the orchestrator's environment — and what it closes is the case that was actually reachable, a process that reproduces the marker without trying to. Delete .nonce and recovery claims nothing at all: an orphan that could once have been ended is lost, which is the cheaper of the two mistakes available at that point. A process that still has its record is not called dead on that evidence either: a row shaped like its own wrapper but carrying the wrong nonce reads as unknown, so destroy() refuses rather than signalling it or deleting the state.

Upgrading from a release without the nonce. Wrappers that an earlier release spawned carry no nonce, so this release does not recognise them. A turn whose record survives the upgrade falls back to its kernel start time where one was pinned, and otherwise reads as unknown. It is neither killed nor cleaned up. A turn whose record is already gone cannot be recovered at all. Let running turns finish, or stop them, before you upgrade.

One limit worth knowing before you rely on recovery: a process found through the process table rather than through its record carries the argv as the process table renders it, and ps escapes a newline in an argument as \012. A multi-line prompt recovered that way is not byte-identical to the one that was spawned. Carrying an encoded copy in the wrapper's own command line would fix it and double the largest thing in that command line, against a 256KB ARG_MAX on macOS — so it is a stated limit rather than a hidden one. It costs nothing in the ordinary case: a process that still has its record is read from the record.

Ports are not per-sandbox

portEndpoint answers http://127.0.0.1:<port> — the port is on the machine that is asking, so there is nothing to look up and no round trip to pay. There is also nothing to isolate: two sandboxes that both bind 3000 collide, and the second fails to bind rather than getting its own 3000 the way a container would. A consumer running concurrent sandboxes has to allocate ports itself.

Unlike the e2b backend, the scheme a caller asks for is the scheme it gets. e2b upgrades http and ws because its ports are reached across the internet through a TLS edge and a plaintext endpoint does not exist there; a loopback port has no edge, so upgrading could only hand back a URL that provably cannot be dialed.

POSIX only

Process groups, signal numbers and ps all mean something specific here, and Windows has no equivalent for any of the three. macOS and Linux are supported; the real-machine suite (src/local.real.test.ts) skips itself elsewhere rather than pretending. The filesystem under stateRoot must support hard links, because .nonce is published with link(2); on one that does not (exFAT, some SMB and FUSE mounts) the first exec fails rather than running without a nonce.

src/node-host.ts is the only shipped module that imports a node: builtin, and it uses specifiers rather than any one engine's API, so it runs on Node, Bun and Deno alike. Everything else in the package is written against the structural LocalHost surface it satisfies — which is what makes pid reuse, a lost record and an orphaned child testable at all, and what closure.test.ts asserts on every run. The real-machine suite is the exception the qualifier is for: src/local.real.test.ts imports node:fs/promises, node:os, node:path and node:process to build the temp directories it drives a real /bin/sh in. It is a test, so closure.test.ts never scans it — the claim above is about what a consumer installs.