# chenyme/grok2api: a self-hosted multi-account gateway for Grok Build, Web and Console

> grok2api pools Grok Build, Grok Web and Grok Console accounts behind OpenAI- and Anthropic-compatible endpoints. The design is coherent, the documentation is uneven, and the legal footing is your problem, not the project's.

**chenyme/grok2api** — Multi-account API gateway for Grok Build, Grok Web, and Grok Console.

- Repository: https://github.com/chenyme/grok2api
- Stars: 7,740 · Forks: 2,310
- Language: Go
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/chenyme-grok2api

## The account sprawl problem grok2api targets

Grok is reachable through more than one surface, and each surface authenticates differently. The README's provider table lists three: Grok Build uses OAuth or Device OAuth, while Grok Web and Grok Console both use SSO. Model availability differs too. Build discovers models per account, Web ships a built-in list filtered by tier, and Console has its own built-in list. If you hold accounts across these surfaces and want one endpoint your existing SDK code can call, you are writing credential handling, quota tracking and failover yourself.

That is the gap this project fills. It is a Go gateway with a React admin console that keeps independent account pools per provider and exposes unified OpenAI- and Anthropic-compatible APIs. The intended reader is a developer who already has Codex, Claude Code or an OpenAI-compatible SDK wired up and wants Grok behind the same interface, not someone looking for a hosted Grok service. The README opens with a note that the project is for technical research and learning purposes only and that compliance with Grok's terms of use and local laws is the user's responsibility. Treat that as the project's own statement about where the risk sits.

## How the gateway routes, syncs and fails over

The architecture diagram splits the system into an access domain (API clients and the React admin), a gateway core domain (management services for accounts, models, keys and settings, plus account sync), and a provider layer. Requests pass through a Provider Registry. Account Sync refreshes credentials, quota and models on an ongoing basis.

The isolation detail matters more than the diagram. Each provider keeps its own credentials, quota, health, cooldown, concurrency and model capabilities, and uses an isolated egress scope. Retries stay inside a single route. When one public model ID intentionally aggregates several routes, the gateway may pick another route, which the README describes as bounded failover. So a failing Build account does not silently consume a Web account's quota, and a retry does not wander across providers unless the model ID was configured to span them.

Routing also covers model discovery, provider pinning, sticky sessions, quota and concurrency guards. Sessions include stored responses, compact, prompt-cache affinity and optional reasoning replay. Media handling covers image generation and editing, video jobs, local archiving, and URL, Base64 or SSE output. Egress is the part that will surprise newcomers: HTTP and SOCKS, plus Resin, Trojan, VLESS, Shadowsocks and VMess tunnels, with subscriptions, probes, proxy pools, allocation and fallback, and optional FlareSolverr integration.

## Installing grok2api with Docker Compose

The repository ships a docker-compose.yml, and the image is published to GitHub Container Registry as ghcr.io/chenyme/grok2api. The compose file defaults to that image with the latest tag, maps container port 8000 to host port 8000, mounts a config file read-only at /run/grok2api/config.yaml, and keeps state in a named volume at /app/data. The environment block sets TZ, an optional GROK2API_DATABASE_URL, and GROK2API_QUALITY_GUARD_DIR.

A minimal start, after placing a config.yaml next to the compose file, looks like this:

```bash
docker compose up -d
```

You should see the grok2api container running with port 8000 published, and the admin console served from that port. The compose file also defines optional services behind profiles. WARP is commented out by default and is meant for cases where the egress IP is not clean; the README instructs enabling it and then adding socks5://warp:1080 as an egress proxy in the admin settings. FlareSolverr starts with a profile flag:

```bash
docker compose --profile flaresolverr up -d
```

The compose file notes the Podman equivalent is podman compose --profile flaresolverr up -d, and that Clearance mode should be set to FlareSolverr in the admin console with http://flaresolverr:8191 as the address. A third optional sidecar, the egress quality guard, is described as not started by default and generating no probe requests until enabled. Its configuration is not visible in the truncated compose excerpt, so read config.example.yaml before assuming the defaults.

For a source build, the Makefile exposes two targets. The run target executes the backend from source with a config path, and the swagger target regenerates API docs with swag v1.16.6:

```bash
cd backend && GOCACHE=$(CURDIR)/.gocache go run ./cmd/grok2api --config "$(abspath $(CONFIG))" $(RUN_ARGS)
```

The Dockerfile builds the frontend with pnpm under Node 22 and the backend with Go 1.26 on Alpine 3.23, producing a static binary run as an unprivileged user. If you build your own image, those are the toolchain versions the project pins.

## Where grok2api stops being the right tool

The Web and Console providers authenticate with SSO, not an API key. That means the gateway's continued function depends on login flows it does not control. Grok can change those flows, and when it does, a working deployment stops working until the project ships a fix. Version cadence is the mitigating factor: v3.1.5 landed on 2026-08-25, with v3.1.4 on 2026-08-19 and v3.1.3 on 2026-08-17, so the last push was recent and releases are frequent. Frequent releases are also a cost: you are tracking a moving target.

The README does not document rollback, and it does not document an upgrade procedure. There is no stated database migration policy, no version compatibility table, and no description of what happens to the named volume at /app/data across versions. If your environment requires a tested downgrade path, this project does not give you one.

Egress is the other sharp edge. The presence of WARP, FlareSolverr and a quality guard sidecar implies that upstream can reject requests based on the IP they arrive from. The related search phrase grok2api 403 suggests people hit exactly that. The compose file's own comment about enabling WARP when the egress IP is not clean is an admission that a plain deployment may not work from every network. If you cannot control your egress, this is not the tool for you.

Finally, the README's scope note is not boilerplate. Routing multiple accounts through one endpoint in ways the upstream terms do not permit is your exposure, and the project explicitly disclaims it.

## grok2api compared with a plain OpenAI-compatible proxy

A generic reverse proxy such as LiteLLM or a hand-written FastAPI shim solves a narrower problem: it forwards a request to an upstream endpoint and returns the response, possibly rewriting the schema. Credentials are usually one per upstream, or a small static set, and failover is a config list.

grok2api's difference is that accounts are first-class objects with lifecycle. The README lists bulk import and export, quota sync, credential renewal, conversion, tools and cleanup as account operations. Credentials expire and get renewed. Quota is tracked per account. Health and cooldown are per account. That is a stateful system, not a proxy, and it is why the compose file persists data in a volume rather than running stateless.

The second difference is protocol coverage. A plain proxy typically speaks one dialect. grok2api exposes Responses, Chat Completions, Anthropic Messages, Images and asynchronous Videos, and the README names Codex, Claude Code, OpenAI-compatible SDKs and Anthropic-compatible SDKs as clients. If you only need Chat Completions against one Grok key, the gateway's account machinery is overhead you will pay for in operational surface: a writable config mount, a state volume, an admin console to secure, and optional sidecars.

## Licence, maintenance and what upgrading actually costs

The project is MIT licensed. That is permissive: you can use, modify and redistribute it, including commercially, provided the copyright notice and licence text are preserved. It says nothing about Grok's terms of use, which is a separate agreement between you and xAI, and the README's disclaimer places that obligation on you. MIT also means no warranty, which matters when the failure mode is an upstream login change rather than a bug in the code you can patch yourself.

Maintenance looks current. The repository is not archived, the last push was on 2026-08-25, and three patch releases landed in the nine days before that. The upgrade cost is not the code, it is the coupling. Your deployment depends on Grok Build OAuth, Grok Web SSO and Grok Console SSO continuing to behave as the providers expect. When they do not, you wait for a release. The README does not describe a rollback path, so the practical mitigation is pinning the image tag in GROK2API_IMAGE rather than tracking latest, and keeping a copy of a config.yaml that you know works. The compose file already makes the image tag overridable through that variable, which is the hook to use.

## Conclusion

Adopt it if you already hold several legitimate Grok accounts and need one OpenAI- or Anthropic-shaped endpoint in front of them, you are comfortable running a container with a writable config mount, and you accept that the README's own notice puts compliance on you. Do not adopt it if you need documented rollback, a published upgrade procedure, or a guarantee that Grok will not change the SSO flows the Web and Console providers depend on. Before deploying, check which providers your accounts can actually authenticate against, confirm the config keys your build expects by reading config.example.yaml rather than the README, and decide whether the egress quality guard sidecar is enabled by default in your compose file.

## FAQ

### Is Grok just ChatGPT?

The repository does not compare Grok with ChatGPT. What it does document is that Grok is reachable through three separate surfaces, Grok Build, Grok Web and Grok Console, each with its own authentication method and its own model list, which is why a gateway that pools accounts across them exists at all.

### Is Grok free for coding?

The README does not state any pricing or free-tier terms. It does note that Grok Web's built-in model list is filtered by tier and that Grok Build's video capability is limited to paid accounts, so capability differences between accounts are expected.

### Is Grok actually good for coding?

The repository makes no quality claim about Grok's coding output. It lists Codex and Claude Code as supported clients, which describes which SDKs can talk to the gateway, not how well the underlying model performs.

## Sources

- [Official README](https://github.com/chenyme/grok2api#readme)
- [Project repository](https://github.com/chenyme/grok2api)
- [Release notes](https://github.com/chenyme/grok2api/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/chenyme-grok2api