Four things bite on a real deployment. Each one fails quietly:
- The default bind is
127.0.0.1. If your reverse proxy runs on another host, it gets a 502 while board-oss looks healthy. - Changes to the installed systemd unit are reverted on upgrade. The install script rewrites it. Use a drop-in.
- systemd's
PATHis minimal, so a CLI agent your shell finds, the service does not. - A CLI agent's login is interactive, and must run as the service user.
The README covers installation. This document covers the decisions and failure modes that come after it.
Examples use a Proxmox LXC, which is what board-oss is sized for. Only the container section is Proxmox-specific; the rest applies to any Debian host.
board-oss itself is small. Headless Chromium is what sizes the box — it spikes during capture and is idle the rest of the time.
| Minimum | Comfortable | |
|---|---|---|
| Cores | 2 | 4 |
| RAM | 1 GB | 4 GB |
| Root disk | 8 GB | 16 GB |
Screenshots dominate disk growth over time. Budget roughly 0.5–1 MB per captured item on top of the base install; a 150-item collection runs to about 100 MB.
Use an unprivileged container. It needs two features that are off by default:
features: nesting=1,keyctl=1
Without them Chromium and Node hit permission errors that look unrelated to either. Set them at creation time or in the container config.
package.json deliberately declares no engines.node, so nothing will stop you
running an unsupported version. Use Node LTS. scripts/install-lxc.sh installs
NodeSource LTS when node is missing, which is the version the project is tested on.
better-sqlite3 ships a prebuilt binary for glibc Linux on Node LTS, so no compiler
is needed. If you end up on a combination with no prebuilt, install
build-essential python3 first.
board-oss ships no authentication of its own — auth and TLS are the reverse proxy's job. See the README's security section for why. Where that proxy runs decides how board-oss must bind.
Nothing to do. The shipped unit binds 127.0.0.1:8080, the proxy connects over
loopback, and the port is unreachable from the network. This is the default because
it is the safe one.
The proxy returns 502, board-oss looks healthy, and /healthz passes from inside the
container. Everything points at the proxy, and the proxy is fine.
127.0.0.1 is unreachable from anywhere but the container itself, so board-oss must
bind an address the proxy can route to.
Do not edit deploy/board-oss.service or the installed unit file directly.
scripts/install-lxc.sh rewrites /etc/systemd/system/board-oss.service, so an
upgrade silently reverts your change and the service goes unreachable again. Use a
systemd drop-in, which survives:
systemctl edit board-oss[Service]
Environment=HOST=0.0.0.0systemctl restart board-ossConfirm it is listening off-loopback:
ss -ltnp | grep 8080 # expect 0.0.0.0:8080, not 127.0.0.1:8080board-oss logs a one-line warning at boot when it binds a non-localhost address. That warning is correct and you should not silence it: the port now has no authentication in front of it. Restrict it at the network layer so only the proxy can reach it — a host firewall rule, a container firewall, or a private VLAN.
A minimal Caddy site block for the proxy host:
board.example.internal {
reverse_proxy http://<board-host-ip>:8080
encode gzip
}If you run split-horizon DNS, point the name at the proxy, not at board-oss.
board-oss runs fully without AI — enrichment shows a dignified "disabled" state rather than failing. There are two ways to turn it on.
The simpler of the two. Add the provider env with a drop-in and restart:
[Service]
Environment=LLM_BASE_URL=https://api.example.com/v1
Environment=LLM_API_KEY=…
Environment=LLM_MODEL=…This uses a coding-agent CLI you already pay for (claude, codex) instead of an API
key. It works. Four things can go wrong first, and none of them produce an obvious
error message.
board-oss spawns the agent by bare command name, with cwd set to a temporary
directory and a 120-second wall-clock timeout (src/llm/cli-provider.ts). That one
sentence explains three of the four problems.
1. The binary must be on systemd's PATH, which is minimal.
Your login shell finds claude because your profile puts it on PATH. systemd does
not read your profile. The spawn fails with ENOENT and surfaces as a generic
enrichment failure. The shipped unit sets no PATH at all, so set one:
[Service]
Environment=PATH=/var/lib/board-oss/.local/bin:/usr/local/bin:/usr/bin:/binVerify it the way the app will, as the service user rather than as yourself:
sudo -u boardoss env PATH=/var/lib/board-oss/.local/bin:/usr/local/bin:/usr/bin:/bin \
claude --version2. The agent needs a writable HOME, and it must be the service user's.
The unit already points HOME, XDG_CONFIG_HOME and XDG_CACHE_HOME at
DATA_DIR — originally so headless Chromium could write its profile under
ProtectSystem=strict. Agent CLIs store their credentials in the same place, so this
works in your favor, with one catch: you must authenticate as the service user
with that same HOME, or the credentials land somewhere the service can't read.
sudo -u boardoss env HOME=/var/lib/board-oss XDG_CONFIG_HOME=/var/lib/board-oss/.config \
claude # then complete the interactive login3. Authentication is interactive and cannot be scripted.
Budget for a human at a terminal; no install script can do this step for you. Until
it is done, enrichment fails and every item lands in the error state with a visible
reason — which is intended, not a bug.
4. Running the agent as root does not test what the service does.
If you invoke the agent from a root shell, it inherits root's HOME and working
directory. The service user typically cannot traverse /root, so the agent's own
tooling fails in ways that have nothing to do with board-oss. Always reproduce as the
service user.
If you would rather not thread PATH and HOME through the unit, install a wrapper
that normalizes the environment and put that on the service's PATH:
# /usr/local/bin/claude root:root 0755
#!/usr/bin/env bash
set -euo pipefail
export HOME=/var/lib/board-oss
export XDG_CONFIG_HOME="$HOME/.config"
export XDG_CACHE_HOME="$HOME/.cache"
cd "$HOME"
# If invoked as root, drop to the service user so credentials and cwd match the app.
if [ "$(id -u)" = "0" ]; then
exec runuser -u boardoss -- env HOME="$HOME" XDG_CONFIG_HOME="$XDG_CONFIG_HOME" \
"$HOME/.local/bin/claude" "$@"
fi
exec "$HOME/.local/bin/claude" "$@"This also makes the agent behave the same whether you invoke it by hand or the service invokes it, which removes a whole class of "works when I run it" confusion.
Capture and the AI read share a single job under one budget, CAPTURE_TIMEOUT_MS,
which defaults to 180 seconds. A CLI agent routinely takes 90–100 seconds for a
single item, so the budget is not generous — it is sized for exactly this. If you use
a slow local model, raise it:
[Service]
Environment=CAPTURE_TIMEOUT_MS=600000An item that exceeds the budget lands in the error state reading "timed out", with
a Try again button on the card. Nothing is lost; the page has already been
captured and only the AI read is missing.
Two different backups, and they are not interchangeable.
board-oss can export everything — every board, every item, and the image files — as a
single .tar. In the app: the button in the bottom-right corner → Your data →
Download a backup. Or directly:
curl -o board-backup.tar http://127.0.0.1:8080/api/backupIt is a plain ustar archive holding manifest.json plus a screenshots/ directory,
so you can inspect it with ordinary tools and without this application:
tar -tvf board-backup.tar | headRestoring is non-destructive by construction: boards that already exist keep their name, view and fields, and items dedupe on their id rather than being overwritten. Restoring your own backup over a live install is a no-op, which makes it safe to test.
curl -X POST http://127.0.0.1:8080/api/backup \
-H 'Content-Type: application/x-tar' --data-binary @board-backup.tarA container snapshot (Proxmox Backup Server, vzdump, ZFS) protects the install, the
systemd configuration and the agent credentials — things the collection export
deliberately does not carry. Run both.
If you store an API key on the box — in a drop-in, a wrapper, or a key file — that container snapshot is now secret-bearing. Either exclude the key path from the backup job and document how to recreate it:
vzdump <ctid> --storage <store> --mode snapshot \
--exclude-path /etc/board-oss/anthropic.key…or accept that the snapshot must be protected as a credential. Decide deliberately
rather than by default. A key file should be root:boardoss mode 0640 so the
service can read it and nothing else can.
If you cloned the repo straight to the app directory (git clone … /opt/board-oss,
then ran the installer from inside it), /opt/board-oss is a working git checkout and
upgrading is:
cd /opt/board-oss
git pull
npm ci --omit=dev
systemctl restart board-ossIf you instead ran the installer from a checkout somewhere else, the app directory is
a copy with no .git, so pull in your original checkout and re-run
scripts/install-lxc.sh with the same APP_DIR / DATA_DIR / PORT values.
DATA_DIR is separate from the code directory, so upgrades never touch your data.
There is no build step — the service runs TypeScript through tsx at runtime.
Anything you changed inside the installed unit file is lost on a re-run of the
install script. Drop-ins (systemctl edit board-oss) survive; use them for every
local change.
| Symptom | Likely cause | Fix |
|---|---|---|
Proxy returns 502, /healthz passes inside the container |
Bound to 127.0.0.1 with the proxy on another host |
Set HOST=0.0.0.0 via a drop-in, firewall the port |
| A local change to the service reverted after an upgrade | The install script rewrites the unit file | Move the change into systemctl edit board-oss |
| Every item fails enrichment immediately | Agent binary not on systemd's PATH |
Set Environment=PATH=…; verify with sudo -u boardoss … --version |
| Enrichment fails only under systemd, works by hand | Authenticated as the wrong user, or a different HOME |
Re-authenticate as the service user with HOME=/var/lib/board-oss |
| Items fail with "timed out" | Capture + AI read exceeded CAPTURE_TIMEOUT_MS |
Raise it; retry the item with Try again on the card |
| Capture fails, no screenshot | Chromium missing, or LXC lacks nesting=1,keyctl=1 |
Install the Debian chromium package; add the container features |
| Cards show but images 404 after a move | The collection export carries paths, the archive carries bytes | Restore from the .tar, not from a JSON export |
Useful commands:
systemctl status board-oss
journalctl -u board-oss -f
curl -fsS http://127.0.0.1:8080/healthz # -> {"ok":true}
ss -ltnp | grep 8080/healthz is a pure liveness probe with no database check, so it stays up during a
SQLite checkpoint rather than flapping and tripping a restart loop. It tells you the
process is alive; it does not tell you enrichment works.