Deploy the control plane.

Quick start

Lillith is a single Rust workspace: a shared protocol crate, the lillithd server, and the Windows agent. The server embeds the web UI, so there are no separate static files to copy.

1. Build the workspace

# check and test everything
make check
make test

# release builds
make server
make agent-windows

# or invoke cargo directly
cargo build --release --workspace
cargo build --release -p lillith-agent --target x86_64-pc-windows-gnu

2. Deploy to the server

./deploy/deploy.sh user@server

# or, after building:
./deploy/deploy.sh user@server --skip-build

The script installs:

• /opt/lillith/lillithd — the server binary
• /opt/lillith/lillith-agent.exe — served at /download/agent
• /etc/lillith/lillith.env — created once; later deploys leave it alone
• /var/lib/lillith/{lillith.db,packages,screenshots,acme}
• /var/log/lillith, plus a hardened lillithd.service

3. Create the first admin

sudo -u lillith env LILLITH_DB=sqlite:///var/lib/lillith/lillith.db \
  /opt/lillith/lillithd user add --username admin

# optional read-only account
sudo -u lillith env LILLITH_DB=sqlite:///var/lib/lillith/lillith.db \
  /opt/lillith/lillithd user add --username viewer --role viewer

The service listens on 127.0.0.1:8443 by default. Change LILLITH_LISTEN in /etc/lillith/lillith.env for remote access. Once a certificate is issued, HTTPS listens on 0.0.0.0:443.

Requirements

• Rust 1.90 or newer, plus a C linker.
• The x86_64-pc-windows-gnu target and mingw-w64 to build the Windows agent.
• A Linux host for lillithd (systemd unit included).
• Windows clients that can reach the server over the LAN or VPN. They dial out; nothing listens inbound.
• Optional: a Cloudflare-managed domain for built-in ACME / Let's Encrypt certificates.
• Optional: a Microsoft Entra ID app registration for OIDC sign-in.

The server is designed for tens to a few hundred machines. SQLite is the only database requirement.

Server install

deploy/deploy.sh builds and copies the server and agent, writes the environment file if absent, creates data directories, and installs a hardened systemd unit. The unit runs as a dedicated user with ProtectSystem=strict, PrivateTmp, NoNewPrivileges, and ambient CAP_NET_BIND_SERVICE so it can bind port 443.

Edit /etc/lillith/lillith.env, then restart the service:

sudo systemctl restart lillithd
sudo systemctl status lillithd
sudo journalctl -u lillithd -f

HTTPS and ACME

Configure ACME under Settings: domain, contact email, staging or production, and a Cloudflare API token with Zone → DNS → Edit on the relevant zone. Test credentials writes a temporary TXT record to verify access. Certificates renew when older than 60 days, checked every 12 hours, and the HTTPS listener reloads.

• Once TLS is active, plain HTTP browser traffic is permanently redirected to HTTPS.
• /api/*, /agent/*, /download/*, and /healthz stay available over HTTP for agent bootstrap and updates.
• HSTS is sent on HTTPS responses, and session cookies become Secure automatically.
• Certificate and key PEMs can be downloaded for a reverse proxy; the key is admin-only.

Accounts & sign-in

Local accounts store Argon2id password hashes. Two roles exist: admin can change the fleet and manage users; viewer can browse every page while every mutating request is rejected with 403 Forbidden — except saving their own UI preferences.

Microsoft 365 sign-in uses OpenID Connect authorization-code + PKCE. The Lillith.Admin app role maps to admin; every other assigned user is provisioned as a viewer. Set the four required variables and restart:

LILLITH_OIDC_TENANT_ID=<tenant-id>
LILLITH_OIDC_CLIENT_ID=<client-id>
LILLITH_OIDC_CLIENT_SECRET=<secret-value>
LILLITH_OIDC_REDIRECT_URI=https://lillith.example.com/auth/microsoft/callback

Add the exact callback URL under Authentication → Web → Redirect URIs, grant delegated openid, profile, and email permissions with admin consent, and set Assignment required? to Yes so Entra enforces assignment.

Sessions default to one hour (LILLITH_SESSION_HOURS, clamped 1–168). Admins can revoke individual sessions or all other sessions immediately from Settings → Manage active sessions.

Enrollment

An agent can enroll with a token or request approval. Tokens are scoped to a site with an expiry and use limit; their values are shown once and stored hashed.

With no token, the client appears on the Pending page. Permit lets the admin edit the hostname and choose the site, defaulting to the requested values. Deny blocks that fingerprint for future tokenless attempts. Pending requests expire after LILLITH_PENDING_TTL_HOURS of inactivity (default 24) and revive if the agent polls again.

lillith-agent.exe --install --server https://lillith.example.com --site "Site A" --token <token>

# tokenless: omit --token and approve on the Pending page
lillith-agent.exe --install --server https://lillith.example.com --site "Site A"

With no token and no saved configuration, the agent defaults to https://lillith.nodomainrequired.com, overridable with LILLITH_DEFAULT_SERVER. Use tokens for unattended rollouts; the tray icon turns pink while a client is pending.

Permitted fingerprints receive a one-time machine secret. It is stored as a DPAPI machine-scope blob at %ProgramData%\Lillith, so copying state.json to another PC does not expose it.

Agent flags

One binary runs as a boot-time SYSTEM service and as a per-user tray. A bare run does not install; use --install or the generated install script.

Configuration reference

Server settings are environment variables read at startup from /etc/lillith/lillith.env under systemd.

Endpoints

The browser UI, agent protocol, and binary downloads are served by the same process. Browser pages require a session; agent routes require a machine secret.

Operations

No operation accepts a shell string. Each is a named request/response pair with a typed argument shape. The server only offers operations the connected agent advertised.

Read

• system.info — hostname, OS name and build, uptime, users, IP/MAC, disks, RAM, CPU.
• programs.list — installed programs from the uninstall registry, 32- and 64-bit HKLM plus HKCU.
• program.version.get — fuzzy display-name matches with versions.
• rustdesk.status — RustDesk ID, version, and relay configuration.
• agent.status — agent version, service uptime, last sync, connection state.

Mutating

Mutating operations are gated server-side, require an authenticated admin, and are recorded in the audit log. Package installs download from lillithd, verify SHA-256, run with stored silent arguments, then re-query and report the version.

Everything else — services, updates, time, files, registry, screenshots, VNC, reboot, rename, Wake-on-LAN — follows the same pattern: a named operation, typed arguments, a deadline, and a result.

Backup & restore

Backup downloads one .tar.gz containing a consistent SQLite snapshot, uploaded packages, screenshots, VNC recordings, the ACME directory, a manifest, and a restore README. The database snapshot uses VACUUM INTO, so it is safe while the server runs, and the archive streams to the browser without holding the whole file in memory.

Restore accepts the same archive and validates the manifest, database integrity, schema, paths, and unfinished downloads before staging. Staged data is applied on the next server start, so the live connection pool is never swapped underneath clients. Under systemd the service restarts automatically; otherwise restart lillithd yourself.

The Backup page also reports database size, page count, and reclaimable free pages, and can run a WAL checkpoint plus VACUUM and PRAGMA optimize. Retention limits for jobs, events, audit rows, and screenshots live on Settings; 0 days keeps data forever.

Troubleshooting

FAQ