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

serverless-objects

v0.13.7

Published

Run a self-hosted Workers-compatible platform for agents

Readme

serverless-objects

npm License: Apache-2.0

sobjects runs Cloudflare Workers and Durable Objects apps on your own hardware. Deploy an ordinary Wrangler project and it runs on a host you control, with Durable Object state in your own S3-compatible bucket, plus TLS ingress, a local dashboard, engine upgrades and service units. The default runtime is celld 0.6.2, which the CLI downloads and verifies by checksum; sobjects dev --engine native runs the app in Node instead.

Status: pre-alpha (0.13.x). For evaluation and testing, not production. Single host by default (the native engine can share a bucket across named nodes); macOS arm64 or Linux arm64/x64; Node.js 22.23.4+, 24.22.1+ or 26.12.1+. See the compatibility table.

Project home, roadmap and conformance results: github.com/directionally-local/serverless-objects.

Install

npm install --global serverless-objects
sobjects --help

Quick start

In a Wrangler project (wrangler.json or wrangler.jsonc):

sobjects dev . --port 8787     # local development, no bucket needed

To run it as a node, create sobjects.toml next to the project:

[celld]
bucket = "s3://my-bucket/serverless-objects"

Then, with bucket credentials in the environment (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, ...):

sobjects deploy .
sobjects up --detach           # serves on 127.0.0.1:8080
sobjects status
sobjects logs
sobjects down

The project README walks through a complete Durable Object example.

Modules for Worker code

The package also ships two Durable Object modules, imported from your Worker:

  • serverless-objects/hotcell: a Sandbox Durable Object and getSandbox() with the Cloudflare Sandbox SDK 0.x call shape, backed by a Hotcell daemon.
  • serverless-objects/autopilot: Autopilot runs as Durable Objects (RunObject, RunRegistry). serverless-objects/autopilot/cell runs a task with Autopilot in a Hotcell cell (AutopilotCellRun), and serverless-objects/autopilot/native runs it in-process on the native engine (AutopilotNativeRun).
npm install serverless-objects

Commands

| Command | What it does | |---|---| | sobjects dev [project] [celld dev options] | Local development with celld. It doesn't run the ingress. With --engine native, it runs the app in Node instead (native engine). | | sobjects deploy [project] [celld deploy options] | Preflights the Wrangler config, bundles the app and uploads it to the bucket. Running nodes pick up the new version on their next poll. | | sobjects up [--config PATH] [--detach] | Starts celld (or the native engine, with a [native] table) plus the configured ingress and admin API from ./sobjects.toml, in the foreground or in the background. | | sobjects status / logs [--supervisor] [--tail N] / down | Inspect or stop a node started with --detach. down waits for celld to drain and release its lease. | | sobjects supervise [--config PATH] | Runs only the ingress and admin API in the foreground. | | sobjects dashboard [--config PATH] | Prints the admin dashboard URL, which carries the admin token. | | sobjects build [project] [--strict] | Bundles the app and checks every Node.js built-in it imports against Cloudflare's nodejs_compat support. Reports the app as portable or native-only; --strict exits 1 for native-only. | | sobjects upgrade [--engine-version V \| --rollback \| --status] | Installs and selects a pinned celld release. | | sobjects service print\|install [opts] | Generates a systemd or launchd unit for up. | | sobjects --help, --version | Help and version. Every command takes --help; for dev and deploy it shows celld's own options. |

Configuration: sobjects.toml

Unknown keys are rejected, so a typo fails loudly instead of being ignored. A full annotated example lives at sobjects.example.toml.

[celld]
bucket = "s3://my-bucket/prefix"      # required: s3://, gs:// or az://
endpoint = "https://..."              # S3-compatible endpoint (or S3_ENDPOINT)
region = "auto"                       # or AWS_REGION
listen = "127.0.0.1:8080"             # keep on loopback behind the ingress
# internal_listen = "127.0.0.1:8081"  # celld operator API, loopback only

[ingress]
listen = "0.0.0.0:443"
redirect_http = "0.0.0.0:80"          # HTTP→HTTPS redirect; also serves ACME challenges
access_log = "-"                      # "-" for stdout; default is the state directory

[ingress.tls]                         # static certificates...
cert = "/etc/serverless-objects/tls/fullchain.pem"
key = "/etc/serverless-objects/tls/privkey.pem"

# [ingress.acme]                      # ...or ACME HTTP-01, not both
# email = "[email protected]"
# agree_to_terms = true
# directory_url = "https://acme-staging-v02.api.letsencrypt.org/directory"

[[ingress.routes]]
hostname = "agents.example.com"       # exact, *.wildcard or *
# upstream = "http://127.0.0.1:8080"  # defaults to [celld].listen
# tls = { cert = "...", key = "..." } # per-route certificate, chosen by SNI

[admin]
listen = "127.0.0.1:8790"             # loopback-only dashboard and API

Credentials never go in this file. celld reads them from its standard credential chain or the environment. Relative certificate paths resolve from the config file's directory.

Ingress

With an [ingress] table, up starts a TLS-terminating reverse proxy in front of celld. It:

  • routes by exact, *.wildcard or * hostname and answers 421 for anything else;
  • tunnels WebSocket upgrades;
  • replaces client-supplied X-Forwarded-* and CF-Connecting-IP with the real peer address;
  • optionally redirects HTTP to HTTPS with 308;
  • serves /.well-known/sobjects/health, which checks the upstreams at most once a second. Remote clients get only {"status":"ok"} or "degraded" (with 503); loopback clients also see each upstream's address and state;
  • writes JSON access logs without query strings.

Plaintext ingress is allowed only on loopback. When [celld].listen is loopback, up starts celld with --trust-forwarded-headers, so a Worker's request.url has the client's https:// scheme and host, as on Cloudflare.

Static certificates reload on SIGHUP.

ACME HTTP-01 needs:

  • an email and an explicit agree_to_terms = true, which records your agreement to the CA's subscriber terms;
  • redirect_http on port 80, with public DNS and inbound HTTP reaching it;
  • exact hostnames only. Wildcard routes need static certificates.

The default directory is Let's Encrypt production, so test with the staging directory_url first. Keys and certificates are stored under the state directory with mode 0600 files in 0700 directories. Valid certificates are reused at startup and renewed 30 days before expiry. A failed renewal is retried every six hours while the current certificate is still valid. Issuance has been tested against Pebble; public Let's Encrypt issuance and renewal have not been exercised yet.

Dashboard and admin API

An [admin] table makes the supervisor serve a dashboard at / and a JSON API. The dashboard shows node health and load, objects, per-object storage with a key-value browser and read-only SQL console, and eviction. The API listens on loopback only and refuses non-loopback Host headers (DNS rebinding). Mutations require the x-sobjects-request: 1 header.

Loopback is reachable by every local process, including the apps you deploy, so the API also requires an admin token. The supervisor creates it on first start as admin-token in the state directory (a 256-bit random value, mode 0600 in a 0700 directory). Send it as Authorization: Bearer <token>. Only the dashboard's static files, GET /api/v1/health and GET /metrics work without it, for health checks and Prometheus scrapers. To open the dashboard, run sobjects dashboard as the same user and with the same SOBJECTS_STATE_DIR as sobjects up, and open the URL it prints:

sobjects dashboard
# http://127.0.0.1:8790/#token=...

The token travels in the URL fragment, which browsers don't send to the server. The dashboard keeps it in the tab's session storage and removes it from the address bar. Treat the URL like a password. To rotate the token, stop the supervisor, delete admin-token and start it again.

From a script:

curl -H "Authorization: Bearer $(cat "${SOBJECTS_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/serverless-objects}/admin-token")" \
  http://127.0.0.1:8790/api/v1/node

| Endpoint | Returns | |---|---| | GET /api/v1/health | celld listener and operator API health | | GET /api/v1/node | Resident and owned objects, memory, CPU, WebSockets, deployment version, drain state | | GET /api/v1/objects?class=&limit=&after= | Objects, marked resident or not | | GET /api/v1/objects/<Class:id> | SQL tables with row counts, pending alarm, WebSocket count and tags | | GET /api/v1/objects/<Class:id>/kv?prefix=&startAfter=&limit= | Key-value entries (Date, Map, Set, bytes and bigint as tagged JSON) | | POST /api/v1/objects/<Class:id>/sql | Read-only SELECT/WITH/EXPLAIN/PRAGMA, up to 500 rows | | GET /api/v1/objects/<Class:id>/export | JSON download of every KV entry, app table and pending alarm (10,000 each) | | POST /api/v1/objects/<Class:id>/evict | Evicts a resident object | | GET /api/v1/backups?class=&limit=&after= | Superseded LTX epochs eligible for GC (not a full history) | | GET /metrics | Prometheus text: engine gauges and ingress counters |

celld 0.6 has no storage API, so sobjects deploy wraps the app's Durable Object classes in a small inspection hook. Requests carrying x-sobjects-inspect with this host's token are answered by the hook, and everything else reaches the app unchanged. Only the token's SHA-256 goes into the bundle, and the ingress strips the header from client requests. Pass --no-inspector to deploy the app unwrapped. Point-in-time restore isn't available, because celld has no tool to restore an older epoch.

Engine upgrades

Every installable celld version is pinned with a SHA-256 for each release asset; currently 0.6.2 (the default) and 0.6.1. sobjects upgrade downloads and verifies a version, selects it, and records the previous one. --rollback switches back and --status lists versions. A failed download or checksum leaves the current selection in place. Running nodes keep their version until restarted. Set SOBJECTS_CELLD_BIN to use a binary you manage yourself.

Service units

sobjects service print writes a systemd unit (Linux) or launchd plist (macOS) to stdout; --kind overrides the choice. sobjects service install writes it to:

  • ~/.config/systemd/user/, or /etc/systemd/system/ with --system --user NAME
  • ~/Library/LaunchAgents/ on macOS

It refuses to overwrite without --force and prints the enable commands; it doesn't start anything. The unit runs sobjects up in the foreground and restarts it on failure. systemd units read credentials from an optional sobjects.env beside the config. System units get CAP_NET_BIND_SERVICE so the ingress can bind ports 80 and 443.

Wrangler config handling

dev and deploy parse wrangler.json/wrangler.jsonc before calling celld:

  • Unknown top-level keys are rejected.
  • observability and upload_source_maps are removed, with a warning.
  • A declared build.command runs first.
  • If assets.directory is missing in a project that uses @cloudflare/vite-plugin, vite build runs and the generated index.html is located. Ambiguous output fails before celld starts.

deploy fills a missing bucket, endpoint and region from the project's sobjects.toml; explicit flags and environment variables win. celld bundles with esbuild: a project-local copy comes first, then one on PATH, then the copy installed with this package.

Environment variables

| Variable | Purpose | |---|---| | SOBJECTS_STATE_DIR | Detached PIDs, logs and ACME state (default $XDG_STATE_HOME/serverless-objects or ~/.local/state/serverless-objects) | | SOBJECTS_DATA_DIR | Engine installs and the inspector token (default $XDG_DATA_HOME/serverless-objects or ~/.local/share/serverless-objects) | | SOBJECTS_CELLD_BIN | Use this celld binary instead of the pinned download | | SOBJECTS_CONFIG | Default sobjects.toml for up and supervise, and for deploy when the project has none | | CELLD_SHUTDOWN_TOTAL_MS | celld's graceful-shutdown bound; down waits slightly longer |

Security notes

  • Keep celld's listener, its operator listener and the admin API on loopback. Only the ingress should face the network, and it requires TLS to do so. The admin token guards the admin API against other local processes; it is not a reason to expose it.
  • Keep object-store credentials in the environment or credential chain, never in sobjects.toml.
  • Use a bucket dedicated to Serverless Objects.

License

Apache-2.0. Report issues at github.com/directionally-local/serverless-objects/issues.