Power your agent
Install from the publisher. Not a PlugMCP endpoint.
Host a copy with our keys and logs.
No packaged release in the registry yet. Follow the repository README.
Remote URL or a command on your machine? How the two installs differ
Run on PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LaunchSupport the project — star it on GitHub.
Remote LLM Gateway is one gateway for Grok Build, Claude Code, and GPT. The VS Code and Cursor plugin and the
remote-llmCLI work with the local project, while the agents, tools, and MCP run on the server. This project is not affiliated with or endorsed by xAI, Anthropic, OpenAI, or Meta. The names Grok, Grok Build, Claude Code, Codex, and Muse Code are used only to describe compatibility.
Three ways into the same gateway:
The plugin and the CLI connect to the gateway over WebSocket and speak ACP (JSON-RPC). They do not call model APIs themselves. On the server the gateway starts an agent in a directory that belongs to that session. One subscription, and the keys stay on the gateway.
Sign in to Claude and the other provider CLIs on the same server that runs the gateway. Login and later use share that one address.
The heavy CLI does not have to sit on every machine. People open their project locally, while Grok Build, Claude Code, and GPT run on one server. An administrator sees usage, assigns a person a model and outbound internet access, and sets a token limit for a period.
Every user connects to the same gateway. Provider keys are not copied to their computers. A session is built from the user and the project: wss://<gateway-address>/ws/{sessionId}.
The Remote LLM Gateway plugin shows a chat in the right sidebar, next to Grok. The project stays open locally: at the start of a session the files go to the gateway, and after the reply the edits are written back into the editor. The plugin does not start a local grok or claude process.
If the admin has assigned an LLM to this user, the plugin shows that model. Without an assignment, the model is chosen in the UI.
The chat UI is based on GUI for Grok Build & Muse Code.
remote-llm talks to the same gateway as the plugin. From the project directory it sends files to the server and writes the edits back after the reply. --no-sync skips that. The short name llm is not used: it is too generic.
A forced model from the admin UI is shown here too.
The admin UI covers users, access tokens, available models, and usage: requests and tokens. It also sets the outbound proxy, the forced LLM, and the usage limit: how many tokens can be spent and when the counter resets.
api accepts calls with user tokens. gateway accepts agent sessions.
An administrator assigns an LLM to a user. The plugin and the CLI show that model on screen. Without an assignment, the person picks the model.
Each user has two fields in the admin UI: a token limit and a reset period. The period can be a day, a week, a month, or a custom interval. The gateway counts tokens for that period. After the limit, new requests stop until the period ends and the counter resets. Usage from earlier periods stays in the analytics.
Requests from Grok Build, Claude Code, and the other agents leave the server through a proxy. The address is set in the admin UI and in .env. Changing either value changes the exit path, and the service does not need a rebuild.
A user's files on the gateway live in that session's directory. The project path from the client is only the directory key: the gateway does not open a repository on the server at that path. Agent commands run in this directory. Edits come back to the local project.
For GPT the gateway supplies the tools itself: read, write, and show the session files, and run a command in the session directory. Extra tools come from stdio MCP, and the server list lives in MCP_CONFIG. Grok Build and Claude Code still take their MCP servers from the configuration on the gateway machine.
remote-llm.grok, claude.go run without Redis stores users, limits, and the proxy in DATA_FILE. WebSocket sessions are not written to Redis: a live conversation does not survive a process restart.The latest release contains the remote-llm binaries, a .vsix package, and container images for that version. The plugin is on Open VSX. Locally, the services start from source.
cp .env.example .env
# set ADMIN_TOKEN in .env
set -a && source .env && set +a
go run ./gateway/cmd/gateway
go run ./admin/cmd/admin
go run ./api/cmd/api
The admin UI opens at http://127.0.0.1:8081. A user's token is shown once, when the user is created. Then:
go run ./cmd/remote-llm --gateway http://127.0.0.1:8080 --token <token>
GATEWAY_ECHO=1 in .env replies with an echo and does not need grok or claude installed. For real agents, remove that variable: the gateway starts grok agent serve or claude agent serve and sends GPT to the OpenAI Responses API. Sign in to Claude and the other provider CLIs on the gateway machine.
One public entry point is described in deploy/nginx/nginx.conf. Nginx accepts ordinary requests and WebSocket, and the processes listen on localhost:
Then GATEWAY_URL points at nginx, without port 8080. .env.example has a commented example.
The monorepo:
gateway/ — gateway, WebSocket, and ACPapi/ — access by user tokensadmin/ — web adminplugin/ — VS Code and Cursor extensioncmd/remote-llm/ — CLIdeploy/ — deploymentapi, and admin with the commands from Install. State lives in DATA_FILE. Redis is not required for this step.remoteLlm.gatewayUrl and save the token in Secret Storage with the command «Remote LLM: задать токен». The chat opens with «Remote LLM: открыть чат» and appears as a tab in the right sidebar. «Remote LLM: показать назначенную модель» only shows the model and usage. Or run remote-llm from the project directory with the same token (--token or GATEWAY_TOKEN).The server pieces are written for Go. The plugin is JavaScript.
The plugin and the CLI are thin. They open a WebSocket, pass the ACP protocol, and show the reply. The gateway owns sessions, agent startup, MCP, and command execution.
The gateway checks whether the user has an assigned model and whether the token limit for the current period is spent. It then starts the backend in that session's directory and proxies outbound calls through the proxy from the admin UI or .env.
A push and a pull request run .github/workflows/ci.yml: gofmt, go vet, go test ./..., the plugin check and tests, and builds of gateway, api, admin, and remote-llm. On a pull request the image job checks the linux/amd64 build.
A push to main publishes linux/amd64 and linux/arm64 images to GitHub Container Registry. The image tag is the commit SHA, plus a moving main tag:
ghcr.io/alanforester/remote-llm-gateway/gateway:<sha>
ghcr.io/alanforester/remote-llm-gateway/api:<sha>
ghcr.io/alanforester/remote-llm-gateway/admin:<sha>
A git tag vMAJOR.MINOR.PATCH publishes the same images with the version number (1.2.3 and v1.2.3) and the same SHA. That tag builds a GitHub Release: remote-llm binaries for Linux, macOS, and Windows, and the plugin .vsix. The release notes list the image names for that version.
git tag v0.1.2
git push origin v0.1.2
Registry login and release creation use GITHUB_TOKEN, which GitHub Actions provides. Those steps have packages: write and contents: write. There is no separate token in the repository files. In Settings → Actions → General the repository must allow read and write for GITHUB_TOKEN, or package publishing stops on permissions.
The image is built from deploy/Dockerfile. Without REDIS_URL the three processes share the file /data/gateway.json. The process inside the container is user 65532. The gateway image includes git, which agents use inside a session. grok and claude are not in the image; install them on the gateway machine. The admin process needs ADMIN_TOKEN and exits immediately without it. The WebSocket token is sent in the Authorization header, not in the URL. Nginx does not write the query string to the access log and does not publish /metrics.
The header carries badges for language, license, CI, and the release.
Pull requests are welcome.
On one machine the stack starts from deploy/docker-compose.yml. It includes Redis, gateway, api, admin, nginx, Prometheus, and Grafana. Secrets are read from .env next to the repository and are not baked into the image.
cp .env.example .env
# your own ADMIN_TOKEN and, if needed, OPENAI_API_KEY, OUTBOUND_PROXY
docker compose --env-file .env -f deploy/docker-compose.yml up -d --build
The admin UI opens on HTTP_PORT (80 by default). GATEWAY_URL for the plugin and CLI is that address, without :8080. Grafana listens on 127.0.0.1:3000, Prometheus on 127.0.0.1:9090. The dashboard is named Remote LLM Gateway. Process metrics: remote_llm_http_requests_total, remote_llm_tokens_total, remote_llm_quota_denied_total, remote_llm_sessions. Nginx does not expose them.
IMAGE_TAG=local builds images from deploy/Dockerfile. After a publish to GHCR the same file can start without a build:
IMAGE_TAG=0.1.2 docker compose --env-file .env -f deploy/docker-compose.yml pull
IMAGE_TAG=0.1.2 docker compose --env-file .env -f deploy/docker-compose.yml up -d
GATEWAY_ECHO=1 in .env keeps the echo. For real agents set it to 0: grok and claude must be available to the gateway process.
To update a VPS, change IMAGE_TAG to a commit SHA from main or to a release number, then run pull and up -d again. Redis and the worktree directory live in the redis-data and workspaces volumes, and up does not erase them.
Kubernetes manifests are in deploy/k8s. They include the same processes. The secret is not stored in the repository:
kubectl apply -f deploy/k8s/namespace.yaml
kubectl -n remote-llm create secret generic remote-llm \
--from-literal=ADMIN_TOKEN=... \
--from-literal=OPENAI_API_KEY=... \
--from-literal=OUTBOUND_PROXY= \
--from-literal=GRAFANA_ADMIN_PASSWORD=...
kubectl apply -k deploy
The default image tag is main. Another version is set with newTag in deploy/kustomization.yaml. The nginx Service of type LoadBalancer opens port 80. On a VPS without a load balancer, change the type to NodePort. Grafana stays inside the cluster: kubectl -n remote-llm port-forward svc/grafana 3000:3000. The manifest sets GATEWAY_ECHO=1; for production agents change the value in deploy/k8s/apps.yaml and apply the kustomization again. If the cluster cannot pull the image, make the GHCR package public or add an imagePullSecret.
.vsix is also in the latest release.MIT. The text is in LICENSE.
The plugin UI is based on phuryn/grok-build-vscode. That project has its own license. This repository is published under MIT.
Remote LLM Gateway is one gateway for Grok Build, Claude Code, and GPT. The VS Code and Cursor plugin and the remote-llm CLI work with the local project, while the agents, tools, and MCP run on the se
Overview
Remote LLM Gateway is one gateway for Grok Build, Claude Code, and GPT. The VS Code and Cursor plugin and the remote-llm CLI work with the local project, while the agents, tools, and MCP run on the server.
Tools
No tool list yet. Remote servers get one after the first health check.
FAQ
Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.
No required environment variable is listed on this record.
Remote Llm Gateway runs locally over stdio.
Last checked 2026-10-28. Remote LLM Gateway is one gateway for Grok Build, Claude Code, and GPT. The VS Code and Cursor plugin and the remote-llm CLI work with the local project, while the agents, tools, and MCP run on the server.