How to install Odysseus AI on a Linux VPS

Install Odysseus AI on a Linux VPS server

In this guide, we will install Odysseus AI on a Linux VPS server with Docker Compose, then expose it cleanly through an HTTPS reverse proxy. The goal is to get a private self-hosted AI workspace that can centralize chat, agents, documents, memory, web research, notes, tasks, calendar, email, and local tools.

Odysseus is an open-source project presented as a self-hosted, local-first, privacy-first AI workspace. It can talk to local models or compatible APIs, run agent tools, use ChromaDB for memory, start SearXNG for web search, and connect to Ollama, vLLM, llama.cpp, OpenRouter, OpenAI, or other endpoints. If you followed our Hermes Agent installation guide, think of Odysseus as the more web-workspace-oriented approach, while Hermes is closer to an autonomous agent reachable from terminal or messaging channels.

Odysseus is still young. The official repository says the dev branch contains the latest development changes but may be unstable, while main is the more stable curated branch. For a VPS you want to keep clean, we will install main by default.

1. What you will have at the end

By the end of this tutorial, you will have:

An Odysseus instance running with Docker Compose.
A web interface protected by authentication.
ChromaDB, SearXNG, and ntfy started with the official stack.
HTTPS access through NGINX, without exposing internal ports directly.
A base ready to connect Ollama, an OpenAI-compatible API, or a remote model server.
Commands for backup, updates, troubleshooting, and hardening.

Odysseus listens on application port 7000 by default. The Docker stack also exposes internal services such as SearXNG, ChromaDB, and ntfy. The important point is not to open all these ports publicly: the Odysseus interface should be the only user-facing entrypoint, ideally behind HTTPS.

2. Recommended prerequisites

Before you start, prepare:

A Linux VPS server with SSH access and sudo rights.
Ubuntu 22.04, Ubuntu 24.04, or Debian 12 if you want to follow the commands as written.
At least 2 GB of RAM to test the interface with API-based models.
Preferably 4 GB to 8 GB of RAM if you also want search, documents, and local processing features.
More RAM and optionally a GPU if you want to serve real local models on the same VPS.
A domain or subdomain, for example odysseus.example.com, if you want clean HTTPS access.

If you use a small VPS without GPU, that is not a blocker. Odysseus can work very well as a private interface connected to an external provider or a remote model server. The GPU mainly matters if you want to download and serve models locally through Cookbook, llama.cpp, vLLM, or a similar runtime.

Update the system first:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git ca-certificates gnupg openssl ufw

3. Install Docker on the VPS

Odysseus recommends Docker for server installations. If Docker is already used in production on your VPS, check the impact before replacing existing packages. On a fresh machine, use this sequence.

sudo apt remove -y $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc podman-docker containerd runc 2>/dev/null | cut -f1)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo systemctl enable --now docker

Check that Docker and Docker Compose are available:

docker --version
docker compose version

If you need more detail about Docker itself, read our dedicated guide: Install Docker on Linux, a practical getting-started guide.

4. Download Odysseus deployment files

The official Odysseus installation relies on the project’s Git repository. This repository contains the complete docker-compose.yml, the SearXNG configuration, GPU scripts, and the files required to start the services used by Odysseus.

Install these files under /opt/odysseus, then give ownership back to your current user so you do not manage everything as root.

sudo apt update
sudo apt install -y git openssl
cd /opt
sudo git clone --branch main https://github.com/pewdiepie-archdaemon/odysseus.git
sudo chown -R "$USER:$USER" /opt/odysseus
cd /opt/odysseus

For this VPS tutorial, stay on main. A dev tag also exists, but it follows the development branch and can move faster.

5. Prepare the `.env` file

Copy the example file:

cp .env.example .env

Then add an explicit configuration for a first deployment behind a reverse proxy. The Odysseus port will stay bound to 127.0.0.1, so it is not exposed directly to the public internet.

ADMIN_PASSWORD=$(openssl rand -hex 24)
SECRET_KEY=$(openssl rand -hex 32)
cat <<EOF >> .env
APP_BIND=127.0.0.1
APP_PORT=7000
AUTH_ENABLED=true
LOCALHOST_BYPASS=false
SECURE_COOKIES=false
ODYSSEUS_ADMIN_USER=admin
ODYSSEUS_ADMIN_PASSWORD=$ADMIN_PASSWORD
SECRET_KEY=$SECRET_KEY
ALLOWED_ORIGINS=http://localhost:7000,http://127.0.0.1:7000
FASTEMBED_CACHE_PATH=/app/data/fastembed_cache
EOF
printf 'Initial admin password: %s\n' "$ADMIN_PASSWORD"

Store the displayed password in a password manager. You can change it later from the Odysseus interface.

Important points:

AUTH_ENABLED=true keeps the page protected by login.
LOCALHOST_BYPASS=false avoids a bypass meant only for local development.
APP_BIND=127.0.0.1 prevents direct exposure of the application port to the public network.
SECURE_COOKIES=false is temporary until HTTPS is active.
FASTEMBED_CACHE_PATH=/app/data/fastembed_cache keeps the FastEmbed cache in the persistent data/ volume. Without this explicit path, Odysseus can show No embedding lanes available errors when memory, RAG, and the tool index initialize.

6. Start Odysseus with Docker Compose

Start the official stack. On the first run, Docker builds the Odysseus image from source, then also starts ChromaDB, SearXNG, and ntfy.

docker compose up -d --build

This first run can take several minutes, especially on a small VPS. Later starts will be faster because Docker reuses the layers it already built.

Check the container state:

docker compose ps

Read the application logs:

docker compose logs --tail=120 odysseus

If you did not define ODYSSEUS_ADMIN_PASSWORD, Odysseus generates a temporary password during first startup. You can find it with:

docker compose logs odysseus | grep -Ei 'password|admin'

At this point, the interface should answer locally from the VPS:

curl -I http://127.0.0.1:7000

You can also test through an SSH tunnel from your own computer:

ssh -L 7000:127.0.0.1:7000 user@vps-address

Then open http://localhost:7000 in your local browser. This is useful for a quick test without exposing the app.

Once the service is running, the login page appears with the admin user created during first startup.

7. Put Odysseus behind NGINX and HTTPS

For clean web access, use a subdomain and a reverse proxy. In the examples, replace odysseus.example.com with your real domain. Before running Certbot, make sure the subdomain DNS already points to the VPS IP address and that port 80 is reachable from the internet.

Install NGINX and Certbot:

sudo apt install -y nginx certbot python3-certbot-nginx

Create the NGINX configuration:

sudo tee /etc/nginx/sites-available/odysseus.conf > /dev/null <<'EOF'
server {
    listen 80;
    server_name odysseus.example.com;

    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:7000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 3600;
        proxy_send_timeout 3600;
    }
}
EOF

Enable the site, test the syntax, then reload NGINX:

sudo ln -s /etc/nginx/sites-available/odysseus.conf /etc/nginx/sites-enabled/odysseus.conf
sudo nginx -t
sudo systemctl reload nginx

Generate the HTTPS certificate:

sudo certbot --nginx -d odysseus.example.com

Once HTTPS is active, update .env to enable secure cookies and allow the public origin:

cd /opt/odysseus
sed -i '/^SECURE_COOKIES=/d;/^ALLOWED_ORIGINS=/d' .env
cat <<'EOF' >> .env
SECURE_COOKIES=true
ALLOWED_ORIGINS=https://odysseus.example.com,http://localhost:7000,http://127.0.0.1:7000
EOF
docker compose up -d

Now open https://odysseus.example.com and sign in with user admin and the password generated earlier.

8. Configure the VPS firewall

Before enabling or changing UFW, always check its current state so you do not lock yourself out of SSH:

sudo ufw status

Allow SSH to keep administrative access, then open web traffic:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

The OpenSSH rule only serves to maintain your administrative SSH access or the SSH tunnel used for testing in this tutorial, and is not required for Odysseus itself.

If UFW is not active yet, enable it only after adding the SSH rule:

sudo ufw enable
sudo ufw status verbose

If your system does not use UFW, you can configure the minimal equivalent with iptables. This SSH rule also serves to preserve your administration access or the tutorial’s tunnel (note that the default port 22 should be adapted if your SSH service listens on a different port):

sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

Do not publish internal ports such as 7000, 8080, 8091, 8100, 11434, or 8000-8020 directly to the internet. Keep them on localhost, inside Docker, behind a VPN, through Tailscale, or behind a controlled reverse proxy.

9. First walkthrough in Odysseus

After signing in, you land on the chat screen. At this point, the installation is running, but Odysseus will not answer yet until at least one model provider is configured.

Make three checks before launching an agent:

Change the admin password if you used a temporary value.
Make sure open signup is disabled if the instance is not meant for multiple users.
Add your first model provider from the settings.

The welcome screen may suggest typing /setup, but depending on the installed version the command alone can return Unknown subcommand. The useful shortcut is to start with the help command or the endpoint helper:

/setup --help
/setup endpoint

You can also go directly through Settings > Add Models. This is the clearest method for a first deployment because it separates local models, external APIs, and connection tests.

Odysseus can work in several ways:

With an OpenAI-compatible API, OpenRouter, DeepSeek, Anthropic, Groq, Gemini, or equivalent provider for a quick start.
With Ollama on the same VPS or another private machine.
With a vLLM, llama.cpp, or other OpenAI-compatible endpoint.
With Cookbook to detect hardware, download models, and prepare a suitable runtime.

If you configure a local model server from Docker, remember that localhost from inside the container is not necessarily the VPS host. For Ollama installed on the same VPS, use http://host.docker.internal:11434/v1, as explained in the next section.

The other modules already open on a fresh instance. Library stores documents, research results, and archived conversations.

Brain contains long-term memory and skills. It becomes genuinely useful once a model and a working embeddings backend are configured.

Deep Research prepares multi-step web research with search engine, rounds, endpoint, and model selection.

Odysseus also includes Compare, a panel that sends the same prompt to several models and compares the answers, including blind testing when multiple models are available.

The Calendar area provides a local-first calendar with week, month, year, and agenda views. CalDAV sync is configured later from the integration settings.

The Tasks module lists scheduled jobs and internal automations: sessions, email, memory, documents, research, and skills. It is also where you can see which jobs are active or paused.

The Email module is also a headline feature, but it requires IMAP/SMTP configuration in Settings > Integrations before it becomes useful. On a fresh instance, it is normal to have no inbox content until an account is connected.

For a small VPS, start with an external provider or a remote model server. On a stronger non-BoxToPlay GPU host, you can later test local model downloading and serving.

10. Connect Ollama to Odysseus

If Ollama runs on the same VPS as Docker, Odysseus must reach it from inside the container. The repository recommends this Odysseus-side URL:

http://host.docker.internal:11434/v1

Ollama must listen on more than its own loopback. On a systemd server, create an override:

sudo mkdir -p /etc/systemd/system/ollama.service.d
sudo tee /etc/systemd/system/ollama.service.d/override.conf > /dev/null <<'EOF'
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
EOF
sudo systemctl daemon-reload
sudo systemctl restart ollama

Do not open port 11434 in the public firewall. The goal is only for the Odysseus container to reach Ollama through the local host/Docker path.

You can also preconfigure the URL in .env:

cd /opt/odysseus
sed -i '/^OLLAMA_BASE_URL=/d' .env
cat <<'EOF' >> .env
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1
EOF
docker compose up -d

Then add or verify the matching provider in Odysseus model settings.

11. Enable GPU options if your VPS supports them

On a BoxToPlay VPS, you can skip this section: our current VPS offers are not sold with GPUs. The options below will not work on a standard BoxToPlay VPS. They only apply to a Linux server that actually has an NVIDIA or AMD GPU with compatible Docker passthrough.

On a CPU-only Linux server, Cookbook can still detect RAM, CPU cores, and suggest compatible or marginal llama.cpp models. This is useful to estimate what can run locally before downloading anything.

For NVIDIA, start with a read-only diagnostic:

cd /opt/odysseus
scripts/check-docker-gpu.sh

To print the required installation commands without running them:

scripts/check-docker-gpu.sh --print-install-commands

To install the NVIDIA runtime and enable the overlay after passthrough validation:

sudo scripts/check-docker-gpu.sh --install-nvidia-toolkit --enable-nvidia-overlay
docker compose up -d --build

For AMD/ROCm, run the diagnostic:

cd /opt/odysseus
scripts/check-docker-amd-gpu.sh

Then add the overlay and the render group GID to .env if the diagnostic asks for it:

RENDER_GID=$(getent group render | cut -d: -f3)
sed -i '/^COMPOSE_FILE=/d;/^RENDER_GID=/d' .env
cat <<EOF >> .env
COMPOSE_FILE=docker-compose.yml:docker/gpu.amd.yml
RENDER_GID=$RENDER_GID
EOF
docker compose up -d --build

One important point: seeing the GPU inside the container does not guarantee that llama.cpp or vLLM will already use CUDA or ROCm. Docker passthrough and model-runtime dependencies are two separate topics.

12. Back up Odysseus cleanly

The important data lives in data/, .env, and depending on your usage, logs/. Before an update or a major change, create an archive.

cd /opt/odysseus
tar --exclude='data/huggingface' --exclude='data/local' -czf "$HOME/odysseus-backup-$(date +%F).tar.gz" .env data logs

The data/huggingface and data/local directories can become very large if you download models or install local engines. Back them up separately if you also want to restore heavy model files and dependencies.

To send the archive to another server:

scp "$HOME/odysseus-backup-$(date +%F).tar.gz" [email protected]:/home/user/backups/

Never publicly share .env, data/, logs, exports, uploads, or screenshots containing API keys.

13. Update Odysseus

Make a backup before updating. With the official installation from the Git repository, fetch the latest files, then rebuild the stack:

cd /opt/odysseus
git checkout main
git pull --ff-only
docker compose up -d --build
docker compose logs --tail=120 odysseus

Afterwards, check the interface and configured providers. If you use dev, expect more frequent changes and keep a fresh archive before every update.

14. Common troubleshooting

If the interface does not respond, check the containers first:

cd /opt/odysseus
docker compose ps
docker compose logs --tail=120 odysseus

If port 7000 is already taken, choose another local port:

cd /opt/odysseus
sed -i '/^APP_PORT=/d' .env
cat <<'EOF' >> .env
APP_PORT=7001
EOF
docker compose up -d

Then update the NGINX proxy_pass to http://127.0.0.1:7001.

If SearXNG blocks startup or stays in error:

docker compose logs --tail=120 searxng
docker compose restart searxng odysseus

If ChromaDB seems unavailable:

docker compose logs --tail=120 chromadb
docker compose restart chromadb odysseus

If Odysseus logs show FastEmbed init failed, No such file or directory: '', or No embedding lanes available, check that .env contains the FastEmbed cache path used in this guide:

cd /opt/odysseus
grep '^FASTEMBED_CACHE_PATH=' .env

The expected value is:

FASTEMBED_CACHE_PATH=/app/data/fastembed_cache

Then restart the container:

docker compose up -d odysseus
docker compose logs --tail=120 odysseus

On first startup, FastEmbed may download a small ONNX model from Hugging Face. A warning about unauthenticated Hugging Face requests is normal if you did not define HF_TOKEN.

If you lost the initial admin password, the cleanest approach is to define a new ODYSSEUS_ADMIN_PASSWORD before real usage. If the instance already contains users and data, handle recovery from the admin interface or the project documentation so you do not overwrite your configuration.

If you lose the administrator password after the initial setup, you can reset the authentication by stopping the service and deleting the data/auth.json file (which will reset the initialization process on the next startup):

cd /opt/odysseus
docker compose down
mv data/auth.json data/auth.json.bak
docker compose up -d

15. Security best practices

Odysseus can handle powerful tools: shell, files, documents, email, calendar, models, webhooks, tokens, and MCP. Treat it like an administration console.

Keep AUTH_ENABLED=true whenever the instance is reachable over the network.
Keep LOCALHOST_BYPASS=false outside local development.
Set SECURE_COOKIES=true as soon as access goes through HTTPS.
Do not expose ChromaDB, SearXNG, ntfy, Ollama, vLLM, llama.cpp, or model APIs directly.
Limit admin accounts and review non-admin privileges.
Enable 2FA if your version and configuration support it.
Do not paste API keys into screenshots, logs, or shared conversations.
Back up .env and data/ regularly, then store archives outside the VPS.

Odysseus is designed with advanced privileged local capabilities, allowing it to interact directly with the file system and run shell commands via its integrated terminal. Treat this interface as a true administration console and do not grant access to untrusted users.

Once this base is ready, Odysseus becomes a private AI workspace you can grow step by step: first a provider-connected interface, then an agent with tools, then eventually a local environment with models, memory, search, and automations.

To host this kind of workspace on a stable machine, a VPS server is a strong base: root access, persistent services, reverse proxy, backups, and progressive scaling. At BoxToPlay, you can start your free VPS trial and build your own self-hosted AI environment at your own pace.

Join the Discussion