Zilobase

Notes, pages, databases, comments, and AI workflows in one open-source workspace.

Website | App | Docs | Self-host | Contribute | Security

---

Zilobase is an open-source workspace for building and organizing knowledge with structured pages, database views, comments, and AI-assisted workflows. It is designed to run as a hosted product or as a self-hosted Docker deployment.

What You Can Do

• Write and organize pages with a rich editor, nested navigation, comments, and workspace context.
• Model structured information with standalone or embedded databases, table views, kanban views, timeline views, properties, filters, sorting, and grouping.
• Work with AI in context using page-aware chat, workspace tools, and supported page/database edit flows.
• Run it yourself with Docker Compose, Caddy, Postgres, and RustFS.

Quick Start

Run the self-hosted stack locally:

npm run selfhost:up

The command generates ignored development secrets, builds the production image from source, waits for Postgres and object-storage readiness, and prints these local-only addresses:

Zilobase: http://127.0.0.1:8787
Setup:    http://127.0.0.1:8787/setup
Mailpit:  http://127.0.0.1:8025

Each installation creates one stable database-backed instance identity. Its desktop compatibility and authorization metadata is available at http://127.0.0.1:8787/.well-known/zilobase. Use /health for process liveness and /ready when an orchestrator must wait for both Postgres and object storage. Open http://127.0.0.1:8787/desktop for a copyable server URL and a secret-free Open in Zilobase Desktop connection link.

Before anyone can sign in, open the printed setup URL and paste the token from the ignored .env.selfhost.development file. The page sends it only in a request header; it is not saved in browser storage or placed in a URL. Bootstrap creates the initial verified owner and pinned workspace atomically. Repeated or concurrent requests are rejected and discovery never returns the token.

Registration defaults to Invite only after bootstrap. The instance owner can switch between Invite only and Open registration under Settings → Team → Server registration. Open registration adds a user to the pinned workspace only after email verification. Invite-only registration accepts only a pending, unexpired invitation for that workspace and email address.

For production self-hosting, copy the example, replace every value, and use a released image tag or digest. The production topology never builds application source and rejects missing settings during Compose interpolation:

cp .env.selfhost.example .env.selfhost
docker compose --env-file .env.selfhost -f docker-compose.yml -f docker-compose.prod.yml config
docker compose --env-file .env.selfhost -f docker-compose.yml -f docker-compose.prod.yml up -d --wait

Ask AI

Ask AI is available as a full page, docked sidebar, and floating panel. Mention pages or databases with @; the read-only agent fetches saved content through authorized tools and follows links discovered in those sources. Reads paginate with explicit coverage and citations. Durable mode supports reload recovery and Continue reading. See server configuration.

Development

Prerequisites:

• Node.js 24
• npm 11
• Docker

Install dependencies:

npm install

Local server and web commands load the root .env.development file through dotenvx. Encrypted env files are safe to commit; .env.keys is gitignored and must stay private. Production and Docker self-hosting continue to use their own environment files and do not read .env.keys. Re-encrypt after editing with npm run env:encrypt. Never commit .env.keys or plaintext .env files.

Common commands:

Command	Purpose
npm run setup	Run local bootstrap: install workspace dependencies, create local development files, and pull dependency images.
npm run setup:check	Check prerequisites and optional tooling without running bootstrap steps.
npm run dev:doctor	Validate source and optional Kubernetes tooling.
npm run dev:setup	Create missing private development files without overwriting.
npm run dev	Run the local Node profile, detected sibling development providers, and the loopback development hub.
npm run db:studio	Open Drizzle Studio for the local development database.
npm run dev:status	Inspect dependency and runtime health.
npm run build	Type-check and build the web client and server.
npm run test:web	Run web tests.
npm run build:desktop	Build the Electron desktop app.
npm run build:clipper	Build the browser clipper.
npm run dev:desktop	Start the same local workspace as dev, then open Electron. Do not combine with dev.
npm run selfhost:up	Build and start the loopback-only Compose stack.
npm run selfhost:logs	Follow development stack logs.
npm run selfhost:down	Stop containers and preserve data volumes.
npm run selfhost:reset	Explicitly delete local self-hosted data volumes.
npm run test:selfhost	Run the isolated end-to-end Compose smoke test.
npm run env:encrypt	Encrypt local runtime env files at rest.

npm run dev:desktop opens Electron on the local Cloudflare web app at http://localhost:1422. Zilobase Cloud in that session is the local Cloudflare runtime at http://localhost:3010. Choose custom server lists self-hosted Community at http://localhost:3000 and the other local server runtimes started with the workspace. Packaged releases default to Zilobase Cloud at https://api.zilobase.com. On the server screen, choose Zilobase Cloud or enter a hosted URL, or use a server's zilobase://connect link. Server metadata is stored in the operating system application-config directory; session credentials remain in the system keyring and are scoped to the saved instance. Custom servers require trusted HTTPS, except for loopback HTTP during local development. Signed-out desktop only offers Continue in Browser and Change server. Login and signup happen in the system browser against the selected server, using PKCE with an ephemeral loopback callback. After continue, the browser stays on the hosted connected page and remains signed in. The desktop receives an independent server session only after issuer, state, instance, and PKCE validation. Signing out the browser does not sign out desktop, and the reverse is also true.

Only one server and account are retained. Settings → Preferences → Desktop server starts the same replacement workflow. If offline drafts exist, the app requires an explicit Sync, Export, Discard, or Cancel choice. A completed change best-effort revokes the old session and removes the old keyring credentials, query cache, IndexedDB/Yjs documents, app/auth stores, tabs, and session storage before reloading. Instance-scoped zilobase://open links are accepted only when both the server origin and instance identity match verified metadata; link query values are never written to diagnostics.

Project Structure

zilobase/
|-- apps/
|   |-- web       # Vite React web client
|   |-- server    # Hono API, auth, persistence, AI, and realtime
|   `-- desktop   # Electron desktop shell
|-- packages/
|   |-- features  # Shared client feature hooks and cache logic
|   |-- page-context
|   `-- markdown-text-splitter
|-- docker/
`-- docker-compose.yml

Deployment Model

The public self-hosted deployment uses Docker Compose with:

• Caddy for HTTP/HTTPS
• Zilobase for the web client and API
• PostgreSQL 17 with pgvector for relational data and optional semantic search
• RustFS for S3-compatible image storage

The open-source server exports edition-neutral runtime extension surfaces from @zilobase/server/adapter-api. This repository documents and supports the public self-hosted deployment only.

Gemini search is disabled by default and requires workspace opt-in. See the search deployment guide and release runbook for configuration, supported text/property coverage, indexing controls and operating limits.

Community

Need	Where to go
Report a bug	Open a bug report
Request a feature	Open a feature request
Contribute code	Read CONTRIBUTING.md
Report a vulnerability	Read SECURITY.md
Understand governance	Read GOVERNANCE.md

License

Zilobase is released under the MIT License.