Getting started

Lockwell is an object store you host yourself. Your app talks to it through one SDK: files in, files out, per-customer isolation built in.

This page gets you to a working result: run the server, store a file, read it back, and let a browser upload directly. Concepts can wait; when a term is new, Concepts in plain words defines it in a sentence.

1. Run LockwellCopy Anchor Link

One container, one volume, no external database.

git clone https://github.com/RusticStack/lockwell-deploy.git
cd lockwell-deploy
cp .env.example .env
docker compose up -d --build

Before up, open .env and replace the two CHANGE_ME values with long random strings. They become your first access key, and the container refuses to start while the placeholders are still in place.

Check it is alive:

curl -fsS http://localhost:9000/health

You now have two listeners and one credential:

• http://localhost:9000: the public listener (object I/O)
• http://localhost:9001: the admin listener (management, kept private)
• the access key from .env, already bootstrapped with full data access

Already running Lockwell somewhere? Skip ahead and use your own endpoint and key.

2. Install the SDKCopy Anchor Link

npm i @kelphect/sdk

Registries, prerequisites, and client options live on the Installation page.

This quickstart intentionally uses the HTTP-native JSON client. LNW/1 is an experimental, opt-in binary transport on a separate TLS 1.3 listener; use the Native Wire guide and its server-only SDK guides after the listener and runtime have passed their qualification gates.

3. Store a file and read it backCopy Anchor Link

Point the native client at the public listener with the key from .env. It mints and refreshes its own short-lived token; you never touch auth plumbing.

import { NativeClient } from "@kelphect/sdk";

const native = new NativeClient({
  endpoint: "http://localhost:9000",
  accessKeyId: process.env.LOCKWELL_ROOT_ACCESS_KEY_ID,
  secretKey: process.env.LOCKWELL_ROOT_SECRET_KEY,
});

await native.createBucket("inbox");
await native.putObject("inbox", "hello.txt", "hi there", { contentType: "text/plain" });

const got = await native.getObject("inbox", "hello.txt");
console.log(got.body.toString()); // "hi there"

That is a private, encrypted object store taking writes. Streaming, ranges, listing, versions, and the rest of the object API start at Upload & download.

4. Let the browser upload directlyCopy Anchor Link

Sign a short-lived PUT URL on your server and hand only the URL to the browser. The file bytes go straight to Lockwell, and your key never leaves the server.

// Server-side: the signed URL comes back as a path; join it to the endpoint.
const signed = await native.signUrl({
  method: "PUT",
  bucket: "inbox",
  key: "photo.jpg",
  ttlSeconds: 300,
});
const url = new URL(signed.url, "http://localhost:9000").toString();

// Browser-side:
await fetch(url, { method: "PUT", body: file });

The URL is bound to one method and one object, expires on its TTL, and can never exceed the signing key's scope. The full flow, including the download direction, is on Signed URLs.

That's itCopy Anchor Link

You ran the server, stored a file, read it back, and took a browser upload. One SDK, no second store, no glue code.

Going multi-tenantCopy Anchor Link

The quickstart used the bootstrap root key. For a real app you give each customer their own tenant and a key scoped to it, so customers are isolated by the credential itself.

That is the job of the admin API and the app kit (provisionTenant, clientForTenant). The admin API needs an admin token, which is minted offline because the CLI and the daemon cannot hold the embedded store at the same time:

docker compose stop lockwell
docker compose run --rm lockwell lockwell admin-token create --name my-app --role owner
docker compose start lockwell
# prints an lwadm_... token exactly once. Store it as LOCKWELL_ADMIN_TOKEN.

Then follow The app kit for the provision-and-go flow, and Tenancy & auth for the model behind it.

Next stepsCopy Anchor Link

• Installation. Per-language registries, client options, and retry setup.
• Upload & download. The full object API.
• The app kit. Multi-tenant provisioning with near-zero glue.
• Signed URLs and Webhooks. Browser-direct I/O and events.
• The three surfaces. How S3, native, and admin fit together.
• Native Wire (LNW/1). Binary transport setup, limits, retries, and rollback.
• Deployment. TLS, the master key, backups, and production posture.