gegentic-quickstart is a Docker Compose bundle that brings up every Gegentic service — API, Gateway, Guardian, Tracing, and Portal — along with their infrastructure dependencies (Postgres, SuperTokens, ClickHouse), with a single command. Use it to evaluate Gegentic locally or to self-host it.
Prerequisites
- Docker Compose
- The following ports free on
localhost: 3002, 4001, 4002, 8787, 8700, 5001
- No Node, npm, or build tools needed — every service ships as a prebuilt Docker image
- Network access to the OpenAI API (or an OpenAI-compatible endpoint) — Guardian’s AI-based guardrails call out to it at runtime
Set up your environment
Clone the repo and copy the environment template:
git clone https://github.com/gegentic/gegentic-quickstart.git
cd gegentic-quickstart
cp .env.example .env
.env and set the following required variables:
| Variable | Description |
|---|
LICENSE_KEY | Your self-hosted license key. Register at gegentic-ai.com to receive one by email. |
ENCRYPT_KEY_FOR_API_KEY | A 64-character hex string. Generate one with openssl rand -hex 32. |
ENCRYPT_KEY_FOR_VIRTUAL_KEY | A 64-character hex string. Generate one with openssl rand -hex 32. |
OPENAI_API_KEY | An OpenAI API key (or set OPENAI_BASE_URL to point at an OpenAI-compatible endpoint), used by Guardian’s AI-based guardrails. |
Optional variables: SEED_ORG_NAME sets the name of the organization created on first run (defaults to “My Organization”), and GEGENTIC_ALLOWED_SIGNUP_EMAILS restricts email/password signup to a comma-separated allowlist (leave blank to allow anyone).
Start the stack
This pulls and starts all services. The first run also runs database migrations via the api-migration service.
Once everything is healthy, open the Gegentic portal:
What gets started
| Service | Port | Role |
|---|
| Portal | 3002 | The web UI — this is what you open in your browser |
| API | 4001 (REST), 4002 (gRPC) | Core backend API |
| Gateway | 8787 | LLM gateway that routes requests through guardrails |
| Guardian | 8700 | AI guardrails service (jailbreak detection, compliance checks) |
| Tracing | 5001 | Request tracing and observability |
| Postgres, SuperTokens, ClickHouse | internal only | Infrastructure dependencies, not exposed to the host |
Updating
docker compose pull && docker compose up -d
Stopping
To also remove persisted data (Postgres and ClickHouse volumes):
Troubleshooting
If a service fails to start, check its logs first:
docker compose logs -f <service-name>
docker compose up usually resolves it.
Next steps
Once the portal is up, follow Making Your First Request to create your organization, connect a provider, and generate your first Access Key — all against your local stack instead of app.gegentic-ai.com. 
