Honcho Proxmox LXC Installer

Create and maintain a dedicated Honcho LXC on a Proxmox VE host.

This repository provides a Bash installer/maintenance helper that:

creates an unprivileged Debian 13 LXC for Honcho,
enables the LXC features needed for Docker-in-LXC,
installs Docker plus current standalone Docker Compose and buildx plugins inside the container (Honcho's images are built from source, which needs buildx >= 0.17.0),
clones upstream Honcho and starts it via honcho.service,
exposes the Honcho API on the container's LAN address on port 8000,
provides status, backup, and conservative update commands.

This is an independent install and update script, not an official Honcho or Proxmox project.

Requirements

Run the script on the Proxmox host as root. The host must have standard Proxmox tools available:

pct
pveam
pvesm
network access to GitHub and Debian/Proxmox package mirrors

The installer expects a Debian 13 LXC template to be available through pveam. If none is found, it fails closed and asks you to run pveam update rather than silently downgrading to another OS release.

Security model

By default, the installer:

creates an unprivileged LXC,
binds the Honcho API to the container network interface (0.0.0.0:8000 inside Docker Compose) so other LXCs can reach it,
enables Honcho authentication and prints an admin JWT for client setup,
stores Honcho provider API keys inside /opt/honcho/.env in the LXC,
expects an OpenAI-compatible API key for the default upstream Honcho configuration, because the bundled defaults use OpenAI-compatible chat and embedding models.

Treat the printed Honcho admin JWT and the LXC's /opt/honcho/.env as secrets.

If you intentionally want a trusted-LAN/no-auth deployment, pass --no-auth. Do not expose a no-auth Honcho API to the public Internet.

Defaults

Setting	Default	Notes
OS template	Debian 13	Fails if unavailable
CTID	Prompted	Required with `--yes`
Hostname	`honcho`	Override with `--hostname`
Bridge	Auto-detected, fallback `vmbr0`	Prompted interactively
Rootfs storage	Auto-detected: a `rootdir`-capable storage, prefers `local-lvm`/`local-zfs`	Prompted interactively
Template storage	Auto-detected: where the Debian 13 template already lives, else a `vztmpl`-capable storage (prefers `local`)	Prompted interactively
Network	DHCP IPv4	Static IP supported with `--ip` and `--gw`
IPv6	Disabled inside the container	Not passed as a Proxmox `net0` option
Cores	`2`	Override with `--cores`
RAM	`4096` MB	Override with `--memory`
Swap	`1024` MB	Override with `--swap`
Disk	`32` GB	Override with `--disk`
LXC privilege	Unprivileged	Fixed by installer
LXC features	`nesting=1,keyctl=1`	Needed for Docker-in-LXC
Honcho ref	`main`	Override with `--honcho-ref`
Honcho auth	Enabled	Disable only with `--no-auth`
Embedding dim	Honcho default (1536)	Override with `--embedding-dim N` (forces a no-start install)

Unified install/update runner

Run the main script directly from GitHub on the Proxmox host for install, update, status, or backup. With no arguments it opens an interactive menu:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/MarcvsTvllivs/honcho-proxmox-lxc-debian13/main/honcho-proxmox-lxc-debian13.sh)"

You can also call a subcommand directly through the same command:

# Install a new Honcho LXC
bash -c "$(curl -fsSL https://raw.githubusercontent.com/MarcvsTvllivs/honcho-proxmox-lxc-debian13/main/honcho-proxmox-lxc-debian13.sh)" -- install

# Update an existing Honcho LXC
bash -c "$(curl -fsSL https://raw.githubusercontent.com/MarcvsTvllivs/honcho-proxmox-lxc-debian13/main/honcho-proxmox-lxc-debian13.sh)" -- update --ctid {CTID}

# Show status or create a backup
bash -c "$(curl -fsSL https://raw.githubusercontent.com/MarcvsTvllivs/honcho-proxmox-lxc-debian13/main/honcho-proxmox-lxc-debian13.sh)" -- status --ctid {CTID}
bash -c "$(curl -fsSL https://raw.githubusercontent.com/MarcvsTvllivs/honcho-proxmox-lxc-debian13/main/honcho-proxmox-lxc-debian13.sh)" -- backup --ctid {CTID}

This is convenient, but it executes the mutable main branch as root. For a more cautious Proxmox-host workflow, use download-then-run, inspect the script, or pin the raw URL to a reviewed commit/tag.

Download-then-run

curl -fsSL https://raw.githubusercontent.com/MarcvsTvllivs/honcho-proxmox-lxc-debian13/main/honcho-proxmox-lxc-debian13.sh -o honcho-proxmox-lxc-debian13.sh
chmod +x honcho-proxmox-lxc-debian13.sh
./honcho-proxmox-lxc-debian13.sh install

With no subcommand and a real terminal, the script opens the same install/update/status/backup menu. In non-interactive use, install is assumed for backward compatibility.

Non-interactive install

--yes skips confirmation prompts but still requires enough information to avoid guessing important values. Provide at least --ctid and preseed an OpenAI-compatible provider key through the environment, because Honcho's default self-host config will not start without one. (Pass --no-start to skip this requirement: the LXC is created without starting Honcho, and you add the key to /opt/honcho/.env before the first start.)

export HONCHO_LLM_OPENAI_API_KEY='<openai-compatible-api-key>'
./honcho-proxmox-lxc-debian13.sh install --yes --ctid {CTID}

Supported key environment variables:

HONCHO_LLM_OPENAI_API_KEY      # required to start (optional with --no-start)
HONCHO_LLM_ANTHROPIC_API_KEY  # optional, for custom Honcho model routing
HONCHO_LLM_GEMINI_API_KEY     # optional, for custom Honcho model routing

The script also accepts upstream-style aliases if already set:

LLM_OPENAI_API_KEY
LLM_ANTHROPIC_API_KEY
LLM_GEMINI_API_KEY

Avoid passing provider keys as command-line arguments because command lines can appear in shell history and process listings.

Maintenance

Use the unified runner above, or download the helper once and run it locally. Replace {CTID} below with your Honcho LXC container ID.

Check status

./honcho-proxmox-lxc-debian13.sh status --ctid {CTID}

This checks:

Proxmox container status/config,
honcho.service,
Docker Compose services,
current Honcho git commit,
local health endpoint,
the Honcho URL to use from other LXCs.

Create a backup

./honcho-proxmox-lxc-debian13.sh backup --ctid {CTID}

The backup is written on the Proxmox host under:

/root/honcho-backups/ct-{CTID}-{timestamp}/honcho-backup.tar.gz

It includes:

/opt/honcho/.env,
/opt/honcho/docker-compose.yml,
a verified non-empty Postgres pg_dumpall dump,
git/service metadata.

Backups contain secrets from .env; the helper creates the host backup directory with restrictive permissions and sets the tarball to mode 600.

By default, backup fails closed if the database dump fails. If you intentionally want a config-only/partial archive, use:

./honcho-proxmox-lxc-debian13.sh backup --ctid {CTID} --allow-partial-backup

Update Honcho safely

./honcho-proxmox-lxc-debian13.sh update --ctid {CTID}

The update flow is intentionally conservative:

start the container if needed,
verify the CTID looks like a Honcho LXC created by this installer,
create a Proxmox snapshot named pre-honcho-update-{timestamp},
create a logical backup under /root/honcho-backups,
fetch/update the Honcho git checkout, refusing to proceed if tracked local changes exist,
re-apply LAN API binding if upstream compose is localhost-only,
ensure a modern Docker Compose is available, refresh docker-compose.yml from upstream docker-compose.yml.example, then pull/build Docker Compose services,
stop the API service before running Alembic migrations,
restart honcho.service,
fail the update if the post-update health check fails,
prune unused Docker images after health passes,
print status/health output.

Useful flags:

./honcho-proxmox-lxc-debian13.sh update --ctid {CTID} --yes
./honcho-proxmox-lxc-debian13.sh update --ctid {CTID} --honcho-ref main
./honcho-proxmox-lxc-debian13.sh update --ctid {CTID} --backup-dir /root/honcho-backups

Only skip safety steps when you mean it:

./honcho-proxmox-lxc-debian13.sh update --ctid {CTID} --no-snapshot
./honcho-proxmox-lxc-debian13.sh update --ctid {CTID} --no-backup

Restore

The backup command produces honcho-backup.tar.gz. Restore it into the same LXC (or a freshly installed one) as follows. Replace {CTID} with your Honcho LXC ID.

Unpack the archive on the Proxmox host. The tarball contains a single timestamped directory (e.g. 20260101-120000/) with .env, docker-compose.yml, postgres.sql, and metadata.txt:
```
tar -xzf honcho-backup.tar.gz
cd 20260101-120000   # the extracted timestamped directory
```
Put the configs back. Either push them into the existing container:
```
pct push {CTID} .env /opt/honcho/.env
pct push {CTID} docker-compose.yml /opt/honcho/docker-compose.yml
```
or restore into a freshly installed LXC created with ./honcho-proxmox-lxc-debian13.sh install --no-start and then push the two files over the generated ones.
Stop the stack so nothing is talking to the database:
```
pct exec {CTID} -- systemctl stop honcho.service
```
Restoring into a CT that already holds Honcho data (in-place disaster recovery)? The dump is pg_dumpall output with no DROP/--clean statements, so replaying it over an existing schema collides — psql keeps going past the already exists errors and can leave a half-merged database. Wipe the Postgres volume first so the dump loads into an empty database:
```
pct exec {CTID} -- bash -lc 'cd /opt/honcho && /usr/local/bin/honcho-compose down -v'
```
down -v removes this project's named volumes — honcho_pgdata and the disposable honcho_redis-data — and the next step recreates an empty pgdata. (To keep the Redis volume, instead run … honcho-compose down then docker volume rm honcho_pgdata.) Skip this entirely when restoring into a fresh --no-start LXC — its database is already empty, and the steps below apply as written.

Start only the database service:

pct exec {CTID} -- bash -lc 'cd /opt/honcho && /usr/local/bin/honcho-compose up -d database'

Load the dump. It comes from pg_dumpall, so restore it through the postgres superuser (it recreates roles and databases itself):

pct exec {CTID} -- bash -lc 'cd /opt/honcho && /usr/local/bin/honcho-compose exec -T database psql -U postgres -f -' < postgres.sql

Start everything and verify health:
```
pct exec {CTID} -- systemctl enable --now honcho.service
pct exec {CTID} -- curl -fsS http://127.0.0.1:8000/health
```
(enable --now also re-enables boot start, which a --no-start install intentionally leaves disabled.)

Client setup

After install/update, configure your Honcho client or integration to use the URL printed by the installer/status command, usually:

http://<honcho-lxc-ip>:8000

If you kept the default authenticated deployment, use the printed Honcho admin JWT as the client's bearer token / API token. If you installed with --no-auth, leave the token unset and keep the API on a trusted private network only.

Notes

Run this on the Proxmox host as root.
The install command prompts interactively for required values.
Install asks whether to start Honcho immediately. Choose no (or pass --no-start) to create the LXC without starting Honcho, so you can edit /opt/honcho/.env (e.g. model config) before the first start; then start it with pct exec <CTID> -- systemctl enable --now honcho.service. A --no-start install is left disabled so a host reboot does not start Honcho before you finish editing .env; enable --now both enables it on boot and starts it.
To use a non-default embedding size, set --embedding-dim N (or answer the prompt). This writes EMBEDDING_VECTOR_DIMENSIONS=N and forces a no-start install, because a custom dimension needs a matching embedding model and the pgvector schema must be altered before the first start. The installer prints the finish-up steps: set EMBEDDING_MODEL_CONFIG__* in .env for a model that outputs N dimensions, run scripts/provision_db.py then scripts/configure_embeddings.py --yes (it only works on the empty tables of a fresh install and prints the applied dimension to confirm vector(N)), then start. Honcho refuses to start on a dim mismatch.
CTID, bridge, rootfs storage, template storage, and root password are prompted unless supplied explicitly or generated.
Honcho's API is exposed on the container network interface so other LXCs can reach it on port 8000.
IPv6 is disabled inside the container after creation; it is not passed as a net0 option.
Do not pass secrets on the command line if you can avoid it.
Avoid unattended Honcho app updates; use the update command so snapshots, backups, compose refresh, migrations, and health checks happen in order.
The Honcho app update command intentionally does not run apt upgrade; OS package maintenance should be a separate maintenance window with its own snapshot/backup/reboot plan.

License

MIT License. See LICENSE.

FilesExpand file tree

README.md

Latest commit

History