Operations

The commands on this page run from your project folder. Every docker compose command takes -f deploy/docker-compose.yml.

Applying changes

After you change config/config.yaml, .env, package.json, or anything in src/, rebuild and restart:

docker compose -f deploy/docker-compose.yml up -d --build

Changes to files in docs/ are picked up at the next sync.

Upgrades

The engine is the @ithousecall/chat npm package. Your config, docs, and code stay as they are.

npm install @ithousecall/chat@latest
docker compose -f deploy/docker-compose.yml up -d --build

Commit package.json and package-lock.json; the Docker build installs from the lockfile.

Read the release notes for new or changed config keys. An invalid config stops startup with the path of the bad key, so problems show up right away in the logs.

Data volume

Everything @housecall stores lives in the data Docker volume, mounted at /app/data. When you run npm start or npm run console, it uses the data/ folder in your project instead.

To run the console against the data volume, stop the service first:

docker compose -f deploy/docker-compose.yml stop
docker compose -f deploy/docker-compose.yml run --rm housecall node --no-warnings=ExperimentalWarning src/main.ts --console

File	Contents
`session.sqlite`	Conversations, thread mappings, approvals, and the images shown to the model.
`docs.sqlite`	The search index and per-source sync status.
`housecall.lock`	The instance lock.

docs.sqlite can be rebuilt from your sources: stop @housecall, delete it, and start again.

docker compose -f deploy/docker-compose.yml stop
docker compose -f deploy/docker-compose.yml run --rm housecall rm /app/data/docs.sqlite
docker compose -f deploy/docker-compose.yml start

Don’t delete session.sqlite unless you want to drop every conversation and pending approval.

Single instance

@housecall holds an exclusive lock on housecall.lock while it runs. A second @housecall on the same data, in the same container or another, refuses to start under the header @housecall cannot start: with another @housecall is already using /app/data/, the absolute path of the data folder. The lock is released when the process exits, however it exits. Stop the service before using docker compose run on the same volume.

Don’t scale the service to more than one replica.

Restarts

Compose runs the service with restart: unless-stopped. If @housecall hits a fatal error it exits with status 1 and Compose starts it again. Answers and approvals that were in progress resume from the data volume. Messages sent while it was stopped are not answered.

docker compose -f deploy/docker-compose.yml logs -f
docker compose -f deploy/docker-compose.yml restart

Logs

Line	Meaning
`[housecall] up: slack, teams`	Connected to these platforms.
`[docs] <source>: N indexed, N removed, N failed`	A source finished syncing.
`[docs] removed N documents of sources no longer configured`	A source was removed from the config, and its documents were deleted.
`[turn] unanswered <reason> <detail>`	The model could not answer. The person sees `Sorry, I could not answer that (<reason>)`.
`[approvals] <id> <user>: <text>`	A click on an approval card that did not count, and the reply it got.
`[attachments] <platform> <file>: <error>`	An image could not be downloaded. The model is told it could not see it.
`[attachments] <platform> <file>: ... answered with a web page, not the file`	The platform sent a web page instead of the image, such as Slack without `files:read`.
`[attachments] <platform> <file>: WxH is over 25000000 pixels`	An image was over 25 megapixels and was skipped.
`[attachments] <platform> <file>: not a PNG, JPEG, GIF or WebP image`	An image in another format was skipped.
`[attachments] <platform> <file>: could not be decoded`	An image file was damaged and was skipped.
`[mcp] <server>: skipping tool ...`	An MCP tool name collided with another tool.

Backups

Your project folder is in git, except .env and secrets/. Back those up with the data volume: stop @housecall, copy the volume out of the container, and archive it.

docker compose -f deploy/docker-compose.yml stop
docker compose -f deploy/docker-compose.yml cp housecall:/app/data ./housecall-data
tar czf housecall-backup.tgz housecall-data .env secrets
docker compose -f deploy/docker-compose.yml start

Leave out secrets if you have no service account key.