Manage your install#

The installer puts a tool called manage in the install folder (~/chatvia by default), next to compose.yaml and .env. It does the everyday work for you: start and stop Chatvia, back up and restore, set a new password, and tune PostgreSQL.

cd ~/chatvia
./manage                # every command
./manage status         # is everything running?
./manage help backup    # the options of one command

It runs Docker Compose in its own folder, so it also works from another folder: ~/chatvia/manage status. When your user cannot reach Docker, it uses sudo.

curl -fsSLO https://raw.githubusercontent.com/chatvia/chatvia/main/docker/manage
chmod +x manage

The install folder#

Your data is not in this folder: Docker keeps it in volumes (see Back up).

Commands#

The services are app, horizon, scheduler, reverb, pulse, postgres and redis, and proxy with HTTPS built in (proxy-self-signed with HTTPS on an IP address). After you change .env, run ./manage restart.

Keep redis and horizon running, and do not remove or replace them in compose.override.yaml. For now, Chatvia needs Redis and Laravel Horizon (Redis and Horizon are required).

Back up#

./manage backup

A backup is one file in backups/, like chatvia-2026-10-12-031500.tar. It holds:

• The database. The tool also saves the database's own settings, which a plain pg_dump leaves out.
• The analytics database: the numbers behind the charts and reports. It is a database of its own, and goes in every backup.
• The app key and the other secrets of your install. Without the app key, the API keys in the admin panel cannot be read on another server.
• Redis: who is signed in, and the memory of open chats. Without it, everyone signs in again after a restore.
• The uploaded files, when you add --files. Leave it out when your files are in object storage (S3).

To back up every night at 3 and keep a week of backups, add this line to your crontab (crontab -e):

0 3 * * * $HOME/chatvia/manage backup --keep 7

--keep only deletes regular backups. The backups the tool makes before a restore, an upgrade, a rollback or an uninstall stay until you delete them.

To keep backups on another disk, set CHATVIA_BACKUP_DIR for the backup, backups and restore commands, for example CHATVIA_BACKUP_DIR=/mnt/backups/chatvia ./manage backup.

Restore#

./manage restore                                  # choose from the list
./manage restore chatvia-2026-10-12-031500.tar    # or name one

A restore replaces all data, so it shows what it will do and asks first. Then it:

1. Backs up the current data (skip it with --no-backup).
2. Restores the database next to the current one, while Chatvia keeps running. If this fails, your data is not touched.
3. Stops Chatvia and switches to the restored database.
4. Puts back the uploaded files and the app key, when the backup has them.
5. Puts back Redis, so people stay signed in and open chats keep their memory. It empties the queues and the cache, so a job from the time of the backup does not run a second time.
6. Starts Chatvia again. The migrations run on the start, so a backup from an older version is updated.

It needs free disk space for a second copy of the database for a short time.

FILE can also be a backup the app made in Settings → Backups. Download it there and copy it into the install folder. An encrypted one (.tar.gpg) is decrypted first: this needs gpg on the server and your private key, and gpg may ask for its passphrase. Such a backup holds only the app key of the secrets, so the restore keeps the server's other secrets. It may also hold the analytics, Pulse and Spectra databases, which come back too.

FILE can also be a plain pg_dump file in custom format. Then the current app key is kept, and Redis is emptied, so everyone signs in again.

Move to another server#

1. Install Chatvia on the new server, with the same version or a newer one.
2. Copy a backup file to the new server.
3. Run ./manage restore /path/to/the-backup.tar.

The new server takes the app key from the backup and keeps its own database password. When the backup stores search data in another way than the new install (embedding storage), the tool changes .env to match the backup.

A backup from a newer version of Chatvia does not fit an older one: upgrade the new server first.

Passwords and admins#

Set a new password, for example when you are locked out and e-mail is not set up yet:

./manage password [email protected]

Without an e-mail, it asks for one and suggests the first admin. You choose a password, or let the tool make a strong one and show it once. Add --disable-2fa when the account lost its authenticator app: it also turns off two-factor sign-in, so you can set it up again after you sign in.

Create another admin account, with its own workspace:

./manage admin [email protected] --name "Sam"

The password goes to the app through standard input, never on a command line.

Tune PostgreSQL#

The installer saves PostgreSQL's settings to postgres/postgresql.conf, and PostgreSQL reads them from there. The file starts as PostgreSQL's own file, with the values your install started with.

The quick way is to let Chatvia size the file:

./manage postgres tune

It reads the memory and processors the database container actually gets (a container limit counts). It computes the usual sizes for a web app on SSD storage: shared_buffers, effective_cache_size, maintenance_work_mem (what the search index builds use), work_mem, the WAL sizes, the planner's SSD costs and the parallel workers. Then it shows every change next to the running value before it asks. Its lines in the file are marked # set by Chatvia tune: a new run replaces them, and never your own edits. Run it again after you give the machine more memory or processors.

To change a setting yourself:

./manage postgres edit

It opens the file in your editor ($EDITOR, else nano), and applies it when you close the editor. You can also change the file with any editor and then run:

./manage postgres apply

This:

1. Checks the file with PostgreSQL itself. When a value is wrong, it shows the error and its line, and changes nothing.
2. Checks that shared_preload_libraries still has pg_textsearch, which Chatvia's keyword search needs. Add your own libraries after it.
3. Reloads PostgreSQL.
4. Restarts PostgreSQL when a changed setting needs that, after it asks. Chatvia pauses for a few seconds. In the file, these settings say "change requires restart".

For example, on a server with 8 GB of memory that also runs Chatvia:

shared_buffers = 2GB           # change requires restart
effective_cache_size = 6GB
maintenance_work_mem = 512MB

PostgreSQL shares the machine with the rest of Chatvia, so leave memory for the app and the queue workers.

Many parallel workers can need more shared memory than the default 256 MB. Uncomment shm_size in compose.override.yaml, then run ./manage restart postgres.

./manage postgres export starts over from the default settings. Your file is kept as a copy, like postgresql.conf.20261012-031500.bak.

./manage psql opens a PostgreSQL prompt. Arguments go to psql:

./manage psql -c "SELECT pg_size_pretty(pg_database_size(current_database()))"

Size the queue workers#

A new install sizes its queue workers to the machine once, at the end of the install. After you give the machine more memory or processors, size them again:

./manage artisan chatvia:workers:tune --restart

It reads the memory and processors, saves a worker count for each kind of work (chat, files and websites, analytics, records, audio and video, voice calls) in the admin panel under Settings → Platform → Queue workers, and restarts Horizon so the numbers apply. Without --restart, the numbers wait for the next restart. --dry-run only shows them. The command never runs by itself, so numbers you set in the admin panel stay until you run it again.

HTTPS built in#

./manage https on
./manage https status
./manage https off
./manage https ca

With HTTPS built in, ChatVia.ai runs Caddy on ports 80 and 443. Caddy gets a free certificate for your domain and renews it by itself. It also gets one for each agent's custom domain, the first time someone opens it. See HTTPS built in for what you need first: an A record for your domain, and ports 80 and 443 free and open.

on asks for your domain (the one in APP_URL is the default), checks the ports and the A record, and asks once. Then it saves the settings in .env, starts Caddy, restarts ChatVia.ai and waits for the certificate. If the domain does not point at the server yet, Caddy keeps trying by itself.

on first asks which kind you want: on your domain, or on this server's IP address. For the IP address, it asks for the address (this server's public one is the default) and the port, then saves the settings, starts Caddy and checks that HTTPS answers. Its certificate is Caddy's own, so browsers warn until you trust it. See HTTPS on an IP address. Turning on one kind turns off the other.

status shows if HTTPS works and which certificates Caddy has.

ca is for HTTPS on an IP address. It saves Caddy's root certificate as chatvia-root-ca.crt in the install folder, and shows how to trust it on your own devices, so the browser warning goes away.

off stops Caddy and takes the settings out of .env. ChatVia.ai keeps its https:// address, and APP_PORT opens to the network again, for your own proxy (see Use your own proxy). The certificates stay saved, in case you turn it on again.

Backups leave the certificates out: Caddy gets them again by itself, also on a new server.

Upgrade#

./manage upgrade

.env names the exact version you run, like CHATVIA_VERSION=1.4.2. The upgrade:

1. Looks up the newest version and downloads it. Chatvia keeps running.
2. Shows the change (1.4.2 → 1.5.0) and a link to the release notes, and asks once. It warns you when the first number changes (a major version).
3. Backs up the database, the app key and Redis.
4. Runs the installer. It downloads the new compose.yaml and manage, then changes them and .env only when every download worked.
5. Starts the new version. The database is updated before the new version serves requests.

If the new version does not start, the tool offers to go back to the old version with the backup from step 3 (see Roll back). With --yes it goes back without asking.

Your settings, your changes in compose.override.yaml and postgres/postgresql.conf are kept. After an upgrade, the images of older versions are deleted. The image of the version you upgraded from stays, so a rollback needs no download.

The tool never moves to an older version this way: an older version does not fit a database that a newer one has changed. Use rollback for that.

Roll back#

./manage rollback

It goes back to the version you ran before the last upgrade. It uses the newest backup made before an upgrade from an older version, or the backup you name (./manage rollback chatvia-2026-10-12-031500-before-upgrade.tar). The backup says which version made it.

A rollback replaces all data with that backup: everything since the upgrade is lost (new chats, settings and sources). So it shows what it will do and asks first. Then it:

1. Backs up the current data (skip it with --no-backup).
2. Runs the installer to get the older version ready, without starting it.
3. Restores the backup, like restore does, and starts the older version.

Uninstall#

./manage uninstall

It deletes the containers, all data (the database, the uploaded files and the app key) and the settings files in the folder. It offers a last backup first, and asks you to type delete. The backups in backups/ are kept.

Scripts and cron#

Commands that ask questions take --yes to use the defaults instead. Without a terminal (for example in cron), the tool asks nothing. restore, rollback and uninstall then only run with --yes.

Only one command that changes things runs at a time. When a backup from cron starts during a restore, it stops with a message instead. stop and uninstall are the exception: when another command hangs, they offer to stop it and go on. With --yes, uninstall stops it without asking.

When your user cannot reach Docker, the tool uses sudo. In cron, sudo cannot ask for a password: run the job as root, or add your user to the docker group (sudo usermod -aG docker $USER, then sign in again).