Admin over SSH and CLI

The SSH admin surface is the implemented Everlock control plane today.

It is provided by:

frontend-ssh
backend-admin-ssh

This is a line-based admin REPL, not a shell. Commands begin with / and act on Everlock resources such as users, groups, backends, sites, OCI registries, DNS zones and records, and mail domains.

When backend-ai-ssh is enabled, the same session also accepts free-text AI prompts:

/... remains command input
plain text becomes AI prompt input
//... sends a slash-prefixed prompt to the model

Session model

Typical flow:

start Everlock with frontend-ssh and backend-admin-ssh
connect with ssh
authenticate as an Everlock user
use slash commands inside the admin session

The session accepts:

/help
resource commands such as /users ..., /site ..., /oci ...
/quit or /exit

A connection has two minutes to log in, or it is closed. Once logged in, an idle session stays connected for 24 hours, and survives the laptop going to sleep in between: the server sends nothing to a quiet client, so there is nothing a sleeping machine could fail to answer. If your router or firewall drops idle connections, let the client send keepalives while it is awake:

Host everlock
  HostName <server>
  Port 2222
  ServerAliveInterval 30

Access model

Three command tiers exist:

any authenticated user, answered with what that user holds a grant on:
- /help
- /users list — your own row
- /users grants <login> — your own login
- /groups list — the groups you belong to
- /git repo list — repositories you can read
- /site list, /calendar list, /contacts list, /files list, /vault list, /image list, /oci list — instances you hold any grant on, wildcard grants such as */*/photos included
- /dns zones list
- /dns records list [<zone>]
access-path governed commands:
- /dns ... uses ssh/dns/* and ssh/dns/<zone>; without the grant the answer is "access denied", whether or not the zone exists
system administrators only:
- backend enable/disable
- user and group changes
- site, OCI, and mail configuration changes
- /oauth client list and every other OAuth command

System administrator here means Owner on */*/*, and a system administrator sees every user, group, and instance in the listings above.

User, group, credential, and grant changes are saved before they take effect: when the store refuses the write, the command reports the error and nothing changes.

Command layout

The command families are:

/help
/users
/groups
/git
/dns
/site
/calendar
/contacts
/files
/oci
/mail
/jobs
/backends
/quit
/exit

Bare scope commands show scope help where implemented:

/site
/calendar
/contacts
/files
/oci
/mail
/git
/dns

Command reference

Help and session

/help
/quit
/exit

Users

/users list
/users create <login> <password>
/users password <login> <password>
/users grant <login> <path> <role>
/users revoke <login> <path>
/users grants <login>
/users delete <login>
/users reload
/users ssh-keys list <login>
/users ssh-keys create <login> "<openssh-public-key>"
/users ssh-keys delete <login> <fingerprint>
/users apikey create <login> [alias]
/users apikey list <login>
/users apikey revoke <login> <key-id>

Notes:

<role> is one of reader, writer, or owner
<path> is an Everlock access path such as http/site/docs or http/oci/default
/users delete drops the user's grants, group memberships and credentials with them
/users reload re-reads users, groups and grants from the system store, for when they were changed by a push rather than a command
/users apikey create prints the key once; see credential types

Groups

/groups list
/groups create <name>
/groups assign <group> <login>
/groups grant <group> <path> <role>
/groups revoke <group> <path>
/groups unassign <group> <login>
/groups delete <name>

Git

/git repo list
/git repo create <name>
/git repo size <name> [retention=<90d>]
/git repo set <name> retention=<90d>
/git repo unset <name> retention
/git branch list <repo>
/git branch delete <repo> <branch>
/git pr list <repo>
/git pr open <repo> <slug> <target> <branch-or-oid>
/git pr merge <repo> <slug> <target>
/git pr close <repo> <slug> <target>
/git workflow list [repo]
/git workflow log <repo> last|<run> [job]
/git workflow start <repo> <workflow> [ref] [key=value ...]
/git secret set <repo> <name> <value>
/git var set <repo> <name> <value>
/git var list <repo>
/git var remove <repo> <name>
/git runner token
/git runner list
/git runner remove <name-or-uuid>

Notes:

the repository-scoped verbs resolve that repository's grant themselves: reader reads a run and its log, writer starts one, owner sets secrets and variables
registering a runner is instance administration and takes a system administrator
/git secret set values are masked in job logs; /git var list shows both kinds and prints — where a secret's value would be
see Workflows

DNS

/dns
/dns zones list
/dns zones create <zone>
/dns zones delete <zone>
/dns records list
/dns records list <zone>
/dns records create <zone> name=<name> type=<type> value=<value> [ttl=<ttl>]
/dns records set <zone> <name> <type> value=<value> [ttl=<ttl>]
/dns records delete <zone> <name> <type>
/dns reload
/dns info
/dns ip refresh
/dns ip set v4|v6 <addr>
/dns peer keygen
/dns peer list <zone>
/dns peer create <zone> name=<name> address=<addr>[,<addr>...] secret=<b64> [algorithm=hmac-sha256]
/dns peer set <zone> name=<name> address=<addr>[,<addr>...] secret=<b64> [algorithm=hmac-sha256]
/dns peer delete <zone> <name>

Notes:

/dns zones create <zone> requires Owner on ssh/dns/*
zone inspection uses Reader on ssh/dns/<zone>
zone mutation uses Writer on ssh/dns/<zone>
zone deletion uses Owner on ssh/dns/<zone>
/dns records list shows effective records and whether they are derived, explicit, or explicit-override
/dns info reports the backend's address mode and the addresses it is publishing
/dns ip refresh runs an out-of-band public-IP probe, and applies only in discover mode; /dns ip set pushes an address by hand, and applies only in manual mode — see address modes. Both require Owner on ssh/dns/*, as the address is the one every zone publishes
the /dns peer family configures TSIG-authenticated zone transfer to secondaries; keygen mints a shared secret to hand to the peer. /dns peer list uses Reader on ssh/dns/<zone>, and managing a peer Owner on it

Sites

/site
/site list
/site create <name> [store=<name>] [mode=html|markdown] [auth=public|private] [vhost=<host>]
/site set <name> auth=public|private
/site set <name> mode=html|markdown
/site set <name> vhost=<host>
/site unset <name> vhost=<host>
/site delete <name>
/site log enable <name>
/site log disable <name>
/site log set <name> flush_interval=<dur> | flush_max_bytes=<n> | flush_max_entries=<n> | buffer_hard_cap=<n> | channel_capacity=<n>
/site log status <name>
/site log tail <name> [count]

Notes:

store= defaults to the site name
mode= defaults to the backend default if omitted at creation time
auth=public grants Reader to anon on http/site/<name>
auth=private revokes that anon grant
multiple vhost= values can be added over time by repeated set
the /site log family drives the per-site access log

OCI

/oci
/oci list
/oci create <name> [store=<name>] vhost=<host> [vhost=<host>...]
/oci set <name> store=<name>
/oci set <name> vhost=<host> [vhost=<host>...]
/oci unset <name> vhost=<host> [vhost=<host>...]
/oci delete <name>

Notes:

vhost= is required at creation time
store= defaults to the registry name if omitted at creation time

Calendar

/calendar
/calendar list
/calendar create <name> [store=<name>] vhost=<host> [vhost=<host>...]
/calendar set <name> store=<name>
/calendar set <name> vhost=<host> [vhost=<host>...]
/calendar unset <name> vhost=<host> [vhost=<host>...]
/calendar delete <name>

Notes:

vhost= is required at creation time
store= defaults to the instance name if omitted at creation time
calendars and events inside the instance are managed through CalDAV, not the admin shell

Files

/files
/files list
/files create <name> [store=<name>] vhost=<host> [vhost=<host>...] [mount=<path>]
/files set <name> store=<name>
/files set <name> vhost=<host> [vhost=<host>...]
/files set <name> mount=<path>
/files unset <name> vhost=<host> [vhost=<host>...]
/files unset <name> mount
/files delete <name>

Notes:

vhost= is required at creation time
store= defaults to the share name if omitted at creation time
mount= defaults to /dav
the creator is granted Owner on http/files/<name>; other users need a grant
files and collections inside the share are managed over WebDAV, not the admin shell

Contacts

/contacts
/contacts list
/contacts create <name> [store=<name>] vhost=<host> [vhost=<host>...]
/contacts set <name> store=<name>
/contacts set <name> vhost=<host> [vhost=<host>...]
/contacts unset <name> vhost=<host> [vhost=<host>...]
/contacts delete <name>

Notes:

vhost= is required at creation time
store= defaults to the instance name if omitted at creation time

Mail

/mail
/mail domains list
/mail domains list <domain>
/mail domains create <domain> [submission=on|off] [auth=on|off] [dkim=on|off] [hostname=<name>]
/mail domains set <domain> <key=value>...
/mail domains delete <domain>
/mail mailboxes list
/mail mailboxes list <domain>
/mail mailboxes list <domain> <mailbox>
/mail mailboxes delete <domain> <mailbox>
/mail rules list
/mail rules show <id>
/mail rules create <id> direction=inbound|outbound type=<action> [priority=<n>] [match=<inline TOML>]
/mail rules delete <id>

Currently documented mail domain settings:

submission=on|off
auth=on|off
dkim=on|off
hostname=<name>

Creation supports the same keys as set, so you can create a domain with its intended submission and DKIM settings in one command.

submission=on also enables the SMTP submission listener (default port 587): the setting is persisted in the frontend config and the listener binds in the running process, staying enabled across restarts.

TLS visibility:

/mail domains list includes the derived SMTP host plus TLS status and expiry summary
/mail domains list <domain> shows the derived mail.<domain> hostname, certificate source and status, expiry and renewal timestamps, and the last ACME error when present

Image

/image
/image list
/image create <name> [store=<n>] [vhost=<host>] [instance_name=<label>] [public_url=<url>] [languages=<en,de>] [job_cooldown=<seconds>] [job_schedule=<job>:<schedule>]
/image set <name> vhost=<host> | instance_name=<label> | public_url=<url> | languages=<en,de> | job_cooldown=<seconds> | job_schedule=<job>:<schedule>
/image unset <name> vhost=<host> | public_url | instance_name | languages | job_cooldown | job_schedule=<job>
/image delete <name>

Notes:

every one of these applies while the process runs — see when a change takes effect
/image delete removes the instance; its store and the images in it are kept
photos, albums and sharing are managed through the gallery or an Immich-compatible client, not the admin shell

Vault

/vault
/vault list
/vault create <name> [store=<name>] vhost=<host> [vhost=<host>...] [open_signups=on|off]
/vault set <name> store=<name> | vhost=<host> [vhost=<host>...] | open_signups=on|off
/vault unset <name> vhost=<host> [vhost=<host>...]
/vault delete <name>
/vault accounts list <instance>
/vault accounts delete <instance> <email>

Notes:

the vhost is load-bearing: it becomes the instance's token issuer and the base of the URLs clients build for attachments
open_signups=off is the default, which leaves registration invite-gated
/vault create grants its caller owner on http/vault/<name>, and account administration takes that grant — see the vault access model
vault items are client-encrypted, so nothing here can read them

OAuth

/oauth
/oauth client list
/oauth client create <id> name=<name> redirect-uri=<uri> [redirect-uri=<uri>...] [scope=<s>...]
/oauth client show <id>
/oauth client rotate-secret <id>
/oauth client delete <id>

Notes:

create and rotate-secret print the client secret once; it is stored hashed
redirect-uri= is repeatable, and only a listed URI is ever redirected to
scopes default to openid profile email
see Registering OAuth clients

Jobs

/jobs
/jobs list
/jobs run <kind>
/jobs show <id>

Backends

/backends
/backends list
/backends enable <name> [<name>...]
/backends disable <name> [<name>...]

Common backend names include:

ai-ssh
git-ssh
image-http
dns-dns
admin-ssh
admin-http
site-http
mail-smtp
calendar-http
contacts-http
oci-http
oauth-http
git-http
admin-mcp
files-http
vault-http
mail-imap

Enabling or disabling a backend restarts Everlock. The create commands of the domains a backend serves — /site, /image, /calendar, /contacts, /files, /vault, /oci — need that backend enabled: on a disabled one they save nothing and answer with the /backends enable command to run first.

Server

/server
/server info
/server restart
/server log [count=N] [since=T] [until=T] [grep=TEXT] [level=L] [target=MOD]
/server settings list
/server settings get <key>
/server settings set <key> <value>
/server settings unset <key>

Notes:

every /server command requires system admin
/server info reports the running binary's version, commit, model variant and platform
/server restart takes the same path a restart-class config change takes: flag, drain, re-exec — or a clean exit for a socket-activation supervisor to bring the process back
/server log reads the in-memory ring, nothing persisted. since=/until= take a relative 15m, 2h, 1d or an RFC 3339 timestamp; grep= is case-insensitive; level= is a floor and target= a module prefix. Each report leads with how much of the buffer it covers. The ring holds log.buffer_lines lines, 2000 by default
every key /server settings accepts is listed in the settings reference, with whether it applies live or at the next restart

Argument styles

Two argument styles are used.

Positional arguments

Examples:

/users create alice secret123
/users grant alice http/site/docs reader
/groups assign editors alice
/git create project-docs

`key=value` arguments

Examples:

/site create docs vhost=docs.example.com auth=private
/site set docs vhost=docs.internal.example.com
/oci create main vhost=registry.example.com store=everlock-oci-main
/mail domains set example.com submission=on auth=on

Behavior notes

site and oci changes persist to config files and may require a restart depending on the operation
mail configuration is persisted in the system store and mail-store metadata
backend enable/disable changes persist config and trigger restart behavior
the SSH admin surface is the main documented operator workflow

Admin over SSH and CLI

Session model

Access model

Command layout

Command reference

Help and session

Users

Groups

Git

DNS

Sites

OCI

Calendar

Files

Contacts

Mail

Image

Vault

OAuth

Jobs

Backends

Server

Argument styles

Positional arguments

key=value arguments

Behavior notes

`key=value` arguments