Documentation
Backend families
Backends are where Everlock's service logic lives. They should stay transport-agnostic and avoid depending directly on SSH, HTTP, SMTP, or other frontend libraries.
Implemented families
| Backend | What it handles |
|---|---|
backend-git-ssh | Git wire operations over the SSH transport |
backend-git-http | Git wire operations over HTTPS (smart HTTP), plus the repository web UI and workflow runs |
backend-ai-ssh | Embedded AI prompting through the admin SSH session, plus image captioning for backend-image-http |
backend-site-http | Static files and rendered Markdown sites from git-backed stores |
backend-image-http | Image and video storage plus gallery-like HTTP behavior, including an e-paper photo frame endpoint |
backend-admin-ssh / backend-admin-http / backend-admin-mcp | Admin interaction surfaces — thin outlets over the shared everlock-admin-core command engine |
backend-dns-dns | Global authoritative DNS record logic served through frontend-dns |
backend-oci-http | OCI distribution-compatible registry with Everlock auth and store-backed persistence |
backend-mail-smtp | Inbound mail storage, forwarding, and submission-backed delivery rules |
backend-mail-imap | Read/write IMAP access on top of the SMTP backend's mail store, sharing the same versioned storage |
backend-calendar-http | CalDAV calendars with Everlock auth and versioned .ics storage |
backend-contacts-http | CardDAV contacts with Everlock auth and versioned .vcf storage |
backend-oauth-http | OAuth2 / OIDC token issuance with versioned client and key storage |
backend-vault-http | Bitwarden-compatible, end-to-end-encrypted password vault with versioned per-instance storage |
backend-files-http | WebDAV file shares with Everlock auth and one versioned store per share |
backend-dns-http holds the capability trait for a DNS management API; DNS records are managed through the admin console (/dns) today.
Shared resource components
Some resources live in their own component so several backends share one copy — a heavy runtime that should be loaded once, or protocol machinery that would otherwise be written twice:
| Crate | Owned resource | Consumers |
|---|---|---|
everlock-mail-storage | Mail tree layout, IMAP UID allocator, MailEventBus | backend-mail-smtp, backend-mail-imap |
everlock-ai-runtime | Embedded GGUF model + self-developed gguf-runner worker thread | backend-ai-ssh, backend-image-http |
everlock-acme | ACME account + challenge handling | frontend-http |
everlock-dav | WebDAV responses, the lock table, property parsing, and the conformance suite each surface runs against itself | backend-files-http, backend-calendar-http, backend-contacts-http |
everlock-backend-git | Git protocol sessions, pack handling, merges, git.gc, and retention | backend-git-ssh, backend-git-http |
everlock-admin-core | The admin command registry and every command's typed input | backend-admin-ssh, backend-admin-http, backend-admin-mcp |
everlock-markup | Markdown rendering and syntax highlighting | backend-site-http, backend-git-http |
Multi-instance model
Backends differ in whether they can serve multiple independent instances from a single Everlock process, each on its own vhost.
| Backend | Model | Instances managed via |
|---|---|---|
backend-site-http | Multi-instance, multi-vhost | /site create / /site set — applies live |
backend-image-http | Multi-instance, multi-vhost | /image create / /image set — applies live |
backend-oci-http | Multi-instance, multi-vhost | /oci create / /oci set — applies live |
backend-calendar-http | Multi-instance, multi-vhost | /calendar create / /calendar set — applies live |
backend-contacts-http | Multi-instance, multi-vhost | /contacts create / /contacts set — applies live |
backend-vault-http | Multi-instance, multi-vhost | /vault create / /vault set — applies live |
backend-files-http | Multi-share, multi-vhost | /files create / /files set — applies live |
backend-git-ssh | Multi-repo, single backend | /git repo create — repositories within one backend |
backend-git-http | Multi-repo, single backend | serves the same repositories; pins its vhost via the git.http.vhost server setting — applies live |
backend-mail-smtp / backend-mail-imap | Single shared store, multi-domain | /mail domains create — domains within one store |
backend-dns-dns | Global, single instance | /dns zones create — zones within one backend |
Where the table says applies live, the command builds the instance and swaps it in while the process runs, and the answer says so — active immediately. The one path that asks for a restart is a command run while the backend itself is not running: the change is written to config and takes effect when the backend next starts. A .local vhost is announced over mDNS the moment the command returns.
| backend-admin-ssh / backend-admin-http / backend-admin-mcp | Single instance | CLI flags; the HTTP outlets pin their vhost via the admin.http.vhost / admin.mcp.vhost server settings |
| backend-ai-ssh | Single instance | CLI flags only |
Hot-reload means vhost routing updates take effect immediately without restarting Everlock. Backends that require restart do so because their instance initialisation involves async startup work (spawning workers, opening connections) that cannot be done inline in a command handler.
Design rule
A backend should expose domain operations and storage rules. It should not own SSH packet parsing, HTTP routing, or SMTP session handling. Those live in frontends.
For a broader summary, continue with Frontends or Primitives.