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

v0.2.0

Published

A Cloudflare Sandbox backend for @amond-ai/sandbox — the Durable Object @cloudflare/sandbox 1.0 leaves to the application, and a session that maps it onto the contract

Readme

@amond-ai/sandbox-cloudflare

A Cloudflare Sandbox backend for @amond-ai/sandbox, built on @cloudflare/sandbox 1.0.

import { createHarnessSandboxProvider } from '@amond-ai/harness-sandbox'
import { createCloudflareProvider } from '@amond-ai/sandbox-cloudflare'
import { env } from 'cloudflare:workers'

export { HarnessSandbox } from '@amond-ai/sandbox-cloudflare'

const sandboxes = createCloudflareProvider(env.Sandbox)

// The same provider, handed to the AI SDK harness as its sandbox.
const harnessSandbox = createHarnessSandboxProvider({
  sandboxes,
  defaultWorkingDirectory: '/workspace',
  ports: [30_000],
})

env.Sandbox is the Durable Object namespace bound to HarnessSandbox in your wrangler.jsonc.

What the package ships

@cloudflare/sandbox 1.0 no longer ships a Sandbox Durable Object or a client with a process table: the application writes its own Durable Object and drives the container through ctx.container. This package is that Durable Object plus the mapping layer onto the contract, so Cloudflare is now a mapped backend like e2b and Daytona.

| Piece | What it does | | --- | --- | | HarnessSandbox | The Durable Object. Starts the container (images.sandbox, standard-1, Internet on, five-minute inactivity timeout), runs processes with Cloudflare's background-process pattern, serves files through Files, and forwards bridge connections into the container. | | createCloudflareProvider(namespace) | session(id) resolves namespace.getByName(id.toLowerCase()) synchronously and maps the contract onto the object's RPC methods. | | Port endpoint | A localhost URL tagged with SANDBOX_ID_PARAM, built by sandboxRoutedUrl from @amond-ai/harness-transport-cloudflare. The transport sends the upgrade to HarnessSandbox.fetch with the port in SANDBOX_PORT_HEADER, and the object forwards it with getTcpPort. Building the URL does no I/O. |

How the contract maps:

  • Processes. Each process gets /var/lib/processes/<id>/ with pid, stdout.log, stderr.log, exit-code and meta.json. The command runs under setsid, so kill() signals its whole group: SIGTERM by default, or the named signal (kill(2) sends SIGINT). An alarm keeps the container running while any process does.
  • Exit codes. The status is reported as recorded. A signalled command's 128 + n is not decoded into signal, because exit 143 records the same number. timedOut is true only when exec's own timeout ended the process.
  • Discovery. getProcess and listProcesses answer null and [] from a stopped container without starting one. exists starts it. destroy never does.
  • Files. writeFile creates missing parent directories, as 0.x did. A read defaults to utf-8; pass encoding: 'base64' for bytes.

Overriding the defaults

Consumers never construct the Durable Object, so it is configured by subclassing:

import { HarnessSandbox } from '@amond-ai/sandbox-cloudflare'

export class Sandbox extends HarnessSandbox<Env> {
  protected override inactivityTimeoutMs(): number {
    return 30 * 60 * 1000
  }

  protected override async setupContainer(container: Container): Promise<void> {
    // Runs for each new container and after the object restarts; must be safe to repeat.
    // GIT_CREDENTIALS stands for a Fetcher binding your Worker defines; this package has none.
    await container.interceptOutboundHttps('github.com', this.env.GIT_CREDENTIALS)
  }
}

containerOptions() returns the options passed to container.start().

Migrating from @cloudflare/sandbox 0.x

Read Cloudflare's migration guide first. The steps below are what changes for a Worker that used this package on @cloudflare/sandbox 0.x.

  1. Export the new class under the old name. Replace export { Sandbox } from '@cloudflare/sandbox' with export { HarnessSandbox as Sandbox } from '@amond-ai/sandbox-cloudflare'. Keeping the class name keeps the Sandbox binding, its storage, and the class_name: "Sandbox" below.

  2. Change the containers entry for that class:

    {
      "compatibility_date": "2025-11-17",
      "compatibility_flags": ["nodejs_compat"],
      "containers": [
        {
          "class_name": "Sandbox",
          "name": "my-worker-sandbox-v1",
          "scheduling_policy": "durable_object",
          "images": { "sandbox": { "dockerfile": "./Dockerfile" } }
        }
      ]
    }
    • scheduling_policy: "durable_object" lets each object start its own container.
    • Give the container application a name your account has not used. Without one, the deploy fails after the new Worker version is already live.
    • Remove image, instance_type and max_instances; this policy rejects them. The image moves to images.sandbox.
    • Keep nodejs_compat, and use a compatibility date of 2025-11-17 or later.
    • Leave durable_objects and migrations as they are.
  3. Replace the image base. FROM docker.io/cloudflare/sandbox no longer applies. Start from an image with the tools the agent needs, and copy in sandbox-shim, which Files needs:

    FROM node:24-trixie-slim
    # git for the agent; coreutils (dd, head, wc) and util-linux (setsid) for the process scripts.
    RUN apt-get update \
      && apt-get install -y --no-install-recommends ca-certificates git coreutils util-linux \
      && rm -rf /var/lib/apt/lists/*
    COPY --from=docker.io/cloudflare/sandbox:1.0.2 /usr/local/bin/sandbox-shim /usr/local/bin/sandbox-shim
    WORKDIR /workspace
    CMD ["sleep", "infinity"]

    procps is not needed: kill is a shell builtin. Keep the sandbox-shim tag in step with the installed @cloudflare/sandbox. Commands do not see ENV lines, so pass values through exec's env option instead.

  4. Remove 0.x options. SANDBOX_OPTIONS is gone from @amond-ai/harness-transport-cloudflare. Its normalizeId: true is now the lowercasing in openSandbox, and its sleepAfter: '5m' is HarnessSandbox's inactivity timeout. Outbound rules such as Sandbox.outboundByHost move to setupContainer(); see Cloudflare's outbound traffic page.

Before you deploy, know what the switch does:

  • It is one-way. After the deploy that moves the class to scheduling_policy: "durable_object", 0.x code cannot start containers for it, even after wrangler rollback.
  • In place or side by side. Keeping the class name moves every sandbox in one deploy. Commands running in 0.x containers end, and files in them do not carry over: a run that was mid-turn has to start again. For long-lived sandboxes, Cloudflare describes moving side by side under a new class name instead.
  • 0.x support ends on 2026-12-31. Until then it receives bug and security fixes only.

What it does not supply

The contract does not express a credential path for repository access, and neither does this package. On Cloudflare the consuming Worker supplies it out of band, by intercepting the container's egress from a HarnessSandbox subclass (setupContainer() above); see @amond-ai/sandbox.

Upstream

The AI SDK tracks a first-party Cloudflare provider in vercel/ai#17638. Its bridge rule asks for a URL a stock ws client can dial, and a Cloudflare sandbox's private port gives none, so this package backs the bridge adapters only together with @amond-ai/harness-transport-cloudflare. This repository tracks the upstream provider issues in amond-ai/harness#64.

License

Apache-2.0. See LICENSE.