Install Serverless Objects

Serverless Objects is pre-alpha. Install it for evaluation and testing, not for production.

#Requirements

#Install from npm

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

Download the annotated example config:

curl -fsSL -o sobjects.toml https://raw.githubusercontent.com/directionally-local/serverless-objects/main/sobjects.example.toml

If you only need the Worker modules (serverless-objects/hotcell, serverless-objects/autopilot), install the package into your project instead:

npm install serverless-objects

#Install from source

git clone https://github.com/directionally-local/serverless-objects.git
cd serverless-objects
npm ci
cp sobjects.example.toml sobjects.toml

From a checkout, run the CLI as npm exec --workspace=serverless-objects -- sobjects in place of sobjects.

#Configure the bucket

Edit sobjects.toml and replace the example bucket URI with one you control. For an S3-compatible provider, set endpoint and region if it needs them.

[celld]
bucket = "s3://my-bucket/serverless-objects"
listen = "127.0.0.1:8080"
# endpoint = "https://<account>.r2.cloudflarestorage.com"
# region = "auto"

Keep credentials out of the file. celld reads the standard environment and credential chain:

export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...

#First start

sobjects up

The first start downloads the pinned celld release and verifies its checksum. The default celld listener is 127.0.0.1:8080. Keep it on loopback: celld's HTTP and operator listeners are unauthenticated. To serve traffic from the network, add TLS ingress as described in running as a service.

#Run with Docker Compose

deploy/compose runs a single node in Docker. The image installs the CLI from npm and bakes in the checksum-verified celld.

• celld, its operator API and the admin dashboard listen on loopback inside the container. Only the TLS ingress is published, on ports 443 and 80.
• Processes run as the unprivileged sobjects user (uid 999).
• The sobjects-data volume keeps local service state: tokens, ACME account and certificates, and logs. Durable Object state lives in your bucket.
• The local-s3 profile adds a SeaweedFS server and a bucket for trying it on one machine.

cd deploy/compose
cp .env.example .env                    # set a long random AWS_SECRET_ACCESS_KEY
cp sobjects.toml.example sobjects.toml
mkdir -p tls apps
# put a certificate in tls/fullchain.pem and tls/privkey.pem (see the compose README)
docker compose --profile local-s3 up -d --build

Deploy a Wrangler project from inside the container:

cp -R /path/to/my-worker apps/my-worker
docker compose exec sobjects sobjects deploy /apps/my-worker
curl -k https://localhost/

The image targets linux/arm64 and linux/amd64. The full stack has been tested on arm64. See the compose README for certificates, key permissions and production settings.

#Where files go

#Operational limits

• Use a bucket dedicated to the service. Don't point test commands at a bucket with unrelated data.
• Single-node writes wait on the object store. One R2 smoke run from a Mac measured about 0.63 to 0.78 seconds per request. That is one environment's observation, not a latency figure to plan on.
• celld 0.6 has no supported point-in-time restore command.

#Next steps

• Quick start
• Running as a service