# Operations

Install `pandoc` and run Lisa as a dedicated `lisa` operating-system user. The
user needs read access to the configuration and persona file, read/write access
to `/var/lib/lisa`, and network access to Matrix, the LLM, SearXNG, DNS, and
model-selected web destinations.

Use [`deploy/lisa.service`](../deploy/lisa.service) as a systemd starting point.
Keep credentials in `/etc/lisa/lisa.env` with restrictive permissions; do not
place them in the TOML file or the systemd unit. Set
`LISA_MATRIX_PASSWORD` for Lisa's dedicated Matrix account, not a manually
created access token. Lisa requests refresh tokens and renews access tokens
while it runs; after a rejected refresh it logs in again with the password.
The service stops without restart for a bad password or identity mismatch,
using exit status 78, until the configuration is corrected.

## Health and diagnostics

Run the local, non-network health check:

```sh
lisa --config /etc/lisa/config.toml --health
```

It emits only queue counts and the age of the oldest unsent response. Routine
logs omit room messages, prompts, downloaded pages, URLs with query strings,
and credentials.

## Shutdown, backup, and upgrade

`SIGTERM` and `SIGINT` stop scheduling sync work, wait up to
`shutdown_grace_seconds` for room workers, clear typing state, and return
unfinished invocation leases to the candidate queue. Ready-to-send replies are
not regenerated and remain safely retryable.

For a consistent backup, stop Lisa and copy both `database_path` and
`matrix_store_path`. Restore both together on rollback. The SQLite database is
forward-migrated; use the saved snapshot rather than attempting a reverse
migration.

Before deploying against the production homeserver and LLM, verify the Matrix
server's `/context`, filter, and transaction replay behavior, the LLM's
OpenAI-compatible tool-call dialect, and SearXNG JSON output. These are the
remaining operator-specific integration decisions from the architecture.