YSK product · MIT open source · npm

Grok CLI to OpenAI Compatible

Turn local Grok CLI (grok -p headless) into a production OpenAI-compatible HTTP API. CLI: gctoac / gcoa, default port 3847.

GitHub npm install

gctoac / gcoa
:3847
MIT

OpenAI APIChat · Responses · Messages

AES-256-GCMEncrypted audit & queue payloads

OTP AdminOne-time login · session ~12h

Queue + DDoSProduction backpressure & abuse protection

Local Grok → production gateway

Turn local Grok into a production OpenAI-compatible gateway — architecture, APIs, Admin, queue, and security at a glance.

ClientOpenAI SDK / curl / Open WebUI
GatewayAuth · rate limit · safe/agent
QueueAES-GCM jobs · SSE gog.queue
WorkerLease / fair poll / concurrency
Grok CLIgrok -p headless

Client (OpenAI SDK / curl / Open WebUI)
        │  Authorization: Bearer gk_live_...
        ▼
   Express Gateway :3847
   · auth · rate limit · safe/agent
   · enqueue ChatJob (AES-GCM) · SSE gog.queue
   · proxy-aware client IP · auto-ban
   · encrypted audit · Admin /admin
        │
        ▼
   In-process worker (lease / fair poll / concurrency)
        │
        ▼
   grok -p … (local Grok CLI)

OpenAI-compatible

Chat Completions, Responses, Anthropic Messages — point existing SDKs at your local gateway.

Encrypted audit

AES-256-GCM for prompts, responses, files, and queue payloads; API keys stored as scrypt hashes.

Durable queue

At-least-once, fair polling, backpressure, and dead-letter; recover in-flight jobs after restart.

DDoS center

Rate limits, auto-ban, blacklist, reverse-proxy IP sources — production-grade abuse protection.

Feature	Details
OpenAI API	`POST /v1/chat/completions`, `POST /v1/responses`, `GET /v1/models`
Anthropic API	`POST /v1/messages` (Bearer or `x-api-key`)
Thinking	`reasoning_content` + Grok `thought` + `grok.*` meta
Documents	Type-sniff upload, encrypted storage, download
Safe / Agent	Per-key policy; optional global force-safe
Encryption	AES-256-GCM for prompts, responses, files, queue payloads
Admin Panel	OTP login; queue / media / system / PM2 / DDoS / API capabilities
Media library	Generate / edit / image-to-video, assets & jobs, lightbox preview
Chat queue	SQLite jobs, fair poll, pause/drain, dead-letter, Idempotency-Key
DDoS center	Live connections, blacklist, auto-ban, presets, reverse-proxy IP
CLI	Lifecycle, settings, queue, ddos, keys, docs, chats, stats, admin otp
Ops	SQLite, PM2, log trim (>5MB), self-update

API & protocols

Endpoints, capability matrix, Thinking mapping, and Safe / Agent policy.

API protocols & endpoints

GET /health liveness; GET /ready DB + Grok; GET /v1/models
POST /v1/chat/completions (queued; optional Idempotency-Key); stream may emit gog.queue then OpenAI chunks
POST /v1/responses text subset; POST /v1/messages Anthropic-style
Documents: /v1/documents upload / list / soft-delete; Admin keys /v1/api-keys
Auth: Authorization: Bearer gk_live_…
Extensions: include_reasoning, cwd (agent only), session_id, document_ids

Grok CLI capability matrix

Capability	Chat	Responses	Anthropic	Admin switch
Text + stream	✅	✅	✅	Protocol toggles
Vision / images	✅	✅	✅	`vision`
Images generations + edits	✅	—	—	`imagesApi` + agent
Files `/v1/files`	✅	—	—	`filesOpenAiAlias`
Videos async	✅ mock	—	—	`videoApi`
Audio speech / transcriptions	✅ mock / 503	—	—	`audioApi`
Tools / tool_use	✅	✅	✅	`tools`
JSON schema	✅	✅	passthrough	`structuredOutput`
Reasoning effort	✅	✅	thinking→effort	`reasoningEffort`
Assistants-lite	—	—	—	`assistantsEmulation`

Not claimed: full official cloud parity (embeddings / realtime need separate backends). Grok CLI has no temperature-style sampling knobs; optional strictSampling rejects those params.

Thinking mapping

Grok thought → reasoning_content / stream delta
text → content; end → finish_reason + grok.sessionId / stopReason
Default include_reasoning: true

Safe / Agent policy

safe (client default): sandboxed cwd, no always-approve, limited tools, shorter timeout
agent: full CLI tools (may always-approve); cwd still allowlisted
Global force-safe: GROK_SAFE_MODE=true or Admin security settings
Clients cannot escalate via request body; never expose agent keys publicly

Admin console

OTP-gated ops panel — chat, keys, media, queue, DDoS, PM2, and system status.

Admin panel pages

Login: gctoac admin otp (5-minute one-shot); session ~12h; can disable panel and re-enable via CLI admin on
Dashboard: 24h KPIs, queue depth, protection summary, recent chats
Chat: playground, history, context modes, attachments (also queueable)
Chat logs: search / paginate; full decrypted prompt / reasoning / response
API keys / documents / audit: create, rate limits, IP allowlists, preview/download, readable action labels
Usage & protection: per-model / per-key stats, rate-limit summary
Media / queue / DDoS: see Queue & security tab
Security settings: global safe, tools/turns/timeout, default model, disable Admin
API capabilities: protocols · media · features · emulation; open / locked / dev presets
PM2: gctoac ↔ PM2, listen port, config, logs
System status: software / packages / env; one-click update & restart

Media library

Tabs: Studio · Assets · Jobs; KPI bar
Studio: generate / edit / image-to-video (Grok aspect ratios); library pick + drag-drop
Preview lightbox: image / video / audio / PDF / text (blob CSP-safe)

Queue & security

Encryption, keys, documents, durable queue, DDoS, and security notes.

Encryption, auth & audit

API keys stored as scrypt hashes (legacy SHA-256 upgraded on login)
Chat / documents / queue job payloads: AES-256-GCM
Plaintext key shown once at creation; lists show prefix only
Full chat audit; Admin chat logs can decrypt views (permission-gated)

API keys

CLI: gctoac key create|list|show|update|revoke|activate
Name, mode safe|agent, rate-limit, active
Admin can edit role and IP allowlists

Documents

Upload (type sniff), encrypted storage in DB or filesystem, preview / download / delete
Chat injects decrypted content via document_ids

Durable chat queue

At-least-once; lease / heartbeat; recover in-flight on restart
Default weighted per-key poll or global FIFO; per-key + global concurrency
Backpressure: queue_full 429, draining 503, wait timeout 504, cancel 409
Optional Idempotency-Key; AES-GCM payloads at rest
Default QUEUE_BACKEND=sqlite (redis / kafka reserved)
Admin: pause / drain, dead-letter, cancel / requeue / priority / purge

Security notes

Back up ENCRYPTION_KEY — lose it and historical data cannot be decrypted
Use safe keys publicly; keep Admin on localhost / VPN
OTP session in sessionStorage: XSS = Admin takeover within TTL
admin key / OTP are root-equivalent (update / PM2 / change port)
Never commit .env; never leak OTP / admin key

CLI & operations

gctoac / gcoa lifecycle, hot policy reload, and production deployment notes.

CLI `gctoac` / `gcoa`

Lifecycle: setup, start / -f / --pm2, stop, restart, status, doctor, logs, migrate, seed, update, open, version
Admin: admin status / on / off, otp, sessions revoke
keys / settings: create etc.; settings set / preset local|prod|code|read|chat|long
queue: stats, policy, pause / resume / drain, jobs, cancel / requeue / priority, purge-dead
ddos: policy, ban / unban, blacklist
Observability: stats, models, docs, chats, conversations, audit
Policies reload from DB in ~2–5s; most changes need no restart

Install, ports & production ops

Requires Node ≥ 20 + Grok CLI already grok login
Install from npm registry only (not npm i -g github:…)
Defaults: API /v1, Admin /admin/, health; change PORT and sync CORS / Admin URL
Data dir ~/.gctoac/ (GCTOAC_HOME / --home)
Production: preferred runner (gctoac or PM2); log trim; avoid dual runners EADDRINUSE

Screenshots & quick install

Real Admin UI previews and a four-step launch path.

Dashboard

24h KPIs, queue depth, keys / media, recent API chats, Safety summary.

Chat playground

Multi-turn chat, reasoning, attachments, history.

Usage & Limits

Per-model / per-key stats and gateway rate-limit summary.

DDoS center

Policy, traffic, blacklist, reverse-proxy IP.

Chat queue

Pause / drain, dead-letter, concurrency and fairness.

PM2 control

gctoac detached ↔ PM2, port 3847.

System

Node / Grok CLI / PM2 health and one-click update.

Quick commands

Global install
doctor → setup → start
admin otp → open /admin/
key create → call the API

npm install -g grok-cli-to-openai-compatible
gctoac doctor && gctoac setup && gctoac start
gctoac admin otp
gctoac key create
# http://127.0.0.1:3847/v1

Get started with Grok CLI Gateway

MIT open source · YSK Limited. Turn local Grok into a production OpenAI-compatible gateway.

View source npm install

Grok CLI to OpenAI Compatible

OpenAI-compatible

Encrypted audit

Durable queue

DDoS center

API protocols & endpoints

Grok CLI capability matrix

Thinking mapping

Safe / Agent policy

Admin panel pages

Media library

Encryption, auth & audit

API keys

Documents

Durable chat queue

DDoS / abuse protection

Security notes

CLI gctoac / gcoa

Install, ports & production ops

Dashboard

Chat playground

Usage & Limits

DDoS center

Chat queue

PM2 control

System

Quick commands

Get started with Grok CLI Gateway

CLI `gctoac` / `gcoa`