How to Run Odysseus AI: Choose a Path, Start Safely, Verify the Workspace

Choose Docker, native, or a platform guide first

The official project presents Docker Compose as the most repeatable starting point for many users. It keeps the application and supporting services in a known stack, makes a clean rebuild easier, and reduces the number of host packages you must manage. The tradeoff is that containers change the meaning of localhost: a service inside the Odysseus network does not automatically see the same localhost as your browser or host operating system.

Native setup is useful when you need direct process control, easier Python-level debugging, or the local acceleration behavior of a specific operating system. It also makes host paths and ports feel more obvious. The cost is that you own the Python environment, dependency versions, service processes, and cleanup. Windows users should usually follow the dedicated Windows guide because WSL2, Docker Desktop, PowerShell, and a host Ollama process can create several network layers at once.

Run the preflight before installation

A failed first run is often an environment problem rather than an Odysseus problem. Before cloning or starting containers, decide where the application will live, where persistent data should remain, and whether the model server is local, remote, or not needed yet. Do not add every optional integration during the first boot; a smaller working baseline gives you a useful error boundary.

Check that the operating system has enough free storage for the source tree, containers, logs, model files, and future database or document data. If you plan to use a local model, treat its RAM and VRAM needs separately from the workspace process. The requirements guide explains why a lightweight UI can coexist with a much heavier inference workload.

Also decide your access boundary. The safest first run is a browser on the same machine using a loopback address. LAN access, a reverse proxy, Tailscale, or public exposure should come later, after the admin password is changed and you know which process owns each port.

• Confirm Git, Docker Compose or the native runtime required by your chosen path.
• Reserve a persistent folder for the repository, .env file, volumes, logs, and backups.
• Keep the first browser test on localhost; do not bind every service to 0.0.0.0 by habit.
• Write down whether Ollama and SearXNG will run natively, in Docker, or on another host.
• Have the official repository and setup guide open so you can compare commands with the current branch.

Install and start the workspace

For a first run, the Docker path is usually the shortest route to a repeatable baseline. Clone the official repository, inspect the current README, copy the example environment file when the project provides one, and start the Compose stack. Keep the repository branch and setup instructions aligned; do not invent a release version or assume that a community tutorial matches the current development branch.

A native run follows the same logic with more host responsibility: create the supported Python environment, install the documented dependencies, run the setup step, and start the application process. On Windows, use the project launcher or the dedicated Windows instructions instead of mixing PowerShell commands from a Linux guide with a Docker Desktop container.

1. Start only the baseline

   Do not add a reverse proxy, LAN binding, model download, and search provider at the same time. The first goal is a healthy workspace process.

2. Read the logs before changing ports

   If the browser cannot connect, inspect the application and container logs first. A port change is not a fix when the process exited during dependency loading.

3. Keep the source branch visible

   The official project may distinguish a development branch from a curated main branch. Verify the branch and current setup notes on the official repository before repeating a command from an older article.

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
./start-macos.sh

Connect Ollama and search services one at a time

Once the workspace itself opens, add the model backend. If Ollama runs natively on the same host as a native Odysseus process, localhost may be the correct endpoint. If Odysseus runs inside Docker while Ollama runs on the host, localhost points back to the container; the Docker guide documents the host gateway form to use instead. Test the endpoint from the same network namespace as the application, not only from your browser.

Search is a separate service boundary. A bundled SearXNG container can usually be addressed by its Compose service name, while an external SearXNG instance needs a URL reachable from the Odysseus process. A green browser page does not prove that model inference or web search works. Run one small model request and one small search test, then save the working endpoint and the failure symptom.

Do not expose Ollama or SearXNG simply because the workspace is reachable. Treat model and search endpoints as separate services with their own authentication, network binding, and update decisions.

Verify the first login before real work

The first login is an operational checkpoint, not a formality. Open the documented local port from the same machine, confirm that the page is the Odysseus workspace you just started, and change any temporary admin password immediately. If the page is blank or a reverse proxy is involved, go back to the direct local address before debugging the proxy.

After authentication, confirm the settings screen can see the services you intend to use. Start with a bounded task that does not need sensitive files: ask for a short summary, check the model response, inspect the plan or proposed changes, and stop if the output is not explained. This verifies the whole path from browser to workspace to model without turning the first test into a risky automation job.

1. Reach the local page

   Use the port documented by the current setup path, commonly a localhost address. If the port differs, trust the current repository output and logs rather than an old blog post.

2. Change credentials

   Replace the generated or temporary admin password before any LAN, VPN, or reverse-proxy experiment.

3. Test the model

   Run one small prompt and confirm the selected provider and model are the ones you intended to use.

4. Test the workflow

   Open a harmless workspace or sample project, review the plan and file access, and keep approval manual until the behavior is familiar.

Build a repeatable run workflow

A reliable run workflow separates four decisions: machine readiness, application startup, service connectivity, and user approval. When those decisions are mixed together, every error looks like a model error. When they are separated, you can tell whether the process failed to start, the browser cannot reach it, the model endpoint is wrong, or the workspace is behaving as designed.

Keep a small runbook beside the repository. Record the chosen path, the local URL, the branch or commit you tested, the model endpoint, the search endpoint, the volume or data directory, and the command that stops the stack. This turns the next restart into a known procedure instead of a memory test.

Troubleshoot the common run failures

Most first-run failures fall into a small set of categories: the process is not healthy, the browser is using the wrong port, a container is using a different localhost, an optional service is unreachable, or a credential/volume choice is being mistaken for an application bug. Start with the smallest failing layer and avoid changing several variables at once.

If you are following a video or community guide, compare its branch, port, environment variables, and service names with the official repository. A guide can be useful and still be stale. The goal is not to make an old command work at any cost; it is to find the current supported path and record the difference.

Update without losing control

There is no universal safe update command that replaces reading the current project instructions. Before pulling changes or rebuilding containers, back up the data that matters, note the tested branch or commit, and check whether environment variables or service names changed. Treat a rebuild as a stateful operation when volumes, databases, documents, or credentials are involved.

For a Docker run, stop and inspect the stack before recreating it. For a native run, preserve the virtual environment and repository changes you understand, then update dependencies deliberately. If you need a public or team-facing deployment, add authentication, HTTPS, network controls, and a rollback plan before the service leaves localhost.