🚀 AICursor Gateway Manager

A lightweight, local OpenAI-compatible gateway that lets Cursor talk to OpenRouter or any OpenAI-compatible API provider — cloud-only, with automatic model discovery, free-tier routing, and a simple terminal menu. No model is ever downloaded or executed on your machine. Works out of the box on any Linux distribution, with automatic detection of your package manager.

Interactive terminal menu of AICursor Gateway Manager

AICursor Gateway Manager runs a small local HTTP gateway (127.0.0.1) that sits between Cursor and any OpenAI-compatible API. Point Cursor's "Override OpenAI Base URL" setting at the gateway, and it transparently forwards your requests to OpenRouter (or a custom provider), including a dedicated free-only mode.

It does not bypass Cursor's licensing or unlock any Cursor-only feature — it only routes requests through APIs that Cursor already allows you to configure.

• 💰 Lower or zero AI cost inside Cursor — by routing through OpenRouter's free-only mode, you can use Cursor's AI features without paying for API usage, and without accidentally switching to a paid model.
• 🔓 Freedom from a single provider — you are not locked into one paid API. You can plug in OpenRouter today and switch to any other OpenAI-compatible provider tomorrow, without reconfiguring Cursor each time.
• ⏱️ No manual setup work — normally, building a local API gateway means writing a Python server, a systemd service, and managing secrets by hand. This tool does all of that for you in seconds.
• 🧠 One place to manage everything — a single terminal menu controls every provider, key, route, and the gateway's ON/OFF state, instead of editing multiple config files by hand.
• 🛡️ Reduced risk of leaking API keys — keys are stored locally with strict file permissions instead of being pasted directly into Cursor or scattered across config files.
• 🔄 Resilience — the gateway restarts itself automatically if it crashes, and survives system reboots, so your Cursor setup keeps working without you thinking about it.

1. Checks and installs dependencies — detects your Linux distribution's package manager and installs curl, jq, and python3 automatically if they are missing.
2. Creates a local configuration folder — sets up ~/.config/aicursor-gw/ and ~/.local/share/aicursor-gw/ to store profiles, routes, secrets, and logs, all with restricted permissions (chmod 600/700) so only your user can read them.
3. Builds a local Python gateway server — generates a small HTTP server (gateway.py) that listens only on 127.0.0.1 and exposes OpenAI-compatible endpoints (/v1/chat/completions, /v1/models, /health).
4. Registers it as a systemd user service — creates and enables a systemd --user unit so the gateway starts automatically, restarts on failure, and runs sandboxed (NoNewPrivileges, PrivateTmp).
5. Stores your provider credentials safely — when you add OpenRouter or a custom provider, your API key is saved in an environment file with chmod 600, never printed back to the screen after entry.
6. Routes every request Cursor sends — when Cursor sends a chat/completion request to http://127.0.0.1:8765/v1, the gateway rewrites the model name according to your active profile/aliases and forwards it to the real provider (OpenRouter or your custom API), then returns the response back to Cursor unchanged.
7. Enforces free-only mode when enabled — if your active profile is marked free_only, the gateway forcibly overrides the model field to openrouter/free before forwarding, so you can never be billed by mistake.
8. Lets you test and monitor everything — a built-in test command checks both the local gateway and the live upstream API in one step, and logs are available instantly via the menu or journalctl.
9. Backs up your setup on demand — one command copies your profiles, routes, secrets file, and Cursor's settings.json into a timestamped backup folder.
10. Uninstalls cleanly when you're done — removes only the gateway's service, files, and folders — Cursor itself and your projects are never touched.

• 🌐 OpenAI-compatible gateway — works with OpenRouter and any OpenAI-compatible endpoint
• 🆓 Free-only OpenRouter mode — automatically forces free models, avoiding accidental paid usage
• 🔀 Multiple provider profiles — switch between OpenRouter and custom providers
• 🏷️ Model aliases — map friendly names (free, auto) to real model IDs
• 🔍 Automatic model discovery — detects which models are free on your account
• 🔁 Automatic failover-ready routing via a simple routes.json
• 🟢🔴 One-command ON / OFF control via systemd --user
• 🧪 Built-in API test — verifies both the local gateway and the upstream provider
• ⚙️ Cursor settings helper — prints the exact values to paste into Cursor
• 🗂️ Backup — snapshots your profiles, routes, secrets, and Cursor settings
• 📜 Logs & health checks — gateway log file + systemctl/journalctl integration
• 🖥️ Simple interactive menu — no need to memorize flags

• Any Linux distribution with systemd --user support (Arch, Debian, Ubuntu, Fedora, RHEL, openSUSE, Alpine, Void, Gentoo, and derivatives)
• bash, curl, jq, python3 (auto-detected and installed via your distro's package manager — pacman, apt, dnf, yum, zypper, apk, xbps, or emerge)
• An OpenRouter API key or any OpenAI-compatible provider key

chmod +x aicursor-manager.sh

./aicursor-manager.sh

./aicursor-manager.sh install

This installs dependencies, prompts for your OpenRouter API key, starts the gateway, tests it, and shows you the Cursor configuration values.

Open Cursor → Settings → Models and set:

OpenAI API Key            : ON  (use your provider key)
Override OpenAI Base URL  : ON
Base URL                  : http://127.0.0.1:8765/v1

./aicursor-manager.sh status
./aicursor-manager.sh test
./aicursor-manager.sh off

• ⏱️ Saves time — no manual gateway scripting or systemd unit writing
• 🧩 Provider-agnostic — swap between OpenRouter and any custom OpenAI-compatible API without touching Cursor's config again
• 💸 Cost control — free-only mode prevents accidental spend on paid models
• 🔄 Persistent — runs as a systemd --user service, survives reboots and restarts automatically on failure
• 🧹 Clean removal — uninstall only removes the gateway, never your projects or Cursor itself

• ✅ Cloud-only — no AI model is ever downloaded or executed locally; all inference happens on the provider's servers
• ✅ Local-only listener — the gateway binds strictly to 127.0.0.1, never exposed to your network
• ✅ Secrets protected — API keys are stored in ~/.config/aicursor-gw/providers.env with chmod 600 permissions, readable only by your user
• ✅ No telemetry — the script does not collect or transmit any usage data of its own
• ✅ Sandboxed service — the systemd unit runs with NoNewPrivileges=true and PrivateTmp=true
• ✅ Non-destructive uninstall — removing the gateway never touches Cursor or your projects, and requires explicit confirmation (REMOVE)

The installer auto-detects your package manager and installs dependencies with the correct commands for your distro:

Released under the MIT License. Use, modify, and share freely.

Made with 🐧 for the Linux desktop community