SilverBullet

Space Manager

6 min read

A single SilverBullet server can host any number of spaces — each with its own URL, access rules, and configuration — managed a web-based management UI called Space Manager.

Setup wizard

When a server boots with an empty data folder it will run in set mode. Setup mode has two steps:

  1. Account creation: creates the first administrator account.
  2. Space creation: creates your first space.

Once finished, the server writes users.json and spaces.json and redirects you to your newly created space. To return to the space manager, simply open the /.spaces URL.

Accounts

Each account has a username, password, admin flag and any number of API tokens.

  • Admins can reach the admin UI and manage spaces, accounts, and tokens. They can also log into every space.
  • Non-admin accounts are ordinary users: they can log into any space they are a member of (see Access).

There is no self-service signup. Admins create accounts. There is no password recovery either, an admin sets a new password from the Users tab. Fancier features like SSO integration etc may be implemented later.

Spaces

Spaces have a name and point to a folder where its content is kept. By default this will be inside the SilverBullet data folder, but you can pick any folder you like.

Bindings

Each space is reachable one of two ways:

  • URL prefix: e.g. /work. A bare / binds a space at the root (allowed once). Prefixes must not overlap (/work and /work/sub can’t coexist, nor can two spaces both bind /).
  • Hostname: e.g. notes.example.com, matched on the Host header of the main listener. Point wildcard DNS or per-host reverse-proxy rules at the server.

Access

Each space controls who can read and write it through two fields:

  • public — when true, no login is required. Anyone who can reach the URL can read and edit the space, so combine it with readOnly for a public wiki, or use it only behind an Authentication Proxy. When false (the default), the space requires a login.
  • members — the accounts allowed to log into a non-public space. Admins are implicitly members of every space and don’t need listing.

Space index

When no space is bound to the server root (/), opening / redirects to /.spaces instead of opening a space. Any account can log in there. Ordinary accounts see public spaces and spaces where they are members; administrators see every space, plus the admin screens covered in Admin UI.

Boot modes

On startup the server inspects the data folder, the --single flag, and legacy SB_* environment variables, then picks its run mode.

Detection rules:

  1. spaces.json present -> multi-space. The folder is a configured multi-space server.
  2. --single command line flag -> single-space. Forces single space mode. silverbullet --single ./new-dir gives you an instant single space, unauthenticated (unless SB_USER is set).
  3. A SB_* variable is set -> single-space. Any of SB_USER, SB_AUTH_TOKEN, SB_READ_ONLY, SB_NAME, SB_INDEX_PAGE, SB_URL_PREFIX, and friends selects single-space mode, so existing deployments keep working untouched.
  4. The folder is non-empty -> single-space. An existing notes folder is served as a single space, exactly as before.
  5. Empty folder, no flags, no legacy env -> setup wizard. A brand-new server — or a server pointed at a folder that hasn’t been created yet — puts up the Setup wizard.

Programmatic setup

You can provision a server without the browser wizard. Both paths run the same logic and refuse to run twice (once users.json exists).

CLI setup subcommand:

silverbullet setup /var/lib/silverbullet \
  --admin admin:s3cretpw \
  --space "Notes" --at / --space-folder spaces/notes
  • --admin user:pass (required) creates the admin account.
  • --space NAME creates a first space (omit to create none).
  • --at is its binding (/ for the root, or a prefix like /notes; default /).
  • --space-folder is where its files live (default spaces/<id>).

HTTP setup API: while a server is in setup mode, POST /.setup/api/complete accepts the same payload the wizard sends:

{
  "adminUsername": "admin",
  "adminPassword": "s3cretpw",
  "space": { "name": "Notes", "prefix": "/", "folder": "" }
}

GET /.setup/api/status reports the server’s absolute data root, which the wizard uses to prepopulate the folder field. On success the server hot-swaps into the multi-space stack, just like the wizard.

Migrating a single-space server to accounts

To convert an existing Single-space mode server (one folder of notes, configured by SB_USER etc.) into an account-managed space:

  1. Stop the server.
  2. Start it pointed at a fresh, empty folder (with none of the legacy SB_* variables set) so it boots into the Setup wizard.
  3. In the wizard, create your admin account. On the space step, tick “Use an existing folder on this server” and point it at your existing notes folder (an absolute path, or one relative to the new server root).
  4. Finish. Your notes are now served as a space, with accounts and the admin UI in front.

Nothing in your old notes folder is modified beyond seeding an index page if one is missing.

Single-space mode

Single-space mode is the “classic” SilverBullet server: one folder, one space, configured entirely by environment variables, with no spaces.json, users.json, nor admin UI. Pick it with --single, or simply by pointing the server at a folder that already has content (or by setting any legacy SB_* variable). See Authentication > Single-space mode for its authentication options and Configuration for the full environment-variable surface. If the target folder doesn’t exist yet, the server creates it and serves an empty space.

Notes and limitations

  • Spaces share one OS process and user. This mode is built for a household or team of trusted spaces, not hostile multi-tenancy.
  • Authentication is shared across the server, while authorization remains per space. Password changes and account deletion revoke that user’s sessions immediately; membership and admin-role changes also take effect on the next request.
  • Because the session is server-wide, so is its policy: SB_REMEMBER_ME_HOURS, SB_LOCKOUT_TIME, and SB_LOCKOUT_LIMIT (see Install/Configuration > Authentication) apply to every space and to the space list itself, and are set as environment variables rather than per space in spaces.json.
  • The runtime API (runtimeApi) uses a single, server-wide headless Chrome with one page (tab) per enabled space. Both levels are lazy: the browser only starts on the first runtime request from any space, and a space only gets a tab on its own first request. It is on by default, but only actually runs when the server found a Chrome or Chromium install at startup — if it did not, the Space Manager says so and the per-space checkbox is locked. Set SB_CHROME_PATH to point at a browser in a non-standard location, or SB_RUNTIME_API=0 to turn the whole surface off server-wide.

Graph View

Backlinks