Repository navigation
Deployment
Generated from
INSTALL.mdat3f7e3ea3cab7. Edit the source, not this page -- the next merge to main overwrites any change here.
AutoBot is a self-hosted AI platform you own: a small core, the Service Lifecycle Manager (SLM) management layer, and modules on top. Installing AutoBot means standing up that stack on your own hardware. (Throughout this guide, SLM always means Service Lifecycle Manager — AutoBot's management layer — never "small language model." For the full picture, see The AutoBot Platform Model.)
Installation uses a two-phase deployment model:
-
install.sh— a shell script that deploys the Service Lifecycle Manager (SLM) and all dependencies onto a blank Ubuntu 22.04+ host. The SLM is the management layer that then deploys, operates, and scales the rest of the infrastructure. - Setup Wizard — a guided web UI that walks you through adding fleet nodes, testing connections, enrolling agents, assigning roles, and provisioning.
After both phases complete you have a fully operational AutoBot platform and fleet — ready to run the core and install modules.
install.sh installs the SLM node -- the control plane. The platform nodes (backend,
frontend, Redis, ChromaDB, LLM) are provisioned afterwards by the Setup Wizard, onto the hosts
you add there, which may include this one.
SLM node -- what install.sh checks before it starts:
| Requirement | Minimum |
|---|---|
| OS | Ubuntu 22.04+ (the installer gets Python 3.14 and Ansible from Ubuntu PPAs; on Debian and other systems, use Docker) |
| Init system | systemd running as PID 1 — the installer manages every service as a systemd unit |
| RAM | 1.5 GB (the installer refuses to run below this; SLM control plane only) |
| Disk | 5 GB free (the installer refuses to run below this); 20 GB recommended |
| Access | Root (or sudo) |
| Network | Internet access for package downloads |
Supported hosts: an Ubuntu 22.04+ VM or bare-metal machine booted with systemd, or
WSL2 with systemd enabled ([boot] systemd=true in /etc/wsl.conf). Not supported by
install.sh: containers and other hosts where systemd is not PID 1 — use the
Docker deployment there instead.
Platform nodes: no minimum is enforced. Provisioning reaches them over SSH, and the backend unit sizes its own memory limits from the host's memory. A local LLM is the main consumer: plan memory for the models you pull, or use a cloud provider instead (see Choose your AI provider).
# One-liner (downloads and runs the installer):
curl -fsSL https://raw.githubusercontent.com/mrveiss/AutoBot-AI/main/install.sh | sudo bash
# Or clone first, then run:
git clone https://github.com/mrveiss/AutoBot-AI.git
cd AutoBot-AI
sudo ./install.shThe installer takes 10-20 minutes depending on network speed and hardware.
The main one-liner runs the newest installer, unpinned and unverified. For a production host,
install a release instead and verify it first.
Each release publishes three files next to its notes (#18666):
-
install.sh, pinned to that release: it installs exactly that tag; -
install.sh.sha256, its checksum; -
install.sh.sig, a cosign signature made with the key in this repository'scosign.pub.
Releases made before this change do not carry them. Verify, then run:
TAG=v0.0.0 # the release you want, from https://github.com/mrveiss/AutoBot-AI/releases
BASE="https://github.com/mrveiss/AutoBot-AI/releases/download/${TAG}"
curl -fsSLO "${BASE}/install.sh"
curl -fsSLO "${BASE}/install.sh.sha256"
curl -fsSLO "${BASE}/install.sh.sig"
curl -fsSL -o cosign.pub "https://raw.githubusercontent.com/mrveiss/AutoBot-AI/${TAG}/cosign.pub"
sha256sum -c install.sh.sha256 \
&& cosign verify-blob --key cosign.pub --signature install.sh.sig install.sh \
&& sudo bash install.shThe && chain is the point: if a download is missing, the checksum differs or the signature does
not verify, install.sh never runs.
A signature only proves the script matches the key, so the key is the thing to check. Fetching
cosign.pub from the same tag, as above, proves nothing by itself: whoever can replace a tag can
replace its key, signature and release notes together. The first time, compare sha256sum cosign.pub
with a fingerprint from a channel a release cannot rewrite:
-
cosign.pubon themainbranch, viewed in the repository's web interface at a commit you pin (its history shows when the key last changed), and - the fingerprint the owner publishes alongside the key (#19126).
Then keep that cosign.pub and verify later releases against your copy. The SHA256 printed in each
signed release's notes is a comparison aid only, never the proof.
Until the signing key is set up, a release carries install.sh and install.sh.sha256 but no
install.sh.sig; its release job says so in a warning. For such a release, verify the checksum and
drop the cosign step from the chain: sha256sum -c install.sh.sha256 && sudo bash install.sh. A checksum downloaded from
the same release proves the file arrived intact, not who made it: authenticity needs the signing key
(#19126).
Pinned but unverified, as a one-liner next to the main one:
curl -fsSL "https://github.com/mrveiss/AutoBot-AI/releases/download/${TAG}/install.sh" | sudo bashOffline or air-gapped installs are out of scope for now. Phase 3 clones the repository from GitHub, and the roles install packages from your distribution's and vendors' mirrors.
The install script runs seven phases automatically:
| Phase | Description |
|---|---|
| 1/7 Pre-flight | Checks root, systemd, OS, disk, memory, internet, existing installs |
| 2/7 System Setup | Installs system packages, creates autobot user, sets up directories |
| 3/7 Code Deployment | Clones the repository to /opt/autobot/code_source, creates a Python venv |
| 4/7 Ansible Deployment | Runs deploy-slm-manager.yml locally (PostgreSQL, SLM backend, nginx, monitoring) |
| 5/7 Service Verification | Waits for the SLM backend to become healthy (up to 2 minutes) |
| 6/7 Register Local Node | Registers this host with the SLM as its first node and assigns the code source |
| 7/7 Finalize | Writes the install marker, prints access URL and credentials |
Which code is installed: phase 3 clones main from GitHub (or the branch given with
--branch=), even when you run ./install.sh from a local clone — the installer warns when
that happens. Only pushed branches can be installed. The installed commit is printed and
logged.
| Option | Effect |
|---|---|
| (none) | Standard interactive install |
--unattended |
Run without prompts, use all defaults (CI/automation) |
--reinstall |
Force a reinstall over an existing installation |
--uninstall |
Remove AutoBot: shows what it will remove, then asks you to type UNINSTALL. See Uninstalling
|
--yes, -y
|
Skip confirmation prompts (use with --uninstall) |
--validate |
Verify installation integrity (required service directories present) |
--branch=BRANCH |
Git branch to install (default: main) |
--admin-pass-file=PATH |
Read the SLM admin password from the first line of PATH (auto-generated if not set). The file must be non-empty and mode 600 or tighter (chmod 600 PATH), or the installer refuses it. --admin-pass= is refused: a command-line argument is readable by every local user (#19236). |
--ip=IP |
Override the auto-detected IP address (multi-interface hosts) |
--rotate-secrets |
On reinstall, replace the existing SLM admin password. By default a reinstall keeps the password set in the wizard and does not use --admin-pass-file=, though it still validates that file |
--help, -h
|
Show help |
Environment variables skip the matching interactive prompt:
| Variable | Effect |
|---|---|
AUTOBOT_INSTALL_BRANCH=<branch> |
Same as --branch=
|
SLM_ADMIN_PASSWORD=<pass> |
The admin password itself, not a file path (unlike --admin-pass-file=, which names a file). AUTOBOT_SLM_ADMIN_PASSWORD still works but is a deprecated alias (#19318) |
AUTOBOT_INSTALL_INTERFACE=<iface> |
Pick the network interface by name instead of the menu |
OVERRIDE_IP=<ip> |
Skip IP detection and use this address |
NETWORK_SUBNET=<cidr> / NETWORK_GATEWAY=<ip>
|
Use this network instead of detecting it. The subnet is the source the firewall rules allow, so if it cannot be detected the installer stops and asks for these instead of guessing |
Headless host with more than one interface (a Docker bridge counts): the installer cannot show its menu without a terminal, and sudo drops variables set before it. Pass the choice after sudo:
curl -fsSL https://raw.githubusercontent.com/mrveiss/AutoBot-AI/main/install.sh | sudo AUTOBOT_INSTALL_INTERFACE=eth0 bash
curl -fsSL https://raw.githubusercontent.com/mrveiss/AutoBot-AI/main/install.sh | sudo bash -s -- --ip=<address>All output is logged to /var/log/autobot/install-<timestamp>.log.
For single-node or development setups, Docker Compose runs the stack without the installer, Ansible or systemd.
Requirements: Docker Engine 24.0+ with the Compose v2 plugin (docker compose, not
the legacy docker-compose v1). Memory depends on what you start — the figures below are
the containers' configured memory limits (ceilings, not measured use), and building the
images needs headroom on top:
| What you start | Containers | Memory limits (sum) | Measured use | Host RAM |
|---|---|---|---|---|
SLM web GUI only (up -d autobot-slm-gui) |
SLM, its GUI, Redis, PostgreSQL | ~3.1 GB | ~215 MiB idle just after start (CI); ~414 MiB with the SLM restarting (an external test) | 1 GB+ free to run; building the images needs more (not measured) |
| Full stack | backend, worker, celery-beat, SLM, frontend, Redis, PostgreSQL, ChromaDB | ~9 GB | not measured | 16 GB recommended |
bash docker/generate-secrets.shThis writes the gitignored docker/.env.secrets: unique signing secrets and passwords,
and AUTOBOT_DOCKER_MGMT_PREFIX, a private /24 for the stack's management network that
overlaps none of this host's routes or existing Docker networks. Compose refuses to start
without it; there is no built-in default range, because a fixed one can collide with your
LAN and cut the host off the network. To choose the range yourself, set
AUTOBOT_DOCKER_MGMT_PREFIX=<first three octets> (e.g. 10.77.3) before running the
script. Keep the file: every command below passes it.
It also holds AUTOBOT_ADMIN_PASSWORD, the password of the main app's first admin
account (user admin). The backend creates that account on its first start. To read it:
grep '^AUTOBOT_ADMIN_PASSWORD=' docker/.env.secretsLog in to the main app at http://localhost with admin and that password, then change
it. A stack started without the line has no main-app account; add the line with
bash docker/generate-secrets.sh (it keeps every value already in the file) and restart the
backend.
Every credential compose needs comes from this file; none has a built-in default. If one is
missing, docker compose stops with an error that names it (#17793).
Upgrading a stack that already has data. An existing Postgres volume keeps the database
password it was created with and ignores a new one. So if docker/.env.secrets has no
AUTOBOT_DB_PASSWORD line, generate-secrets.sh refuses to create one while the Postgres
volume exists. Add the password the stack already uses (a stack started from the old tracked
default used autobot), then rerun the script to add any other missing line:
echo 'AUTOBOT_DB_PASSWORD=<the password this stack already uses>' >> docker/.env.secrets
bash docker/generate-secrets.shStart only the Service Lifecycle Manager and its web GUI, then add the rest of the fleet from the GUI's Setup Wizard:
git clone https://github.com/mrveiss/AutoBot-AI.git
cd AutoBot-AI
bash docker/generate-secrets.sh
docker compose --env-file docker/.env.docker --env-file docker/.env.secrets up -d --build autobot-slm-guiThe SLM GUI is then at http://localhost:8080/slm/. It has its own ports, so it runs alongside the full stack's frontend, and it starts with the full stack too. Change them with AUTOBOT_DOCKER_SLM_HTTP_PORT and AUTOBOT_DOCKER_SLM_HTTPS_PORT (default 8443). It listens on this machine only by default, because plain HTTP would send the admin login across the network in clear text. To reach it from another machine, select the TLS config below and set AUTOBOT_DOCKER_SLM_BIND_ADDRESS=0.0.0.0.
To serve it over HTTPS, put a certificate in docker/certs/ (autobot.crt and autobot.key;
bash docker/certs/generate-self-signed.sh makes a self-signed pair for testing) and select
the TLS config. Port 80 then redirects to HTTPS:
AUTOBOT_DOCKER_SLM_NGINX_CONF=./docker/nginx/nginx-slm-ssl.conf \
docker compose --env-file docker/.env.docker --env-file docker/.env.secrets up -d autobot-slm-guiThe GUI is then at https://localhost:8443/slm/. Open that address directly: the plain-HTTP redirect goes to the default HTTPS port, which on a full stack is the frontend. The full stack's frontend switches to TLS the same way, with
AUTOBOT_DOCKER_NGINX_CONF=./docker/nginx/nginx-ssl.conf.
Run the same up command. A one-time step, autobot-slm-postgres-copy, copies the SLM's databases out of autobot-postgres before the SLM starts, and leaves the originals where they are. If autobot-postgres isn't running it stops and says so, and the SLM waits: start it and run up again. After that the SLM no longer needs it to start.
Keep SLM_DB_NAME at its current value for this first start: it names the database that gets copied. Compose backups you take yourself need to include the new slm_postgres_data volume.
docker compose --env-file docker/.env.docker --env-file docker/.env.secrets up -d --buildThis starts the core services: backend, SLM, the SLM GUI at http://localhost:8080/slm/,
frontend, Redis, PostgreSQL, and ChromaDB.
Optional services are activated with --profile:
# Add a local Ollama LLM server (only for running models on this host)
docker compose --env-file docker/.env.docker --env-file docker/.env.secrets --profile ollama up -d --build
# Add Prometheus + Grafana monitoring
docker compose --env-file docker/.env.docker --env-file docker/.env.secrets --profile monitoring up -d --buildWhich AI providers to use is your choice: local, hybrid or cloud (#15494). Out of the box,
every LLM tier points at autobot-ollama (docker-compose.yml, the AUTOBOT_OLLAMA_* and
AUTOBOT_LLM_* endpoints), which only runs with --profile ollama. Without that profile, either
point AUTOBOT_OLLAMA_HOST at an Ollama server you run, or use Anthropic:
ANTHROPIC_API_KEY is the one provider key compose passes to the backend. Then select the
provider in SLM Admin > Settings > LLM. With the ollama profile, Ollama starts empty:
pull the models docker/.env.docker names, or the ones you set there instead:
# every model docker/.env.docker names, read from the file itself (about 21 GB with the defaults)
sed -n 's/^AUTOBOT_[A-Z_]*_MODEL=//p' docker/.env.docker | sort -u | \
xargs -n1 docker compose --env-file docker/.env.docker --env-file docker/.env.secrets exec -T autobot-ollama ollama pull| Service | URL |
|---|---|
| Frontend (user UI) | http://localhost |
| SLM Admin | http://localhost/slm/ |
| Backend API | http://localhost/api |
| RedisInsight | http://localhost:8001 |
| Ollama |
http://localhost:11434 (profile: ollama) |
| Grafana |
http://localhost:3000 (profile: monitoring) |
Copy the override template to enable live-reload for frontend and backend code:
cp docker-compose.override.example.yml docker-compose.override.yml
docker compose --env-file docker/.env.docker --env-file docker/.env.secrets up -dEdit source files on the host and changes are reflected inside the containers automatically.
Every command above passes --env-file docker/.env.docker. That is the only Docker env file
(#18555). To change a value, edit a copy of it and pass the copy with --env-file instead.
.env.example is the reference for native installs, not for Docker. Native-install development
tooling reads .env.base (the shared keys) and then one overlay -- .env.localhost, .env.native-vm
or .env.network -- in that order (#18555).
After the installer finishes, open the SLM web UI in your browser:
https://<server-ip>/slm/
Log in with the admin credentials printed at the end of the install. On first login the setup wizard launches automatically and guides you through:
| Step | Action |
|---|---|
| Welcome | Overview of the setup process |
| Add Nodes | Enter hostname/IP and SSH credentials for each fleet node |
| Test | Verify SSH connectivity to every node |
| Enroll | Install the AutoBot agent on each node |
| Roles | Choose which role(s) each node performs |
| API Keys | Configure the secrets the fleet needs |
| Provision | Run Ansible provisioning across the fleet |
| Verify | Confirm all nodes and required roles are healthy |
| Done | Setup finished — redirects to Fleet Overview |
You can skip the wizard at any time and return to it later from Settings > General > Launch Wizard.
To start the wizard over from the first step, use Settings > General > Reset Wizard in the SLM web UI.
Over the API, log in to the SLM first. The response's access_token is the bearer token
(an account with MFA enabled gets an MFA challenge instead; use the UI for that one). These
commands send the admin password and a token, so run them on the SLM server itself: the
installer's certificate is self-signed, and -k (skip certificate checks) is only safe over
loopback. From another machine, install a certificate from a CA you trust, drop -k, and use
the server's name instead of 127.0.0.1. --fail makes a rejected login or reset exit non-zero
instead of looking successful:
TOKEN=$(curl -sSk --fail -X POST https://127.0.0.1/slm/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"username": "admin", "password": "<password>"}' | python3 -c 'import json,sys; print(json.load(sys.stdin)["access_token"])')
curl -sSk --fail -X POST https://127.0.0.1/slm/api/setup/reset -H "Authorization: Bearer ${TOKEN}"- First login to the main app, and where the chat UI is: README: First login.
- First steps: Quick Start · settings and the AI provider: Configuration · problems: Troubleshooting.
- Upgrades, backups and recovery: README: Running AutoBot.
After a successful install the following paths are created:
/opt/autobot/
├── code_source/ # Git clone of AutoBot-AI
├── autobot-slm-backend/ # SLM backend (FastAPI + Ansible)
├── autobot-slm-frontend/ # SLM frontend (Vue 3, built)
├── venv/ # Python virtual environment
└── .autobot-installed # Install marker (prevents re-install)
/etc/autobot/
└── slm-secrets.env # Generated admin credentials + secrets
/var/log/autobot/
└── install-*.log # Installer logs
| Service | Description |
|---|---|
autobot-slm-backend |
FastAPI backend (systemd) |
nginx |
Reverse proxy + static frontend |
postgresql |
Database |
prometheus, grafana-server, node_exporter
|
Monitoring, installed by phase 4 (alertmanager only when monitoring_install_alertmanager is set) |
Check service status:
sudo systemctl status autobot-slm-backend
sudo systemctl status nginx
sudo systemctl status postgresql
sudo systemctl status prometheus grafana-server node_exporterThe installer creates the autobot service account and gives it unrestricted passwordless
root: it writes autobot ALL=(ALL) NOPASSWD:ALL to /etc/sudoers.d/autobot.
Why it is that broad today:
- the SLM deploys and updates hosts with Ansible using
become, and that runs arbitrary module code as root throughsudo /bin/sh -c ..., which a sudoers command list cannot usefully restrict; - the builtin updater and the agent's privileged tasks run commands as root through
sudo -n.
Treat the autobot account as root-equivalent: anyone who can act as it can act as root on
this host. Narrowing the grant without breaking deploys is designed in #19245.
To audit it:
sudo cat /etc/sudoers.d/autobot # exactly the one line above, mode 0440
sudo -l -U autobot # what the account may runTo remove it, run sudo rm /etc/sudoers.d/autobot. Fleet deploys, the builtin updater and
privileged agent tasks then stop working on this host until it is restored. The uninstaller
removes it along with the account it created (see below).
sudo /opt/autobot/code_source/install.sh --uninstall # shows the plan, then asks
sudo bash /opt/autobot/code_source/scripts/uninstall.sh --dry-run # only shows what would go
sudo bash /opt/autobot/code_source/scripts/uninstall.sh --purge-data # also your AutoBot dataThe uninstaller first prints its plan, then asks you to type UNINSTALL. --yes skips the
question for scripted use. Without a terminal and without --yes, it refuses instead of
proceeding.
By default it removes AutoBot's services and units, its code, configs, nginx sites, sudoers files and the apt sources it added. Your data stays unless you add a flag:
| Flag | Also removes |
|---|---|
--purge-data |
AutoBot's databases; the whole /opt/autobot tree, including anything else in it (by default only AutoBot's own code there goes; its backups, db-backups, snapshots, data, models, plugins, .env, config, certificates, any folder AutoBot does not know as its code, and the data inside its code folders -- the backends' data and .env, the ChromaDB store -- stay); /etc/autobot (secrets and credentials); its state and backups elsewhere; and the accounts the installer created, with their homes. PostgreSQL itself only if every cluster was inspected and holds nothing but AutoBot's databases and roles, and its directories only if empty afterwards |
--purge-shared |
grafana, prometheus, node-exporter, redis-stack and python3-psycopg2, with their data. Nothing records who installed them, so they stay by default |
It never removes:
-
An account it did not create. The installer records the
autobotaccount only if it created it, in/etc/autobot/install-record. On a machine whereautobotalready existed, for example your own login, the account and its home stay. An install made before this record existed has no record, so no account, recorded package or recorded apt source is removed there. -
More than it asked apt for. If purging a package would also remove something else, the
purge is skipped and the plan names it. No
apt autoremoveis run. -
nginx, the base packages the installer needs (git, curl, openssh-server, ...),
ollama, thedockerandintel-openvinosources, anddeadsnakesunless the installer recorded adding it. Nor the service accounts the roles create (prometheus, node_exporter, ...).
A partial install that never got as far as cloning the code has no uninstaller copy on the
machine; install.sh --uninstall says so instead of guessing.
The log is written to /var/tmp/autobot-uninstall-<timestamp>.log, which survives the uninstall.
Check the Ansible log:
tail -100 /var/log/autobot/install-*.logCommon causes:
- Missing internet access (package downloads fail)
- Port 5432 already in use (existing PostgreSQL)
- Insufficient disk space
# Verify backend is running
sudo systemctl status autobot-slm-backend
# Check nginx
sudo nginx -t
sudo systemctl status nginx
# Test the SLM backend's health through nginx (/slm/api/ is the SLM; /api/ is the main
# backend, which exists only once the wizard has provisioned it)
curl -sk https://localhost/slm/api/healthThe wizard only redirects on first run (before setup_wizard_completed is set
to true in the database). To force it, reset it as described in
Resetting the Wizard, then refresh the browser.
Symptom: a service restarts in a loop, and its log says it cannot reach PostgreSQL at autobot-postgres:5432 (or Redis, or another service), naming the host and port it tried and
whether the attempt timed out, was refused, or the name did not resolve.
-
Timed out: nothing answered in time. A timeout alone does not say why; possible causes
include packets being dropped, a target host or container that is down or overloaded, or
routing that leads nowhere. One common cause is a host firewall whose forwarding policy drops
container-to-container traffic. Check
sudo iptables -S FORWARD(a-P FORWARD DROPwith no Docker accept rules points there), and if so allow traffic on the Docker bridges, or restore Docker's own chains withsudo systemctl restart docker. -
Refused: the target container is not listening yet, or not running. Check
docker compose --env-file docker/.env.docker --env-file docker/.env.secrets psand that container's logs. - Did not resolve: Docker's DNS could not find the name. Possible causes include the two containers not sharing a network, the target service not being started (or a different service name), or a host DNS problem. Check that the name matches a service in the compose files, and start the whole stack with the same compose files and env files, so every service joins the networks it declares.
Use the --reinstall flag to bypass the "already installed" check:
sudo ./install.sh --reinstallThis does not destroy data — it re-runs all phases and overwrites code and configuration while preserving the database.