Cicero

Open WebUI + Hermes Agent (DeepInfra) via Traefik

This stack runs Open WebUI as a chat frontend connected to Hermes Agent (inside Docker) backed by the DeepInfra LLM provider. All public-facing services are exposed through an existing Traefik reverse proxy using the traefik_proxy network.

---

Prerequisites

• Docker & Docker Compose
• A working Traefik instance with traefik_proxy network (your existing setup)
• A DeepInfra API key (get one here)

---

CI/CD (Forgejo Actions)

This repository includes a Forgejo Actions workflow (.gitea/workflows/deploy.yml) that auto-deploys on every push to main.
Configure the following in your Forgejo repository Settings → Secrets and variables:

Type	Name	Description
Secret	HERMES_API_SERVER_KEY	Random API key for Hermes ↔ Open WebUI communication
Secret	DEEPINFRA_API_KEY	Your DeepInfra API key
Variable	CICERO_DIR	Absolute host path for persistent data (e.g. /opt/cicero)
Variable	HERMES_HOST	Public hostname for Hermes dashboard (e.g. hermes.teurnia.net)
Variable	WEBUI_HOST	Public hostname for Open WebUI (e.g. chat.teurnia.net)

Generate the Hermes API key with nu-shell

# 64-character hex string (32 bytes)
(random bytes 32) | encode hex

# Or a 64-character alphanumeric string
random chars -l 64

Or with openssl:

openssl rand -hex 32

---

Manual deployment

1. Prepare environment

Copy the example file and fill in your secrets:

cp .env.example .env

Edit .env and set:

Variable	How to get it
DEEPINFRA_API_KEY	From DeepInfra Dashboard
HERMES_API_SERVER_KEY	A random secret (see below)
HERMES_HOST	Your Hermes dashboard hostname (e.g. hermes.teurnia.net)
WEBUI_HOST	Your Open WebUI hostname (e.g. chat.teurnia.net)

Generate the Hermes API key with nu-shell

Using nu-shell (recommended):

# 64-character hex string (32 bytes)
(random bytes 32) | encode hex

# Or a 64-character alphanumeric string
random chars -l 64

Or with openssl:

openssl rand -hex 32

---

2. Configure Hermes for DeepInfra

Run the Hermes setup wizard once (interactive, mounts the persistent volume):

docker compose run --rm hermes setup

When prompted:

1. Choose "Custom Endpoint" as the provider.
2. Enter the Base URL: https://api.deepinfra.com/v1/openai
3. Enter your DeepInfra API key.
4. Choose a Model (e.g. meta-llama/Meta-Llama-3.1-70B-Instruct or any model listed on DeepInfra).

This writes ~/.hermes/config.yaml (inside the hermes-data Docker volume) with the DeepInfra settings.

---

3. Start the stack

docker compose up -d

• Open WebUI will be available at: https://<WEBUI_HOST>
• Hermes dashboard (if enabled): https://<HERMES_HOST>

---

4. First-time Open WebUI setup

1. Open https://<WEBUI_HOST> in your browser.
2. Create the first admin account.
3. The Hermes agent model should appear in the model dropdown automatically because the connection is pre-configured via environment variables.
4. Select the model and start chatting.

---

5. Verify the connection

Check that Hermes is healthy:

docker compose exec hermes curl -s http://localhost:8642/health
# Expected: {"status": "ok"}

Check that models are listed:

docker compose exec hermes curl -s -H "Authorization: Bearer $HERMES_API_SERVER_KEY" http://localhost:8642/v1/models
# Expected: {"object":"list","data":[{"id":"hermes-agent", ...}]}

---

6. Enable the Hermes Dashboard (optional)

Uncomment in compose.yml:

environment:
  - HERMES_DASHBOARD=1
labels:
  - "traefik.http.routers.hermes-dashboard.rule=Host(`${HERMES_HOST}`)"
  ...

Then recreate:

docker compose up -d

---

7. Maintenance

View logs:

docker compose logs -f hermes
docker compose logs -f open-webui

Restart a service:

docker compose restart hermes

Update images:

docker compose pull
docker compose up -d

Reset Open WebUI (wipes all data):

docker compose down -v
# Warning: this deletes the open-webui-data volume

---

Notes

• Ollama is disabled (ENABLE_OLLAMA_API=false) so only the DeepInfra-backed Hermes agent appears in the model picker.
• No ports are published on the host; Traefik is the sole entry point.
• Open WebUI talks to Hermes over the internal Docker network (http://hermes:8642/v1), so host.docker.internal is not needed.
• shm_size: 1gb is set for Hermes so Playwright/Chromium browser tools work correctly.

---

Troubleshooting

No models appear in the dropdown

• Check that the Hermes API server is running: docker compose logs hermes | grep "API server listening"
• Ensure API_SERVER_KEY in .env is at least 8 characters.
• Verify the Open WebUI connection settings in Admin Settings → Connections → OpenAI.

"Invalid API key" errors

• Make sure OPENAI_API_KEY in Open WebUI matches API_SERVER_KEY in the .env file exactly.
• Remember: Open WebUI persists connection settings in its database after the first launch. Changing .env alone is not enough once the database exists; update the connection in the Admin UI or wipe the open-webui-data volume.

Hermes container exits immediately

• Check logs: docker compose logs hermes
• Common cause: missing or invalid configuration in /opt/data/.env or config.yaml. Run the setup wizard again.

---

Architecture

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   Browser    │      │   Traefik    │      │   DeepInfra  │
│  (User)      │─────▶│  (Proxy)     │─────▶│   (LLM)      │
└──────────────┘      └──────┬───────┘      └──────────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
              ▼              ▼              ▼
      ┌──────────────┐ ┌──────────────┐
      │   Open WebUI │ │    Hermes    │
      │   (Port 8080)│ │  (Port 8642) │
      └──────────────┘ └──────────────┘
              │              │
              └──────────────┘
         (Internal Docker network: traefik_proxy)

• Open WebUI acts as the chat interface.
• Hermes Agent processes requests, decides which tools to use, and calls the DeepInfra API for LLM inference.
• Traefik handles TLS termination and routes public hostnames to the correct containers.