> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gegentic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Gegentic Locally with Quickstart

> Use the gegentic-quickstart Docker Compose bundle to run the full Gegentic platform on your own machine.

[gegentic-quickstart](https://github.com/gegentic/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:

```bash theme={null}
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](https://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. |

<Note>
  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).
</Note>

## Start the stack

```bash theme={null}
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 Gegentic 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

```bash theme={null}
docker compose pull && docker compose up -d
```

## Stopping

```bash theme={null}
docker compose down
```

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

```bash theme={null}
docker compose down -v
```

## Troubleshooting

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

```bash theme={null}
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](/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`.