Docker Compose — Cloud

Use a cloud AI provider for LLM inference while keeping everything else (memory, voice processing, the UIs) on your server. Supported providers: OpenAI, Anthropic, and Google Gemini.

Requirements:

  • Docker and Docker Compose
  • An API key from your chosen provider

One-line install

# OpenAI — handles everything (LLM, STT, TTS, embeddings)
export OPENAI_API_KEY=sk-...
curl -fsSL https://raw.githubusercontent.com/achetronic/magec/main/scripts/install.sh | bash -s -- --openai

# Anthropic — LLM only (STT, TTS, embeddings stay local)
export ANTHROPIC_API_KEY=sk-ant-...
curl -fsSL https://raw.githubusercontent.com/achetronic/magec/main/scripts/install.sh | bash -s -- --anthropic

# Google Gemini — LLM only (STT, TTS, embeddings stay local)
export GEMINI_API_KEY=AI...
curl -fsSL https://raw.githubusercontent.com/achetronic/magec/main/scripts/install.sh | bash -s -- --gemini

What runs where

Each provider mode disables different local services. Redis and PostgreSQL always run locally because they store your data.

OpenAI mode

OpenAI handles everything: LLM, speech-to-text (Whisper), text-to-speech, and embeddings. No local AI containers needed.

Container Status
magec, redis, postgres Running
ollama, parakeet, tts Disabled

Anthropic / Gemini mode

These providers only offer LLM inference. Speech-to-text (Parakeet), text-to-speech (Edge TTS), and embeddings (nomic-embed-text via Ollama) still run locally.

Container Status
magec, redis, postgres, ollama, parakeet, tts Running
ollama-setup Downloads nomic-embed-text only (no LLM model)
With Anthropic and Gemini, the first start still downloads the nomic-embed-text model (~270 MB) for embeddings. This is much faster than the ~5 GB download in fully local mode.

Manual setup

OpenAI

mkdir magec && cd magec

curl -fsSL https://raw.githubusercontent.com/achetronic/magec/main/docker/compose/docker-compose.yaml \
  -o docker-compose.yaml
curl -fsSL https://raw.githubusercontent.com/achetronic/magec/main/docker/compose/docker-compose.openai.yaml \
  -o docker-compose.override.yaml
curl -fsSL https://raw.githubusercontent.com/achetronic/magec/main/docker/compose/config.yaml \
  -o config.yaml

OPENAI_API_KEY=sk-... docker compose up -d

Anthropic

mkdir magec && cd magec

curl -fsSL https://raw.githubusercontent.com/achetronic/magec/main/docker/compose/docker-compose.yaml \
  -o docker-compose.yaml
curl -fsSL https://raw.githubusercontent.com/achetronic/magec/main/docker/compose/docker-compose.anthropic.yaml \
  -o docker-compose.override.yaml
curl -fsSL https://raw.githubusercontent.com/achetronic/magec/main/docker/compose/config.yaml \
  -o config.yaml

ANTHROPIC_API_KEY=sk-ant-... docker compose up -d

Gemini

mkdir magec && cd magec

curl -fsSL https://raw.githubusercontent.com/achetronic/magec/main/docker/compose/docker-compose.yaml \
  -o docker-compose.yaml
curl -fsSL https://raw.githubusercontent.com/achetronic/magec/main/docker/compose/docker-compose.gemini.yaml \
  -o docker-compose.override.yaml
curl -fsSL https://raw.githubusercontent.com/achetronic/magec/main/docker/compose/config.yaml \
  -o config.yaml

GEMINI_API_KEY=AI... docker compose up -d

Set up your first agent

Open the Admin UI at http://localhost:8081.

OpenAI mode

Create one backend that handles everything:

Field Value
Name OpenAI
Type openai
API Key Your OpenAI key
URL (leave empty)

Create an agent:

Field Value
Name Assistant
LLM Backend OpenAI
LLM Model gpt-4.1-mini
Transcription Backend OpenAI
Transcription Model whisper-1
TTS Backend OpenAI
TTS Model tts-1
TTS Voice nova

Create a memory provider for embeddings:

Field Value
Embedding Backend OpenAI
Embedding Model text-embedding-3-small

Anthropic mode

You need three backends — Anthropic for LLM, local services for everything else:

Backend 1 — Anthropic (LLM):

Field Value
Name Anthropic
Type anthropic
API Key Your Anthropic key

Backend 2 — Parakeet (STT):

Field Value
Name Parakeet
Type openai
URL http://parakeet:8888

Backend 3 — Edge TTS:

Field Value
Name Edge TTS
Type openai
URL http://tts:5050
API Key (leave empty)

Create the agent mixing these backends:

Field Value
LLM Backend Anthropic
LLM Model claude-sonnet-4-20250514
Transcription Backend Parakeet
Transcription Model nvidia/parakeet-ctc-0.6b-rnnt
TTS Backend Edge TTS
TTS Model tts-1
TTS Voice es-ES-AlvaroNeural

For memory, create an Ollama backend (http://ollama:11434/v1) and use it for embeddings with nomic-embed-text.

Gemini mode

Same as Anthropic, but the LLM backend is:

Field Value
Name Gemini
Type gemini
API Key Your Gemini key

And the agent uses:

Field Value
LLM Backend Gemini
LLM Model gemini-2.0-flash

STT, TTS, embeddings, and memory are configured the same as Anthropic mode.

Create a client

For all modes, go to Clients → New:

Field Value
Name My Voice UI
Type Voice UI
Agent Assistant

Copy the pairing token, open http://localhost:8080, paste it, and start talking.

Environment variables

API keys are passed through environment variables. The Docker Compose override files reference them automatically:

services:
  magec:
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}

You can set them in a .env file in the same directory as your docker-compose.yaml:

OPENAI_API_KEY=sk-...

Or export them in your shell before running docker compose up.

Managing the deployment

Same as the local deployment — see Docker Compose — Local: Managing the deployment.

Next steps