Running Founding Bot X in the background

On Linux and macOS, Founding Bot X can run as a service for your user so you do not need to keep a terminal open.

Manage the service

Install the foundingbot-x CLI first (Install Founding Bot X), then run these commands on the machine that will host Founding Bot X:

Task	Command
Install and start	foundingbot-x service install
Inspect status and log location	foundingbot-x service status
Move to a newer release	foundingbot-x update
Restart	foundingbot-x service restart
Stop and remove from startup	foundingbot-x service uninstall

Uninstalling the service leaves your projects, threads, and settings intact. Running foundingbot-x service install again repairs a service that foundingbot-x service status reports as broken.

foundingbot-x update downloads the newest release on your channel and switches foundingbot-x and the service to it. Restarting interrupts running agent turns, terminals, and remote clients, so it asks first; answer no and the service keeps running the old version until you run foundingbot-x service restart. Pass --yes from a script. A server you started by hand is left running; stop and start it again to pick up the new version. Wait for any remote update already in progress before updating; to match a remote client's version, follow Updating Founding Bot X.

Pass an exact version (foundingbot-x update 0.0.46) to pin one, or --allow-downgrade to move backwards. preview is a maintainers' test train: its builds can be broken and are never offered as updates, so the installer and foundingbot-x update ask for confirmation before installing one.

foundingbot-x uninstall removes the background service, the foundingbot-x launcher, and the downloaded versions after showing you the list and asking once. Your projects, threads, and settings under ~/.foundingbot-x/userdata are kept, along with service.env in the Founding Bot X home folder. Pass --yes from a script.

Configure the service environment

Put custom environment variables in service.env in the service's Founding Bot X home folder, normally ~/.foundingbot-x/service.env. This file survives service installation and updates. For example:

FOUNDINGBOT_X_PORT=3773
FOUNDINGBOT_X_HOST=127.0.0.1

Use KEY=VALUE entries, quoting values that contain spaces or #. Values are literal: shell commands and variable expansion are not evaluated. Entries override the inherited service environment, except for PATH, FOUNDINGBOT_X_HOME, FOUNDINGBOT_X_BOOT_SERVICE_UNIT, and FOUNDINGBOT_X_SERVICE_LAUNCHER_CONTEXT (including case variants).

Run foundingbot-x service restart after changing the file. Changes apply when the service starts again; switching the server version alone keeps the current values. For a service installed before env-file support, run foundingbot-x service install once with an up-to-date CLI. A missing file is ignored; other read failures stop service startup. If the file contains credentials, restrict access to that file with chmod 600 (for the default home folder, chmod 600 ~/.foundingbot-x/service.env).

Platform support

Linux needs systemd user services. Setup enables lingering so Founding Bot X starts at boot and keeps running after logout. If this needs administrator permission, setup prints a recovery command before changing the service.

macOS starts the service when you log in and stops it when you log out. Keep the Mac logged in and awake for unattended remote access. Installing over SSH while nobody is logged in at the Mac's screen can fail at the final start step; the service is still installed and will start at the next login.

Windows background services are not supported.

Founding Bot Connect can offer service installation during setup, but the two are managed separately. Signing out of Founding Bot Connect does not stop or uninstall the service.

Troubleshooting

Start with foundingbot-x service status on the host. It prints the log path and, on Linux, checks whether the installed service is running, enabled, and allowed to survive logout.

If it stops when your SSH session closes, check for linger-disabled. An administrator can enable lingering with:

sudo loginctl enable-linger "$(id -un)"

Over SSH, allow sudo to prompt:

ssh -t your-server 'sudo loginctl enable-linger "$(id -un)"'

Then retry service setup as your normal user. Run only the loginctl command with sudo; running Founding Bot X as root creates a separate installation and Connect identity. Without administrator access, run foundingbot-x serve in a terminal and keep that session open.

Status problem	Next step
linger-unavailable	Run loginctl show-user "$(id -un)" --property=Linger and check that systemd-logind is available.
user-manager-unavailable	Run systemctl --user status in a login session for the service user; check your distribution's systemd user-session support.
service-disabled or service-stopped	Read the log and systemctl --user status foundingbot-x.service, then use the repair command printed by Founding Bot X.
restart-pending	A newer version is installed but the service still runs the previous one. Run foundingbot-x service restart.

On macOS, check System Settings → General → Login Items if the service no longer starts at login. If agent work cannot access Desktop, Documents, or Downloads, it may need Full Disk Access for the foundingbot-x executable listed in ProgramArguments in ~/Library/LaunchAgents/bot.founding.x.service.plist.

For failures after signing in to Founding Bot Connect, see connection troubleshooting.

Reclaim database space

Founding Bot X removes superseded internal history on its own while it runs; your conversations are kept. Databases created before this shrank automatically still hold the freed space on disk until a one-time offline repair returns it and turns on automatic shrinking. Settings > Storage (web and desktop) or Settings > Maintenance (mobile) suggests the repair when at least 1 GiB can be reclaimed.

Run foundingbot-x doctor on the machine that hosts the environment. It reports the database size and the space it can reclaim, then asks which repairs to run; pass --fix to run the recommended ones without a prompt (for scripts), or --dry-run to only report. An installed background service for the same data directory is stopped for the repair and started again afterwards, also when the repair fails. Quit a server you started by hand, or the desktop app, first: the repair refuses to touch a database that is in use. Use --base-dir for a different data directory.

The repair can take several minutes on a large database. It rebuilds the database through a temporary copy, so it needs free space of about the database's size twice over: once in the system temporary directory (TMPDIR or /tmp on Linux and macOS) and once next to the database for its write-ahead log.