GreyFox Community Edition

GreyFox Community Edition is a self-hosted AI traffic proxy and local operator console for teams that want to control LLM token usage, enforce per-user limits, reuse exact cached responses, and keep AI traffic visibility inside their own infrastructure.

GreyFox runs as a local Docker box. No GreyFox-hosted control plane is required.

What You Get

• OpenAI-compatible proxy endpoint at /v1/chat/completions
• Local Admin UI served from the same container
• Per-user token quota enforcement with X-App-User-Id
• Mock mode for zero-cost onboarding and demos
• Provider mode for OpenAI-compatible upstream APIs
• Exact response cache for repeated non-streaming requests
• Local SQLite storage for settings, users, logs, cache, and metrics
• Traffic history, token analytics, manual cost calculator, and safe maintenance tools

Community Edition Limits

• Up to 5 active managed users
• Token monitoring is the authoritative usage signal
• Cost estimates are manual and informational only
• No hosted GreyFox cloud control plane
• No automatic update checks or automatic container updates
• No request detail drawer, exports, deeper diagnostics, or live traffic metrics

Requirements

• Docker Desktop or Docker Engine with Docker Compose
• One available host port, default 8080
• A Provider API key only if you want to use live provider mode

You do not need Node.js, npm, Angular, Nx, or source code to run the Community Edition release.

Quick Start

Create a compose.yaml file:

services:
  greyfox:
    image: ghcr.io/skillful-fox-studio/grey-fox-community:0.1.0
    container_name: greyfox-community
    environment:
      OPENAI_BASE_URL: ${OPENAI_BASE_URL:-https://api.openai.com/v1}
      GREYFOX_DB_PATH: ${GREYFOX_DB_PATH:-data/greyfox.db}
      PORT: 3000
      GREYFOX_STATIC_ROOT: /app/public/admin-ui
    ports:
      - "${GREYFOX_HTTP_PORT:-8080}:3000"
    volumes:
      - greyfox-data:/app/data
    restart: unless-stopped

volumes:
  greyfox-data:

Start GreyFox:

Open the Admin UI:

Health check:

curl http://localhost:8080/api/health

Expected response:

{"status":"ok","service":"proxy-api"}

How GreyFox Fits Into Your App

GreyFox is a proxy layer. It does not install browser extensions, intercept your personal ChatGPT usage, or automatically capture traffic from unrelated applications. Your AI application must send its provider requests to GreyFox instead of sending them directly to the upstream provider.

Typical direct setup:

Your application
      |
      | HTTPS request with provider API key
      v
OpenAI-compatible provider

GreyFox setup:

Your application
      |
      | OpenAI-compatible request
      | Base URL: http://<greyfox-host>:<port>/v1
      | Header: X-App-User-Id: <your-end-user-id>
      v
GreyFox Community Edition
      |
      | Local checks:
      | - user token quota
      | - exact response cache
      | - prompt injection guard
      | - traffic logging
      v
OpenAI-compatible provider

The application still decides when to call AI. GreyFox only sees requests that are explicitly routed through its proxy endpoint.

Minimal Integration Checklist

In your application configuration:

1. Change the AI provider base URL to GreyFox:

   If GreyFox runs on another server, use that host instead:

   http://greyfox.internal:8080/v1
   

2. Keep using the OpenAI-compatible chat completions path:

   Full URL:

   http://localhost:8080/v1/chat/completions
   

3. Add the end-user identifier header to every AI request:

   This should be your application's own user id, tenant user id, account id, or another stable identifier that lets GreyFox enforce limits per real end user.

4. Configure Provider Settings in the GreyFox Admin UI:

   • use Mock mode for first validation;
   • switch to OpenAI-compatible provider when you are ready to forward real traffic;
   • enter your provider API key in the Admin UI.

5. Send a test request and verify it appears in Dashboard and Traffic.

Common Deployment Shapes

Same machine demo

Use this for local evaluation:

App or curl -> http://localhost:8080/v1/chat/completions -> GreyFox -> Provider

Same Docker host

If your application also runs in Docker Compose, put both services on the same Compose network and call GreyFox by service name:

http://greyfox:3000/v1/chat/completions

Inside Docker, use the container port 3000. From the host machine, use the published port, usually 8080.

Internal server

For a team environment, run GreyFox on an internal host and point your application to it:

http://greyfox.internal:8080/v1/chat/completions

Keep the Admin UI and proxy endpoint reachable only inside your trusted network unless you intentionally place your own authentication, VPN, or gateway in front of it.

Client Configuration Examples

Most OpenAI-compatible SDKs let you override the base URL.

Conceptually, change this:

baseURL = "https://api.openai.com/v1"

to this:

baseURL = "http://localhost:8080/v1"

Then include:

The exact SDK option name depends on your application stack. Look for settings such as baseURL, baseUrl, apiBase, base_url, or OPENAI_BASE_URL.

Port Configuration

GreyFox uses one stable internal container port:

The host port is controlled by Docker port mapping. To run GreyFox on another host port:

GREYFOX_HTTP_PORT=9090 docker compose up -d

Then open:

Provider Settings

Open the Admin UI and go to Provider Settings.

Use:

• Mock mode for zero-cost local demos and onboarding
• OpenAI-compatible provider for live traffic forwarding

GreyFox expects an OpenAI-compatible upstream API in live provider mode. Other compatible providers such as OpenRouter, Groq, Together, DeepSeek, Mistral, Ollama, or LocalAI may connect successfully, but provider billing remains the source of truth for final accounting.

GreyFox stores provider settings locally in the container database volume. Saved provider keys are not shown again in full inside the UI.

Mock Demo Request

After enabling Mock mode in the Admin UI, send a test request:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-App-User-Id: demo-user-1" \
  -d "{\"model\":\"gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":\"Reply with GreyFox OK\"}]}"

Refresh the Admin UI to see the request in Traffic and Dashboard.

Updating GreyFox

GreyFox does not auto-update.

To check releases manually, use About -> Check for updates in the Admin UI or visit the public release page.

To update the Docker image:

docker compose pull
docker compose up -d

Your local SQLite data is stored in the greyfox-data Docker volume and is not removed by a normal image update.

Data and Privacy

GreyFox Community Edition is designed to run inside your own infrastructure.

• Prompts, completions, logs, settings, provider keys, and metrics stay in your local deployment unless you send them elsewhere.
• Manual update checks make one browser request to GitHub Releases.
• GreyFox does not require a hosted GreyFox control plane.
• Connected upstream providers still process any traffic you send to them.

Support and Feedback

Public issues and Community releases:

https://github.com/skillful-fox-studio/grey-fox-community

Direct operator inquiries:

GreyFox is currently maintained by a solo indie developer. Email replies may take up to 3 days.

License

GreyFox Community Edition is proprietary commercial software made available as a free-to-use Community Edition. It is not open-source software.

See LICENSE.md and THIRD_PARTY_NOTICES.md.