Odysseus AI Docker Setup: 7 Checks Before You Expose the Workspace

Use Docker when you want a repeatable local Odysseus AI stack

Choose Docker if you want the official quick-start flow, isolated service dependencies, and a setup that can be rebuilt without guessing which Python or system package changed on the host. The current public README presents Docker Compose as the first quick-start path, which makes it the safest default for a clean first attempt.

Do not choose Docker because you think it removes every setup decision. You still need to know which branch you cloned, which environment file is active, which port the web UI uses, where the admin password appears, and whether a model backend such as Ollama is running inside the stack or on the host machine.

The practical rule is simple: prove the web app first, prove the model endpoint second, and expose nothing beyond localhost until the private services around the workspace have been reviewed.

Run Docker Compose in a clean, inspectable order

Start from the official repository rather than a random zip or copied command block. Odysseus AI is moving quickly, and setup details such as branch choice, GPU overlays, ports, and service names can change faster than third-party tutorials. Keep your first run boring so that errors are easy to isolate.

If you are on Windows, make sure Docker Desktop is actually running before you clone and build. If you are on macOS or Linux, confirm the Docker daemon is available and that the repository is stored somewhere Docker can read without permission surprises.

1. Clone the repository you intend to run

Use the official repository, then decide whether you want the newest dev branch or a curated main branch before editing files.

git clone https://github.com/pewdiepie-archdaemon/odysseus.git
cd odysseus

2. Create the environment file

Copy the example file so Compose and the app read explicit defaults. Keep secrets out of screenshots and do not commit your edited .env file.

cp .env.example .env

3. Build and start the stack

The first build can take a while because images and dependencies are downloaded. Let it finish before opening multiple troubleshooting tabs.

docker compose up -d --build

4. Check service health and first credentials

Open the local UI only after containers are healthy. The generated first admin password is printed in the Odysseus service logs.

docker compose ps
docker compose logs odysseus

Understand .env, port 7000, and what should actually be reachable

The web UI is the part most users need in the browser. In the public quick start, the expected local URL is http://localhost:7000 once containers are healthy. If that port is already occupied, change the documented app port setting in .env instead of editing random generated files.

A Compose stack may include supporting services for search, notifications, storage, or vector data. Those services are not meant to become public entry points just because the web UI works. Before any reverse proxy or LAN exposure, inspect the Compose file and confirm which ports are bound to the host.

Connect host Ollama without confusing container localhost

Ollama is a separate model server in the common Docker setup. If Ollama runs on the host and Odysseus AI runs inside a container, localhost inside the container is not the host machine. That is why Docker-to-host instructions often use host.docker.internal for the base URL.

Test in layers. First confirm Ollama responds on the host. Then confirm the container can reach the host endpoint. Only after that should you save the model provider settings inside Odysseus AI.

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

Know what survives rebuilds, updates, and restarts

Docker makes rebuilds easy, but a workspace is not disposable once you add accounts, settings, documents, memories, or local configuration. Before updating, identify which named volumes or mounted folders hold application state. Back them up before major changes.

Use Compose commands with intent. A normal restart is different from removing volumes. When you are only refreshing the app image, do not run cleanup commands that remove persistent data unless you already exported what matters.

First-boot troubleshooting matrix

Most first-run errors become easier when you separate build, container health, browser access, login credentials, and model routing. Fix the earliest failing layer before changing later settings.

Security checklist before LAN, tunnel, or reverse-proxy access

A self-hosted AI workspace can touch files, prompts, documents, model endpoints, and agent tools. Local control is valuable only when the deployment boundary is intentional. Do not treat a successful localhost test as a production deployment.

The safest early pattern is to bind only the web UI you need, keep helper services private, change first credentials, enable HTTPS for remote access, and avoid publishing raw model or database ports. If you cannot explain each exposed port, keep the stack local.

1. Change or set the admin credential before allowing anyone else to reach the UI.
2. Check docker compose ps and the Compose file for every host port binding.
3. Keep ChromaDB, notification services, model servers, and other helper services off the public internet.
4. Use HTTPS and a trusted reverse proxy before remote access.
5. Keep .env, logs, and screenshots with tokens or generated passwords out of Git and public posts.
6. Back up named volumes before upgrades, migrations, or destructive cleanup.