Odysseus AI localhost:7000 Not Working

Last updated: June 5, 2026

If Odysseus AI starts but http://localhost:7000 does not open, do not delete data or reset Docker volumes. Work through the port, container, and bind checks below first.

Quick answer

For Docker installs, run docker compose ps and confirm the web UI is mapped to 127.0.0.1:7000. If another service owns port 7000, set APP_PORT=7001 in .env, recreate the stack, and open http://localhost:7001.

1. Confirm the URL for Your Install Path

Docker Compose

Open http://localhost:7000 unless APP_PORT is set to another host port.

Manual uvicorn

Open the port passed to uvicorn. The documented manual command uses 127.0.0.1:7000.

Apple Silicon start script

The current start-macos.sh path launches at http://127.0.0.1:7860, so localhost:7000 will not respond for that path.

2. Check the Docker Stack

Run this from the Odysseus repository directory:

Copy command

docker compose ps

Look for an odysseus service that is running and mapped to a local host port. If it is restarting or exited, read the logs before changing port settings.

Copy command

docker compose logs --tail 120 odysseus

3. Test the Web Process Directly

Odysseus exposes a health endpoint. A working response means the app is listening and the browser problem is likely URL, cache, extension, or host resolution related.

Copy command

curl -fsS http://localhost:7000/api/health

If localhost behaves strangely, try the loopback IP directly:

Copy command

curl -fsS http://127.0.0.1:7000/api/health

4. Check Whether Another App Owns Port 7000

Port conflicts are common on developer machines. Use the command for your OS:

macOS

Copy command

lsof -nP -iTCP:7000 -sTCP:LISTEN

Linux

Copy command

ss -ltnp | grep ':7000'

Windows

Copy command

netstat -ano | findstr :7000

Do not kill an unknown process until you know what it is. Changing Odysseus to a free port is usually safer than stopping a system service.

5. Move Odysseus to a Free Port

If port 7000 is taken, add this to .env:

Copy command

APP_PORT=7001

Recreate the stack so Docker applies the new host-port mapping:

Copy command

docker compose down
docker compose up -d --build

Then open http://localhost:7001.

6. If You Are Running Natively

For a manual Python install, start uvicorn on loopback and keep the terminal open:

Copy command

python -m uvicorn app:app --host 127.0.0.1 --port 7000

For the Apple Silicon script, use the script's current port:

Copy command

./start-macos.sh
# open http://127.0.0.1:7860

7. Do Not Expose the App While Debugging

Keep the default loopback bind until local access works. Use a LAN or reverse proxy bind only when you intentionally want remote access and authentication is enabled.

Copy command

APP_BIND=127.0.0.1

If you later change to APP_BIND=0.0.0.0, also review the security checklist first.

Verify Against Official Docs

Odysseus is moving fast. For the current Docker port mapping, macOS script port, and environment variable names, check the official GitHub repository.

FAQ

Why does http://localhost:7000 not open after Docker starts?

The usual causes are a container that is still starting, a failed Odysseus container, another local service already using port 7000, or an APP_PORT override in .env. Check docker compose ps and docker compose logs before changing anything.

How do I check whether Odysseus is running?

Run docker compose ps from the Odysseus directory. The odysseus service should be running and mapped to 127.0.0.1:7000 or the APP_PORT value you configured.

What if port 7000 is already taken?

Set APP_PORT=7001 or another free port in .env, then recreate the stack with docker compose down and docker compose up -d --build. Open the new localhost port in your browser.

Why does the macOS start script not use localhost:7000?

The Apple Silicon start-macos.sh path launches at http://127.0.0.1:7860 in the current README. Use localhost:7000 for Docker or manual uvicorn runs unless your .env overrides APP_PORT.

Should I bind Odysseus to 0.0.0.0 to fix localhost?

No. Keep APP_BIND on 127.0.0.1 while troubleshooting local access. Bind to 0.0.0.0 only when you intentionally want LAN or reverse-proxy access and authentication is enabled.

Related Guides

Docker Setup

Install Odysseus with Docker Compose and confirm the expected port mapping.

Find Admin Password

Locate the first login password after the web UI opens.

Troubleshooting

Fix Docker startup, GPU detection, model backend, and login issues.

Windows Guide

Windows-specific Docker Desktop, WSL2, and port troubleshooting notes.