diff --git a/.gitignore b/.gitignore index 28bbccd..da2ad4a 100644 --- a/.gitignore +++ b/.gitignore @@ -49,3 +49,4 @@ test/ data/* !data/seeds/ server/data/ +onnxruntime-*/ \ No newline at end of file diff --git a/Makefile b/Makefile index 59f2a9b..a4da719 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: help build build-admin build-voice dev dev-admin dev-voice clean download-model swagger docker-build docker-buildx docker-push postgres redis ollama infra infra-stop infra-clean +.PHONY: help build build-admin build-voice dev dev-admin dev-voice clean download-model swagger docker-build docker-buildx docker-push postgres redis ollama infra infra-stop infra-clean docs docs-stop CONFIG ?= config.yaml @@ -15,6 +15,8 @@ help: @echo " dev-admin Start admin UI dev server (Vite, port 5173)" @echo " dev-voice Start voice UI dev server (Vite, port 5174)" @echo " swagger Regenerate Swagger docs from annotations" + @echo " docs Start documentation site (Hugo, port 1313)" + @echo " docs-stop Stop documentation site" @echo " clean Remove generated files" @echo "" @echo "Models:" @@ -102,6 +104,26 @@ docker-push: @docker buildx build -f docker/build/Dockerfile --platform $(DOCKER_PLATFORMS) -t $(IMAGE_NAME):$(IMAGE_TAG) --push . @echo "Image pushed: $(IMAGE_NAME):$(IMAGE_TAG) [$(DOCKER_PLATFORMS)]" +# Documentation (Docker) + +HUGO_VERSION ?= 0.147.1 +DOCS_PORT ?= 1313 + +docs: + @echo "Starting documentation site on http://localhost:$(DOCS_PORT) ..." + @docker run -d --name magec-docs \ + -p $(DOCS_PORT):1313 \ + -v $(CURDIR)/website:/src \ + hugomods/hugo:$(HUGO_VERSION) \ + hugo server --bind 0.0.0.0 --baseURL http://localhost:$(DOCS_PORT) --disableFastRender + @echo "Documentation site running at http://localhost:$(DOCS_PORT)" + @echo "Stop with: make docs-stop" + +docs-stop: + @docker stop magec-docs 2>/dev/null || true + @docker rm magec-docs 2>/dev/null || true + @echo "Documentation site stopped" + # Infrastructure (Docker) postgres: diff --git a/docker/compose/docker-compose.yaml b/docker/compose/docker-compose.yaml index e34de65..1a7ef6e 100644 --- a/docker/compose/docker-compose.yaml +++ b/docker/compose/docker-compose.yaml @@ -92,8 +92,18 @@ services: - REQUIRE_API_KEY=False restart: unless-stopped + cliproxyapi: + image: eceasy/cli-proxy-api:latest + ports: + - "54545:54545" # OAuth callback (required for login only) + volumes: + - ./cliproxyapi/config.yaml:/CLIProxyAPI/config.yaml + - cliproxyapi_auth:/CLIProxyAPI/auth + restart: unless-stopped + volumes: magec_data: redis_data: postgres_data: ollama_data: + cliproxyapi_auth: diff --git a/scripts/install.sh b/scripts/install.sh index c523b65..5d8782b 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -333,6 +333,42 @@ choose \ LLM_CHOICE="$REPLY" +# ── CLIProxyAPI (use provider subscription as API) ─────────────────────── + +WANT_CLIPROXYAPI=false + +if [[ "$LLM_CHOICE" == "2" || "$LLM_CHOICE" == "3" ]]; then + echo + box_top + box_empty + box_line " Use Your Subscription Instead of an API Key?" "$BOLD" "center" + box_empty + box_sep + box_empty + box_line " Some AI providers offer paid subscriptions" + box_line " (e.g., Claude Max/Pro, ChatGPT Plus) that are" + box_line " separate from their API billing." + box_empty + box_line " CLIProxyAPI is a local proxy that lets you" + box_line " use your existing subscription with Magec" + box_line " instead of paying separately for API access." + box_line " You log in once and Magec can use the models" + box_line " from your subscription." + box_empty + box_line " ${DIM}You can still add a regular API key later${NC}" + box_line " ${DIM}if you prefer.${NC}" + box_empty + box_bottom + echo + + if ask_yn "Enable subscription proxy (CLIProxyAPI)?" "n"; then + WANT_CLIPROXYAPI=true + ok "CLIProxyAPI will be configured" + else + info "Skipped — you can set it up later" + fi +fi + # ═══════════════════════════════════════════════════════════════════════════ # STEP 3 — MEMORY # ═══════════════════════════════════════════════════════════════════════════ @@ -727,6 +763,9 @@ box_empty box_line " ${BOLD}Install method:${NC} $method_label" box_line " ${BOLD}System:${NC} ${os_label} (${arch_label})" box_line " ${BOLD}AI models:${NC} $llm_label" +if $WANT_CLIPROXYAPI; then + box_line " ${BOLD}Subscription proxy:${NC} Enabled (CLIProxyAPI)" +fi box_line " ${BOLD}Conversation memory:${NC} $($WANT_REDIS && echo "Yes" || echo "No")" box_line " ${BOLD}Long-term memory:${NC} $($WANT_POSTGRES && echo "Yes" || echo "No")" box_line " ${BOLD}Voice:${NC} $voice_label" @@ -1314,6 +1353,54 @@ install_binary() { install_onnx_runtime fi + # ── CLIProxyAPI setup (binary) ─────────────────────────────────────── + + if $WANT_CLIPROXYAPI; then + cls + echo + printf " $(badge " SETUP " "$BG_YELLOW" "$FG_BLACK") ${BOLD}Subscription proxy (CLIProxyAPI)${NC}\n" + printf " ${DIM}$(hline '─' "$BOX_W")${NC}\n" + echo + + box_top + box_empty + box_line " CLIProxyAPI runs as a separate service." + box_line " You can run it via Docker or download the" + box_line " binary from GitHub." + box_empty + box_sep + box_empty + box_line " ${BOLD}Option A — Docker (recommended):${NC}" + box_empty + box_line " ${CYAN}docker run -d -p 8317:8317 -p 54545:54545 \\${NC}" + box_line " ${CYAN} -v \$(pwd)/cliproxyapi/config.yaml:\\${NC}" + box_line " ${CYAN} /CLIProxyAPI/config.yaml \\${NC}" + box_line " ${CYAN} -v cliproxyapi_auth:/CLIProxyAPI/auth \\${NC}" + box_line " ${CYAN} --name magec-cliproxyapi \\${NC}" + box_line " ${CYAN} eceasy/cli-proxy-api:latest${NC}" + box_empty + box_sep + box_empty + box_line " ${BOLD}Option B — Binary:${NC}" + box_empty + box_line " ${CYAN}https://github.com/router-for-me/CLIProxyAPI/releases${NC}" + box_empty + box_sep + box_empty + box_line " ${BOLD}After starting, log in to your provider.${NC}" + box_line " ${BOLD}See the guide for supported providers:${NC}" + box_empty + box_line " ${CYAN}https://magec.dev/docs/subscription-proxy/${NC}" + box_empty + box_bottom + echo + + printf " ${DIM}Press Enter to continue...${NC}" + read -r < /dev/tty + + generate_cliproxyapi_config + fi + # ── Generate config ───────────────────────────────────────────────── echo @@ -1458,6 +1545,9 @@ install_containers() { info "Creating configuration files..." generate_docker_compose + if $WANT_CLIPROXYAPI; then + generate_cliproxyapi_config + fi if ! $SKIP_CONFIG; then generate_config_yaml else @@ -1485,6 +1575,18 @@ install_containers() { # CONFIGURATION GENERATORS # ═══════════════════════════════════════════════════════════════════════════ +generate_cliproxyapi_config() { + mkdir -p cliproxyapi + cat > cliproxyapi/config.yaml <<'CLIPROXY' +host: "0.0.0.0" +port: 8317 +auth-dir: "/CLIProxyAPI/auth" +api-keys: + - "sk-magec-local" +CLIPROXY + ok "cliproxyapi/config.yaml" +} + generate_config_yaml() { local voice_enabled="true" [[ "$WANT_VOICE" != true ]] && voice_enabled="false" @@ -1533,6 +1635,7 @@ generate_store_json() { local openai_backend_id="$(gen_uuid)" local anthropic_backend_id="$(gen_uuid)" local gemini_backend_id="$(gen_uuid)" + local cliproxyapi_backend_id="$(gen_uuid)" local parakeet_backend_id="$(gen_uuid)" local tts_backend_id="$(gen_uuid)" @@ -1548,6 +1651,12 @@ generate_store_json() { backend_entries+=("{\"id\":\"${gemini_backend_id}\",\"name\":\"Gemini\",\"type\":\"gemini\",\"url\":\"\",\"apiKey\":\"\"}") fi + if $WANT_CLIPROXYAPI; then + local cliproxyapi_url="http://localhost:8317" + [[ "$INSTALL_METHOD" == "2" ]] && cliproxyapi_url="http://cliproxyapi:8317" + backend_entries+=("{\"id\":\"${cliproxyapi_backend_id}\",\"name\":\"Subscription Proxy\",\"type\":\"anthropic\",\"url\":\"${cliproxyapi_url}\",\"apiKey\":\"sk-magec-local\"}") + fi + if [[ "$WANT_VOICE" == true ]]; then local parakeet_url="http://localhost:5092" local tts_url="http://localhost:5050" @@ -1601,6 +1710,9 @@ generate_store_json() { if [[ "$LLM_CHOICE" == "1" || "$LLM_CHOICE" == "3" ]]; then llm_backend_id="$ollama_backend_id" llm_model="qwen3:8b" + elif [[ "$LLM_CHOICE" == "2" ]] && $WANT_CLIPROXYAPI; then + llm_backend_id="$cliproxyapi_backend_id" + llm_model="claude-sonnet-4-20250514" elif [[ "$LLM_CHOICE" == "2" ]]; then llm_backend_id="$anthropic_backend_id" llm_model="claude-sonnet-4-20250514" @@ -1771,6 +1883,18 @@ generate_docker_compose() { services+=" restart: unless-stopped\n" fi + if $WANT_CLIPROXYAPI; then + services+="\n cliproxyapi:\n" + services+=" image: eceasy/cli-proxy-api:latest\n" + services+=" ports:\n" + services+=" - \"54545:54545\"\n" + services+=" volumes:\n" + services+=" - ./cliproxyapi/config.yaml:/CLIProxyAPI/config.yaml\n" + services+=" - cliproxyapi_auth:/CLIProxyAPI/auth\n" + services+=" restart: unless-stopped\n" + volumes+=" cliproxyapi_auth:\n" + fi + printf "services:\n" > docker-compose.yaml printf '%b' "$services" >> docker-compose.yaml printf "\nvolumes:\n" >> docker-compose.yaml @@ -1908,12 +2032,32 @@ EOF fi box_empty - if [[ "$LLM_CHOICE" == "2" || "$LLM_CHOICE" == "3" ]]; then + if $WANT_CLIPROXYAPI; then + box_sep + box_empty + box_line " ${YELLOW}Action needed:${NC} Log in to your provider." + box_line " See the subscription proxy guide for login" + box_line " commands for each supported provider:" + box_empty + box_line " ${CYAN}https://magec.dev/docs/subscription-proxy/${NC}" + box_empty + box_line " A subscription proxy backend has been" + box_line " pre-configured. After login, it's ready to use." + box_empty + fi + + if [[ "$LLM_CHOICE" == "2" || "$LLM_CHOICE" == "3" ]] && ! $WANT_CLIPROXYAPI; then box_sep box_empty box_line " ${YELLOW}Remember:${NC} Cloud AI providers need API keys." box_line " Add them in Admin Panel → Backends." box_empty + elif [[ "$LLM_CHOICE" == "2" || "$LLM_CHOICE" == "3" ]] && $WANT_CLIPROXYAPI; then + box_sep + box_empty + box_line " ${DIM}Other cloud providers (OpenAI, Gemini) still${NC}" + box_line " ${DIM}need API keys — add them in Admin Panel → Backends.${NC}" + box_empty fi if [[ "$INSTALL_METHOD" == "2" ]] && { [[ "$LLM_CHOICE" == "1" || "$LLM_CHOICE" == "3" ]] || $WANT_POSTGRES; }; then diff --git a/server/agent/agent.go b/server/agent/agent.go index dcdbcf2..9a88877 100644 --- a/server/agent/agent.go +++ b/server/agent/agent.go @@ -413,6 +413,7 @@ func createLLM(ctx context.Context, backend store.BackendDefinition, llmRef stor case config.BackendTypeAnthropic: return genaianthro.New(genaianthro.Config{ APIKey: backend.APIKey, + BaseURL: backend.URL, ModelName: llmRef.Model, HTTPOptions: genaianthro.HTTPOptions{ Headers: headers, diff --git a/website/content/docs/backends.md b/website/content/docs/backends.md index 38c435d..5aff3c3 100644 --- a/website/content/docs/backends.md +++ b/website/content/docs/backends.md @@ -10,6 +10,10 @@ Every agent references a backend for its LLM. Optionally, an agent can also refe {{< screenshot src="img/screenshots/admin-backends.png" alt="Admin UI — Backends" >}} +{{< callout type="info" >}} +Have a paid subscription with a provider (e.g., Claude Max/Pro, ChatGPT Plus)? You can use it instead of an API key. See the **[Using a subscription proxy](/docs/subscription-proxy/)** guide. +{{< /callout >}} + ## Backend types Click **+ New Backend** to create one. All types share the same dialog: @@ -63,7 +67,8 @@ For Anthropic's Claude models. Uses the official Anthropic API protocol, which i | Field | Required | Description | |-------|----------|-------------| | `name` | Yes | Display name | -| `apiKey` | Yes | Anthropic API key (starts with `sk-ant-`) | +| `url` | No | API base URL. Defaults to `https://api.anthropic.com`. Set this when using [a proxy](https://github.com/router-for-me/CLIProxyAPI). | +| `apiKey` | Yes | Anthropic API key (starts with `sk-ant-`) or proxy API key | Anthropic doesn't offer STT, TTS, or embedding APIs, so this backend type is used only for LLM inference. For voice and embeddings, add a separate `openai`-type backend pointing at a local service. diff --git a/website/content/docs/install-compose-local.md b/website/content/docs/install-compose-local.md index d9a94c5..c7d7d78 100644 --- a/website/content/docs/install-compose-local.md +++ b/website/content/docs/install-compose-local.md @@ -70,6 +70,7 @@ docker compose up -d | **ollama-setup** | Downloads Ollama models on first start, then exits | — | | **parakeet** | Speech-to-text (NVIDIA Parakeet) | 5092 | | **tts** | Text-to-speech (OpenAI Edge TTS) | 5050 | +| **cliproxyapi** | Claude subscription proxy ([CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)) | 8317 | ## Set up your first agent @@ -189,6 +190,10 @@ These providers only offer LLM — STT, TTS, and embeddings stay local. Create t | Anthropic | `anthropic` | `claude-sonnet-4-20250514` | | Gemini | `gemini` | `gemini-2.0-flash` | +### Provider subscription (no API key) + +If you have a paid subscription with a provider (e.g., Claude Max/Pro, ChatGPT Plus), the included CLIProxyAPI service lets you use their models without a separate API key. See the full **[Using a subscription proxy](/docs/subscription-proxy/)** guide for setup instructions. + ## Managing the deployment ```bash @@ -215,6 +220,7 @@ All data is stored in Docker volumes: | `redis_data` | Session memory | | `postgres_data` | Long-term memory (pgvector) | | `ollama_data` | Downloaded AI models | +| `cliproxyapi_auth` | CLIProxyAPI OAuth credentials (Claude subscription login) | Your data survives `docker compose down/up`, image updates, and container recreation. To back up your Magec configuration, copy `data/store.json` from the `magec_data` volume. diff --git a/website/content/docs/subscription-proxy.md b/website/content/docs/subscription-proxy.md new file mode 100644 index 0000000..e441713 --- /dev/null +++ b/website/content/docs/subscription-proxy.md @@ -0,0 +1,129 @@ +--- +title: "Using a subscription proxy" +--- + +Some AI providers offer paid subscriptions (e.g., Claude Max/Pro, ChatGPT Plus) that are separate from their API billing. A **subscription proxy** lets you route Magec's API requests through your existing subscription instead of paying for API access separately. + +[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) is an open-source proxy that translates subscription OAuth credentials into a standard API. It supports multiple providers and can be used with any Magec backend type that has a configurable `url` field. + +## How it works + +``` +Magec ──▶ CLIProxyAPI (localhost:8317) ──▶ Provider API + ▲ + │ OAuth credentials + │ from your subscription +``` + +Magec talks to CLIProxyAPI as if it were the provider's official API. CLIProxyAPI authenticates using the OAuth tokens from your subscription login and forwards the request upstream. + +## Setting up CLIProxyAPI + +### Docker (recommended) + +If you used the interactive installer and enabled the subscription proxy, CLIProxyAPI is already running. Otherwise, add it to your `docker-compose.yaml`: + +```yaml +services: + cliproxyapi: + image: eceasy/cli-proxy-api:latest + ports: + - "54545:54545" # OAuth callback (required for login only) + volumes: + - ./cliproxyapi/config.yaml:/CLIProxyAPI/config.yaml + - cliproxyapi_auth:/CLIProxyAPI/auth + restart: unless-stopped + +volumes: + cliproxyapi_auth: +``` + +Create the config file at `cliproxyapi/config.yaml`: + +```yaml +host: "0.0.0.0" +port: 8317 +auth-dir: "/CLIProxyAPI/auth" +api-keys: + - "sk-magec-local" +``` + +### Binary + +Download the latest release from [CLIProxyAPI releases](https://github.com/router-for-me/CLIProxyAPI/releases) and run it directly. + +## Logging in to a provider + +CLIProxyAPI requires you to authenticate with your provider's subscription account. The login command starts a temporary OAuth callback server, so you must **stop the running CLIProxyAPI service first** to free its ports: + +```bash +docker compose stop cliproxyapi +docker compose run --rm --service-ports cliproxyapi /CLIProxyAPI/CLIProxyAPI --no-browser -- +docker compose up -d cliproxyapi +``` + +Replace `--` with the login flag for your provider (see examples below). + +The command prints an authorization URL — open it in your browser, authorize, and wait for the callback. Your credentials are stored in the `cliproxyapi_auth` volume and persist across restarts. + +## Provider examples + +### Claude (Anthropic) + +Login flag: `--claude-login` ([docs](https://help.router-for.me/configuration/provider/claude-code.html)) + +```bash +docker compose run --rm --service-ports cliproxyapi /CLIProxyAPI/CLIProxyAPI --no-browser --claude-login +``` + +Then create an `anthropic` backend in the Admin UI: + +| Field | Value | +|-------|-------| +| Name | `Claude (Subscription)` | +| Type | `anthropic` | +| URL | `http://cliproxyapi:8317` (Docker) or `http://localhost:8317` (local) | +| API Key | `sk-magec-local` | + +{{< callout type="warning" >}} +The **URL** field is required. Without it, Magec sends requests to the default Anthropic API and authentication will fail. +{{< /callout >}} + +### Gemini (Google) + +Login flag: `--login` ([docs](https://help.router-for.me/configuration/provider/gemini-cli.html)) + +```bash +docker compose run --rm --service-ports cliproxyapi /CLIProxyAPI/CLIProxyAPI --no-browser --login +``` + +Then create an `openai` backend in the Admin UI (CLIProxyAPI exposes Gemini models through an OpenAI-compatible API): + +| Field | Value | +|-------|-------| +| Name | `Gemini (Subscription)` | +| Type | `openai` | +| URL | `http://cliproxyapi:8317/v1` (Docker) or `http://localhost:8317/v1` (local) | +| API Key | `sk-magec-local` | + +{{< callout type="info" >}} +CLIProxyAPI supports additional providers like [Codex](https://help.router-for.me/configuration/provider/codex.html) and [Antigravity](https://help.router-for.me/configuration/provider/antigravity.html). See the [full provider list](https://help.router-for.me/) for all available login commands and configuration options. +{{< /callout >}} + +## Verifying the setup + +After logging in, check that the proxy is working: + +```bash +curl http://localhost:8317/v1/models -H "X-Api-Key: sk-magec-local" +``` + +If you see a list of models, the proxy is ready. Assign the backend to any agent and start chatting. + +{{< callout type="info" >}} +The interactive installer can set up CLIProxyAPI automatically — just answer "yes" when asked about the subscription proxy. See [CLIProxyAPI on GitHub](https://github.com/router-for-me/CLIProxyAPI) for full configuration options. +{{< /callout >}} + +{{< callout type="info" >}} +CLIProxyAPI is a third-party project not affiliated with any AI provider. You are responsible for ensuring your usage complies with each provider's terms of service. +{{< /callout >}} diff --git a/website/hugo.toml b/website/hugo.toml index a7d6f06..5099871 100644 --- a/website/hugo.toml +++ b/website/hugo.toml @@ -128,10 +128,20 @@ theme = 'magec' url = '/docs/commands/' weight = 9 + [[menu.docs]] + identifier = 'guides' + name = 'Guides' + weight = 4 + [[menu.docs]] + name = 'Using a subscription proxy' + parent = 'guides' + url = '/docs/subscription-proxy/' + weight = 1 + [[menu.docs]] identifier = 'clients' name = 'Clients' - weight = 4 + weight = 5 [[menu.docs]] name = 'Overview' parent = 'clients' @@ -171,7 +181,7 @@ theme = 'magec' [[menu.docs]] identifier = 'reference' name = 'Reference' - weight = 5 + weight = 6 [[menu.docs]] name = 'API Reference' parent = 'reference' diff --git a/website/public/docs/a2a/index.html b/website/public/docs/a2a/index.html index 8f2c302..eaaf26b 100644 --- a/website/public/docs/a2a/index.html +++ b/website/public/docs/a2a/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
diff --git a/website/public/docs/admin-password/index.html b/website/public/docs/admin-password/index.html index 3c70abd..0f07872 100644 --- a/website/public/docs/admin-password/index.html +++ b/website/public/docs/admin-password/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
diff --git a/website/public/docs/agents/index.html b/website/public/docs/agents/index.html index 6514675..1899047 100644 --- a/website/public/docs/agents/index.html +++ b/website/public/docs/agents/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
@@ -305,11 +314,11 @@

While the system prompt defines who the agent is, skills define what it knows. An agent with a “Return Policy” skill and a “Product Catalog” skill becomes a capable customer support representative without you having to cram everything into one massive prompt.

Skills are especially powerful when shared across agents. Update a product catalog skill once, and every agent that uses it sees the change.

For a deeper comparison of when to use skills vs. creating specialized agents, see Skills vs. Agents.

-

+

Context Guard Experimental - # + #

Long conversations eventually hit the model’s token limit and fail. Context Guard watches the conversation size and automatically summarizes older messages before that happens. Recent messages stay untouched.

You set it up per-agent inside the LLM section. Two strategies:

diff --git a/website/public/docs/api/index.html b/website/public/docs/api/index.html index 8045496..7687ce9 100644 --- a/website/public/docs/api/index.html +++ b/website/public/docs/api/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
diff --git a/website/public/docs/backends/index.html b/website/public/docs/backends/index.html index 4293e06..b3ba0ca 100644 --- a/website/public/docs/backends/index.html +++ b/website/public/docs/backends/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
@@ -159,6 +168,13 @@

AI Backends

Admin UI — Backends
+ + + +
+ Have a paid subscription with a provider (e.g., Claude Max/Pro, ChatGPT Plus)? You can use it instead of an API key. See the Using a subscription proxy guide. +
+

Backend types # @@ -248,10 +264,15 @@

Yes Display name + + url + No + API base URL. Defaults to https://api.anthropic.com. Set this when using a proxy. + apiKey Yes - Anthropic API key (starts with sk-ant-) + Anthropic API key (starts with sk-ant-) or proxy API key diff --git a/website/public/docs/clients/index.html b/website/public/docs/clients/index.html index 698eac1..4facebb 100644 --- a/website/public/docs/clients/index.html +++ b/website/public/docs/clients/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
diff --git a/website/public/docs/commands/index.html b/website/public/docs/commands/index.html index a512765..e1e4a2e 100644 --- a/website/public/docs/commands/index.html +++ b/website/public/docs/commands/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
diff --git a/website/public/docs/configuration/index.html b/website/public/docs/configuration/index.html index b73efa3..88335fc 100644 --- a/website/public/docs/configuration/index.html +++ b/website/public/docs/configuration/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
@@ -193,12 +202,12 @@

# adminPassword: ${MAGEC_ADMIN_PASSWORD} # encryptionKey: ${MAGEC_ENCRYPTION_KEY} -voice: +voice: ui: enabled: true # Toggle Voice UI and voice routes # onnxLibraryPath: /usr/lib/libonnxruntime.so -log: +log: level: info # debug, info, warn, error format: console # console, json

@@ -301,7 +310,7 @@ 

server:
   port: ${MAGEC_PORT:-8080}
 
-log:
+log:
   level: ${LOG_LEVEL:-info}

data/store.json — Resources diff --git a/website/public/docs/context-guard/index.html b/website/public/docs/context-guard/index.html index 9445b5a..30f1afc 100644 --- a/website/public/docs/context-guard/index.html +++ b/website/public/docs/context-guard/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
diff --git a/website/public/docs/cron/index.html b/website/public/docs/cron/index.html index 5176ebb..ba88c48 100644 --- a/website/public/docs/cron/index.html +++ b/website/public/docs/cron/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
diff --git a/website/public/docs/discord/index.html b/website/public/docs/discord/index.html index 6b24883..368d463 100644 --- a/website/public/docs/discord/index.html +++ b/website/public/docs/discord/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
diff --git a/website/public/docs/flows/index.html b/website/public/docs/flows/index.html index 9a6165b..838c578 100644 --- a/website/public/docs/flows/index.html +++ b/website/public/docs/flows/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
diff --git a/website/public/docs/getting-started/index.html b/website/public/docs/getting-started/index.html index 8c2fde1..99f8af9 100644 --- a/website/public/docs/getting-started/index.html +++ b/website/public/docs/getting-started/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
diff --git a/website/public/docs/index.html b/website/public/docs/index.html index cfd4256..018515b 100644 --- a/website/public/docs/index.html +++ b/website/public/docs/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
@@ -201,6 +210,15 @@

Core Concepts

+

Guides

+ + + +

Clients

    diff --git a/website/public/docs/install-binary/index.html b/website/public/docs/install-binary/index.html index 64aab20..56555ac 100644 --- a/website/public/docs/install-binary/index.html +++ b/website/public/docs/install-binary/index.html @@ -106,6 +106,15 @@ +
    +
    Guides
    + + Using a subscription proxy + +
    + + +
    Clients
    @@ -210,11 +219,11 @@

    port: 8080 adminPort: 8081 -voice: +voice: ui: enabled: true -log: +log: level: info format: console

    @@ -327,10 +336,10 @@

    # Long-term memory (requires pgvector) docker run -d -p 5432:5432 \ - -e POSTGRES_USER=magec \ - -e POSTGRES_PASSWORD=magec \ - -e POSTGRES_DB=magec \ - pgvector/pgvector:pg17 + -e POSTGRES_USER=magec \ + -e POSTGRES_PASSWORD=magec \ + -e POSTGRES_DB=magec \ + pgvector/pgvector:pg17

Then configure in the Admin UI under Memory:

  • Session: redis://localhost:6379
    • diff --git a/website/public/docs/install-compose-local/index.html b/website/public/docs/install-compose-local/index.html index 29a4ea8..42818bc 100644 --- a/website/public/docs/install-compose-local/index.html +++ b/website/public/docs/install-compose-local/index.html @@ -106,6 +106,15 @@ +
    +
    Guides
    + + Using a subscription proxy + +
    + + +
    Clients
    @@ -182,10 +191,10 @@ 

    mkdir magec && cd magec
 
 curl -fsSL https://raw.githubusercontent.com/achetronic/magec/master/docker/compose/docker-compose.yaml \
-  -o docker-compose.yaml
+  -o docker-compose.yaml
 
 curl -fsSL https://raw.githubusercontent.com/achetronic/magec/master/docker/compose/config.yaml \
-  -o config.yaml
+  -o config.yaml

    2. (Optional) Enable GPU # @@ -253,6 +262,11 @@

    Text-to-speech (OpenAI Edge TTS) 5050 + + cliproxyapi + Claude subscription proxy (CLIProxyAPI) + 8317 +

    @@ -551,6 +565,11 @@

    +

    + Provider subscription (no API key) + # +

    +

    If you have a paid subscription with a provider (e.g., Claude Max/Pro, ChatGPT Plus), the included CLIProxyAPI service lets you use their models without a separate API key. See the full Using a subscription proxy guide for setup instructions.

    Managing the deployment # @@ -595,6 +614,10 @@

    ollama_data Downloaded AI models + + cliproxyapi_auth + CLIProxyAPI OAuth credentials (Claude subscription login) +

    Your data survives docker compose down/up, image updates, and container recreation. To back up your Magec configuration, copy data/store.json from the magec_data volume.

    diff --git a/website/public/docs/install-docker/index.html b/website/public/docs/install-docker/index.html index 97c43cf..8d7bacb 100644 --- a/website/public/docs/install-docker/index.html +++ b/website/public/docs/install-docker/index.html @@ -106,6 +106,15 @@ +
    +
    Guides
    + + Using a subscription proxy + +
    + + +
    Clients
    @@ -166,11 +175,11 @@

    port: 8080 adminPort: 8081 -voice: +voice: ui: enabled: true -log: +log: level: info format: console

    @@ -178,12 +187,12 @@

    # 

    docker run -d \
-  --name magec \
-  -p 8080:8080 \
-  -p 8081:8081 \
-  -v $(pwd)/config.yaml:/app/config.yaml \
-  -v magec_data:/app/data \
-  ghcr.io/achetronic/magec:latest
+  --name magec \
+  -p 8080:8080 \
+  -p 8081:8081 \
+  -v $(pwd)/config.yaml:/app/config.yaml \
+  -v magec_data:/app/data \
+  ghcr.io/achetronic/magec:latest

    That’s it. Magec is now running:

    diff --git a/website/public/docs/mcp/index.html b/website/public/docs/mcp/index.html index d199f2d..abf29e3 100644 --- a/website/public/docs/mcp/index.html +++ b/website/public/docs/mcp/index.html @@ -106,6 +106,15 @@ +
    +
    Guides
    + + Using a subscription proxy + +
    + + +
    Clients
    diff --git a/website/public/docs/memory/index.html b/website/public/docs/memory/index.html index be22970..37dbb97 100644 --- a/website/public/docs/memory/index.html +++ b/website/public/docs/memory/index.html @@ -106,6 +106,15 @@ +
    +
    Guides
    + + Using a subscription proxy + +
    + + +
    Clients
    diff --git a/website/public/docs/screenshots/index.html b/website/public/docs/screenshots/index.html index 7681c18..a46f7a9 100644 --- a/website/public/docs/screenshots/index.html +++ b/website/public/docs/screenshots/index.html @@ -106,6 +106,15 @@ +
    +
    Guides
    + + Using a subscription proxy + +
    + + +
    Clients
    diff --git a/website/public/docs/secrets-advanced/index.html b/website/public/docs/secrets-advanced/index.html index e737f9e..d2f566e 100644 --- a/website/public/docs/secrets-advanced/index.html +++ b/website/public/docs/secrets-advanced/index.html @@ -106,6 +106,15 @@ +
    +
    Guides
    + + Using a subscription proxy + +
    + + +
    Clients
    diff --git a/website/public/docs/secrets/index.html b/website/public/docs/secrets/index.html index 03058d3..cd39206 100644 --- a/website/public/docs/secrets/index.html +++ b/website/public/docs/secrets/index.html @@ -106,6 +106,15 @@ +
    +
    Guides
    + + Using a subscription proxy + +
    + + +
    Clients
    diff --git a/website/public/docs/skills-vs-agents/index.html b/website/public/docs/skills-vs-agents/index.html index 114c32a..c70cb24 100644 --- a/website/public/docs/skills-vs-agents/index.html +++ b/website/public/docs/skills-vs-agents/index.html @@ -106,6 +106,15 @@ +
    +
    Guides
    + + Using a subscription proxy + +
    + + +
    Clients
    diff --git a/website/public/docs/skills/index.html b/website/public/docs/skills/index.html index 86123f5..9b5ec99 100644 --- a/website/public/docs/skills/index.html +++ b/website/public/docs/skills/index.html @@ -106,6 +106,15 @@ +
    +
    Guides
    + + Using a subscription proxy + +
    + + +
    Clients
    diff --git a/website/public/docs/slack/index.html b/website/public/docs/slack/index.html index 1b8ee59..3a47491 100644 --- a/website/public/docs/slack/index.html +++ b/website/public/docs/slack/index.html @@ -106,6 +106,15 @@ +
    +
    Guides
    + + Using a subscription proxy + +
    + + +
    Clients
    diff --git a/website/public/docs/subscription-proxy/index.html b/website/public/docs/subscription-proxy/index.html new file mode 100644 index 0000000..ffe654d --- /dev/null +++ b/website/public/docs/subscription-proxy/index.html @@ -0,0 +1,354 @@ + + + + + + Using a subscription proxy — Magec — Self-hosted Multi-Agent AI Platform + + + + + + + + + + + +
    + +
    +
    + +
    + +

    Using a subscription proxy

    +

    Some AI providers offer paid subscriptions (e.g., Claude Max/Pro, ChatGPT Plus) that are separate from their API billing. A subscription proxy lets you route Magec’s API requests through your existing subscription instead of paying for API access separately.

    +

    CLIProxyAPI is an open-source proxy that translates subscription OAuth credentials into a standard API. It supports multiple providers and can be used with any Magec backend type that has a configurable url field.

    +

    + How it works + # +

    +
    Magec  ──▶  CLIProxyAPI (localhost:8317)  ──▶  Provider API
+              ▲
+              │ OAuth credentials
+              │ from your subscription
+

    Magec talks to CLIProxyAPI as if it were the provider’s official API. CLIProxyAPI authenticates using the OAuth tokens from your subscription login and forwards the request upstream.

    +

    + Setting up CLIProxyAPI + # +

    + +

    If you used the interactive installer and enabled the subscription proxy, CLIProxyAPI is already running. Otherwise, add it to your docker-compose.yaml:

    +
    services:
+  cliproxyapi:
+    image: eceasy/cli-proxy-api:latest
+    ports:
+      - "54545:54545"   # OAuth callback (required for login only)
+    volumes:
+      - ./cliproxyapi/config.yaml:/CLIProxyAPI/config.yaml
+      - cliproxyapi_auth:/CLIProxyAPI/auth
+    restart: unless-stopped
+
+volumes:
+  cliproxyapi_auth:
+

    Create the config file at cliproxyapi/config.yaml:

    +
    host: "0.0.0.0"
+port: 8317
+auth-dir: "/CLIProxyAPI/auth"
+api-keys:
+  - "sk-magec-local"
+

    + Binary + # +

    +

    Download the latest release from CLIProxyAPI releases and run it directly.

    +

    + Logging in to a provider + # +

    +

    CLIProxyAPI requires you to authenticate with your provider’s subscription account. The login command starts a temporary OAuth callback server, so you must stop the running CLIProxyAPI service first to free its ports:

    +
    docker compose stop cliproxyapi
+docker compose run --rm --service-ports cliproxyapi /CLIProxyAPI/CLIProxyAPI --no-browser --<provider-login>
+docker compose up -d cliproxyapi
+

    Replace --<provider-login> with the login flag for your provider (see examples below).

    +

    The command prints an authorization URL — open it in your browser, authorize, and wait for the callback. Your credentials are stored in the cliproxyapi_auth volume and persist across restarts.

    +

    + Provider examples + # +

    +

    + Claude (Anthropic) + # +

    +

    Login flag: --claude-login (docs)

    +
    docker compose run --rm --service-ports cliproxyapi /CLIProxyAPI/CLIProxyAPI --no-browser --claude-login
+

    Then create an anthropic backend in the Admin UI:

    +
    + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldValue
    NameClaude (Subscription)
    Typeanthropic
    URLhttp://cliproxyapi:8317 (Docker) or http://localhost:8317 (local)
    API Keysk-magec-local
    + + + +
    + The URL field is required. Without it, Magec sends requests to the default Anthropic API and authentication will fail. +
    + +

    + Gemini (Google) + # +

    +

    Login flag: --login (docs)

    +
    docker compose run --rm --service-ports cliproxyapi /CLIProxyAPI/CLIProxyAPI --no-browser --login
+

    Then create an openai backend in the Admin UI (CLIProxyAPI exposes Gemini models through an OpenAI-compatible API):

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldValue
    NameGemini (Subscription)
    Typeopenai
    URLhttp://cliproxyapi:8317/v1 (Docker) or http://localhost:8317/v1 (local)
    API Keysk-magec-local
    + + + +
    + CLIProxyAPI supports additional providers like Codex and Antigravity. See the full provider list for all available login commands and configuration options. +
    + +

    + Verifying the setup + # +

    +

    After logging in, check that the proxy is working:

    +
    curl http://localhost:8317/v1/models -H "X-Api-Key: sk-magec-local"
+

    If you see a list of models, the proxy is ready. Assign the backend to any agent and start chatting.

    + + + +
    + The interactive installer can set up CLIProxyAPI automatically — just answer “yes” when asked about the subscription proxy. See CLIProxyAPI on GitHub for full configuration options. +
    + + + + +
    + CLIProxyAPI is a third-party project not affiliated with any AI provider. You are responsible for ensuring your usage complies with each provider’s terms of service. +
    + + +
    +
+
+ + + + + + + + + diff --git a/website/public/docs/telegram/index.html b/website/public/docs/telegram/index.html index fe016db..e918028 100644 --- a/website/public/docs/telegram/index.html +++ b/website/public/docs/telegram/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
diff --git a/website/public/docs/voice-system/index.html b/website/public/docs/voice-system/index.html index b6ee247..2d83bc2 100644 --- a/website/public/docs/voice-system/index.html +++ b/website/public/docs/voice-system/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
diff --git a/website/public/docs/voice-ui/index.html b/website/public/docs/voice-ui/index.html index 3eb7f4f..00f83ab 100644 --- a/website/public/docs/voice-ui/index.html +++ b/website/public/docs/voice-ui/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
diff --git a/website/public/docs/webhooks/index.html b/website/public/docs/webhooks/index.html index 169ae56..f3317bc 100644 --- a/website/public/docs/webhooks/index.html +++ b/website/public/docs/webhooks/index.html @@ -106,6 +106,15 @@ +
+
Guides
+ + Using a subscription proxy + +
+ + +
Clients
@@ -241,13 +250,13 @@

Authentication uses the client’s token as a Bearer token:

# Command mode — body is ignored
 curl -X POST http://localhost:8080/api/v1/webhooks/YOUR_WEBHOOK_ID \
-  -H "Authorization: Bearer mgc_your_token"
+  -H "Authorization: Bearer mgc_your_token"
 
 # Passthrough mode — body contains the prompt
 curl -X POST http://localhost:8080/api/v1/webhooks/YOUR_WEBHOOK_ID \
-  -H "Authorization: Bearer mgc_your_token" \
-  -H "Content-Type: application/json" \
-  -d '{"prompt": "Analyze this error: connection timeout on service X"}'
+  -H "Authorization: Bearer mgc_your_token" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "Analyze this error: connection timeout on service X"}'

The agent processes the request synchronously and the response is returned in the HTTP response body. This makes webhooks easy to integrate with any system that can make HTTP requests and read responses.

Example integrations @@ -270,9 +279,9 @@

Forward alerts from Prometheus, Grafana, or any monitoring tool:

curl -X POST http://magec:8080/api/v1/webhooks/alert-handler \
-  -H "Authorization: Bearer mgc_..." \
-  -H "Content-Type: application/json" \
-  -d '{"prompt": "Critical alert: CPU usage above 90% on prod-web-01 for 10 minutes. Analyze possible causes and suggest remediation."}'
+  -H "Authorization: Bearer mgc_..." \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "Critical alert: CPU usage above 90% on prod-web-01 for 10 minutes. Analyze possible causes and suggest remediation."}'

Form processing # diff --git a/website/public/index.html b/website/public/index.html index 57ce0a1..76f01bd 100644 --- a/website/public/index.html +++ b/website/public/index.html @@ -1,7 +1,7 @@ - + Magec — Self-hosted Multi-Agent AI Platform diff --git a/website/public/sitemap.xml b/website/public/sitemap.xml index 420e3d5..95b27cd 100644 --- a/website/public/sitemap.xml +++ b/website/public/sitemap.xml @@ -59,6 +59,8 @@ http://localhost:1313/tags/ http://localhost:1313/docs/telegram/ + + http://localhost:1313/docs/subscription-proxy/ http://localhost:1313/docs/voice-system/