Self-host quickstart

Run Nimbus as a server and talk to it over plain HTTP. No codegen, no schema files, no Node.js — curl is enough.

1. Install Nimbus

brew trust --cask nimbus/tap/nimbus
brew install --cask nimbus/tap/nimbus

Other platforms ship via the install script and release binaries — see the install options.

2. Start the server

nimbus start --port 8080 --data-dir ./data

The server binds to localhost by default and persists to ./data with the embedded SQLite backend.

3. Grab the admin token

The native API is protected by a local admin token, created on first boot and stored as a JSON file:

# Linux
export NIMBUS_TOKEN=$(jq -r .token ~/.local/share/nimbus/auth/token)

# macOS
export NIMBUS_TOKEN=$(jq -r .token "$HOME/Library/Application Support/nimbus/auth/token")

On Windows the file is %LOCALAPPDATA%\nimbus\auth\token.json. Requests without the token get a 401.

4. Create a tenant

curl -s -X POST http://localhost:8080/api/tenants \
  -H "Authorization: Bearer $NIMBUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "demo"}'

5. Insert a document

curl -s -X POST http://localhost:8080/api/tenants/demo/documents \
  -H "Authorization: Bearer $NIMBUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"table": "messages", "fields": {"text": "hello world", "author": "you"}}'

6. Query it back

curl -s -X POST http://localhost:8080/api/tenants/demo/query \
  -H "Authorization: Bearer $NIMBUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"table": "messages", "filters": []}'

nimbus start runs the same engine as nimbus dev without codegen. The native HTTP/WebSocket API is the front door here, and the protocol adapters are served alongside it by default — the Firestore-compatible routes on this same listener, the MongoDB endpoint on 127.0.0.1:27017, the DynamoDB endpoint on 127.0.0.1:8000, and the S3-compatible endpoint on 127.0.0.1:9000 (--no-firestore, --no-mongodb, --no-dynamodb, and --no-s3 switch them off). See the per-adapter guides under Developers and the full list in configuration.

Next steps

• Native API guide — tenants, documents, queries, and live subscriptions over WebSocket, from any language.
• Operators — production deployment, tenants, storage backends (Postgres, MySQL, libSQL, redb), encryption at rest, networking, and observability.
• Reference — every nimbus start flag and the native HTTP/WebSocket API.