Install with Docker Compose (manual)

Prefer to manage Docker Compose yourself? Every release ships as a self-contained bundle with a setup.sh helper. It's the same stack the CLI installs, without the wizard.

Most people should use the CLI. It adds backup, restore, upgrade, and health checks on top of this bundle.

1. Download and verify the bundle

Download the Community bundle (.tar.gz) and its .sha256 checksum from the Helpin releases page, then verify it:

sha256sum -c helpin-community-<version>.tar.gz.sha256
tar -xzf helpin-community-<version>.tar.gz
cd helpin-community-<version>/community

2. Generate configuration

./setup.sh install

This creates .env with independent secrets and encryption keys. It never runs .env as shell code, and running it again keeps existing values.

Edit .env to set your public URLs and, optionally, SMTP and AI keys. Every setting is described in the environment variable reference.

3. Start Helpin

./setup.sh start
./setup.sh status

Open http://localhost:8085 and sign up. The first account becomes the server admin.

Everyday commands

./setup.sh status                                # containers, images, migrations
./setup.sh logs helpin-api agent-runtime-worker  # follow logs
./setup.sh stop                                  # stop; data volumes are kept
./setup.sh start                                 # start again, applying .env changes

Warning: Never run docker compose down -v on data you want to keep.

Using docker compose directly

setup.sh start passes the agent runtime's app configuration inline, so running commands can't read it from disk. If you run Compose yourself, export it first without printing it:

export AGENT_RUNTIME_EXECUTION_APP_CONFIG="$(cat apps.json)"
docker compose --env-file .env -f compose.yaml up -d

External PostgreSQL

The bundle includes PostgreSQL 17 with pgvector. To use your own server instead, install pgvector and create the extensions in the Helpin database before the first migration:

CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS pgcrypto;

The agent runtime and Temporal use their own databases. External databases aren't covered by helpin backup, so back them up with your database tooling.

Upgrades

Published bundles pin every image by digest, so changing a version variable doesn't upgrade anything. To move to a new release, follow the release notes, or use helpin upgrade, which verifies the upgrade path and takes a recovery backup first.