Skip to main content

Quickstart

This document helps you launch an OpenAI-, Anthropic-, and Gemini-compatible gateway to GigaChat and verify each protocol with a first request.

Requirements​

  • Python 3.10–3.14 for a local run.
  • uv for local development.
  • Docker with the Compose plugin for a container run.
  • GigaChat credentials and scope for the target account.

Setting up credentials​

Create a local env file:

cp .env.example .env

At a minimum, fill in:

GPT2GIGA_MODE=DEV
GPT2GIGA_HOST=0.0.0.0
GPT2GIGA_PORT=8090
GPT2GIGA_ENABLE_API_KEY_AUTH=True
GPT2GIGA_API_KEY="<local-proxy-api-key>"
GIGACHAT_CREDENTIALS="<your-gigachat-credentials>"
GIGACHAT_SCOPE=GIGACHAT_API_PERS
GIGACHAT_MODEL=GigaChat-2-Max

The GigaChat SDK settings use the GIGACHAT_ prefix. The proxy settings use the GPT2GIGA_ prefix.

Running via Docker Compose​

DEV profile:

docker compose --env-file .env -f deploy/base.yaml --profile DEV up -d

PROD profile:

docker compose --env-file .env -f deploy/base.yaml --profile PROD up -d

In PROD, the Compose file binds the service to 127.0.0.1 only by default. For external access, put nginx, Traefik, Caddy, or another reverse proxy in front.

Check:

curl http://localhost:8090/health

Choose an installation​

Install only the compatibility gateway when you need the OpenAI-, Anthropic-, or Gemini-shaped HTTP API:

uv tool install --prerelease allow gpt2giga
gpt2giga

The current Unified Harness alpha line is 0.4.1a1. Install the local control plane from your package index with:

uv tool install 'gpt2giga-harness==0.4.1a1'
giga doctor
giga --version
giga ui

Install gpt2giga-harness[gpt2giga]==0.4.1a1 instead when this environment should also provide Direct Chat and the local gpt2giga provider preset.

The Unified Harness guide also documents the always-available source-checkout path for development and prerelease evaluation.

Prefix an existing native agent command with exactly giga:

giga codex exec --json "inspect this repository"
giga claude -p "inspect this repository"
giga gemini -p "inspect this repository"

Do not replace Claude or Gemini syntax with an invented common exec command. Run giga doctor --json for L0/L1/L2 compatibility and giga completion bash|zsh|fish|powershell to generate conservative root completion.

The Harness distribution uses the gpt2giga_harness Python namespace and provides the giga and gpt2giga-harness commands. The gateway distribution provides only the gpt2giga command.

Alpha preview

Unified Harness is under active development. Start with local, supervised workflows and read the Unified Harness prerelease guide before enabling edit mode, remote access, or scheduled jobs.

Run from the repository​

Install both editable workspace members and the development dependencies:

uv sync --all-packages --all-extras --dev
uv run gpt2giga

In DEV, the FastAPI docs are available at http://localhost:8090/docs. In PROD they are disabled.

OpenAI SDK​

from openai import OpenAI

api_version = "v1"
client = OpenAI(
    base_url=f"http://localhost:8090/{api_version}/",
    api_key="<local-proxy-api-key>",
)

completion = client.chat.completions.create(
    model="GigaChat-2-Max",
    messages=[{"role": "user", "content": "Briefly explain SSE"}],
)
print(completion.choices[0].message.content)

To explicitly select the GigaChat backend contract, use api_version = "v1" or api_version = "v2" and pass it into base_url. /v1 always selects the GigaChat v1 contract, /v2 selects the GigaChat v2 contract. http://localhost:8090 without a version follows GPT2GIGA_GIGACHAT_API_MODE=v1|v2.

Anthropic SDK​

from anthropic import Anthropic

api_version = "v1"
client = Anthropic(
    base_url=f"http://localhost:8090/{api_version}/",
    api_key="<local-proxy-api-key>",
)

message = client.messages.create(
    model="GigaChat-2-Max",
    max_tokens=512,
    messages=[{"role": "user", "content": "Briefly explain SSE"}],
)
print(message.content[0].text)

Gemini SDK​

The official Gemini client appends /v1beta/models/... itself, so pass the gateway root rather than /v1 or /v2:

from google import genai
from google.genai import types

client = genai.Client(
    api_key="<local-proxy-api-key>",
    http_options=types.HttpOptions(base_url="http://localhost:8090"),
)
response = client.models.generate_content(
    model="GigaChat-2-Max",
    contents="Briefly explain SSE",
)
print(response.text)

To select a GigaChat backend contract for Gemini, include /v1 or /v2 in the operation URL or use the corresponding integration configuration. See the Gemini examples for streaming, tools, structured output, token counting, and embeddings.

Per-request GigaChat authorization​

If a client must pass GigaChat authorization via Authorization, enable:

GPT2GIGA_PASS_TOKEN=True

Supported header values:

  • giga-cred-<credentials>:<scope> for GigaChat authorization key credentials;
  • giga-auth-<access_token> for a ready access token;
  • giga-user-<user>:<password> for username/password authorization.

For typical deployment scenarios, server-side GIGACHAT_* credentials are preferable. Enable GPT2GIGA_PASS_TOKEN=True only if you need client-specific upstream credentials.

Examples​