Run Gegentica Locally with Quickstart

gegentic-quickstart is a Docker Compose bundle that brings up every Gegentica service — API, Gateway, Guardian, Tracing, and Portal — along with their infrastructure dependencies (Postgres, SuperTokens, ClickHouse), with a single command. Use it to evaluate Gegentica 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

Edit .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

docker compose up

This pulls and starts all services. The first run also runs database migrations via the api-migration service. Once everything is healthy, open the Gegentica portal:

http://localhost:3002

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

docker compose down

To also remove persisted data (Postgres and ClickHouse volumes):

docker compose down -v

Troubleshooting

If a service fails to start, check its logs first:

docker compose logs -f <service-name>

The most common causes are a missing required environment variable, or a Postgres/SuperTokens connection race on first boot despite the healthcheck-gated startup order — retrying 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.

Introduction

Features

Support

Run Gegentica Locally with Quickstart

Prerequisites

Set up your environment

Start the stack

What gets started

Updating

Stopping

Troubleshooting

Next steps

​Prerequisites

​Set up your environment

​Start the stack

​What gets started

​Updating

​Stopping

​Troubleshooting

​Next steps

Prerequisites

Set up your environment

Start the stack

What gets started

Updating

Stopping

Troubleshooting

Next steps