Skip to main content
API7.ai Logo

Open-Source AISIX Gateway Quickstart

This gateway-only quickstart runs just the AISIX AI Gateway data plane in a single container. You declare every gateway resource in one resources.yaml file, start the gateway with Docker, and send one request through the OpenAI-compatible proxy API. No dashboard, no control plane, and no separate configuration store are required. It is the fastest path to a first proxied request.

note

For the complete self-hosted deployment with a dashboard — visual resource management, gateway certificate issuance, and usage reporting — use the AISIX On-Premises Quickstart instead. The self-hosted control plane is also the recommended way to manage several gateways from one place.

This quickstart uses OpenAI as the example upstream provider. In AISIX, the client sends a caller API key, and the gateway uses the configured provider key when it calls the upstream provider.

The request follows this path:

The client sends the caller API key and the AISIX model name gpt-4o-mini. AISIX authenticates the client and uses the stored provider key to call OpenAI with the same upstream model. The client never sends the upstream OpenAI key.

Prerequisites​

  • Install Docker to run the AISIX AI Gateway container.
  • Install cURL to send requests to the gateway.
  • Prepare an OpenAI API key for an account with access to gpt-4o-mini and available quota.

Create the Resources File​

First, create a working directory:

mkdir aisix-quickstart
cd aisix-quickstart

Gateway resources — provider keys, models, and caller API keys — are declared together in one resources.yaml file. Create it:

resources.yaml
_format_version: "1"

provider_keys:
  - display_name: openai-main
    provider: openai
    adapter: openai
    api_key: ${OPENAI_API_KEY}
    api_base: https://api.openai.com/v1

models:
  - display_name: gpt-4o-mini
    provider: openai
    model_name: gpt-4o-mini
    provider_key: openai-main

api_keys:
  - display_name: quickstart-caller
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-mini

❶ _format_version: "1" is mandatory and must be a quoted string. It pins the file format so a future revision can never silently misread this file.

❷ ${OPENAI_API_KEY} is resolved from the gateway's environment when the file loads, so the file itself never contains the upstream credential. A referenced variable that is unset or empty fails the load.

❸ provider_key references the provider key above by its display_name. A reference to an undefined name fails the load, so a typo can never become a silent runtime failure.

❹ key_env names an environment variable that holds the plaintext caller API key. The gateway hashes the value at load time and stores only the hash. Do not start the variable name with AISIX_, because that prefix is reserved for startup-configuration overrides. To supply a precomputed SHA-256 hash instead, set key_hash in place of key_env.

Entries carry no id field. The gateway derives stable IDs from each entry's name, so names must be unique within each collection.

Besides the three resource kinds above, the same file can declare guardrails, mcp_servers, a2a_agents, cache_policies, observability_exporters, and rate_limit_policies.

Create the Startup Configuration​

Create a config.yaml file that points the gateway at the resources file:

config.yaml
resources_file: /etc/aisix/resources.yaml

proxy:
  addr: "0.0.0.0:3000"

admin:
  addr: "0.0.0.0:3001"
  admin_keys:
    # Replace with a strong admin key.
    - "YOUR_ADMIN_KEY"

❶ resources_file selects the file as the gateway's resource source. With this setting, the gateway does not use an external configuration store, so the etcd section is omitted. The two are mutually exclusive.

For the remaining startup options, see Configuration Files.

Start AISIX AI Gateway​

Start the gateway container, mounting both files and passing the two environment variables the resources file references:

# Replace with your OpenAI API key.
export OPENAI_API_KEY="YOUR_PROVIDER_API_KEY"

# Choose a caller API key for client requests.
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

docker run -d --name aisix-quickstart \
  -v "$(pwd)/config.yaml:/etc/aisix/config.yaml:ro" \
  -v "$(pwd)/resources.yaml:/etc/aisix/resources.yaml:ro" \
  -e OPENAI_API_KEY \
  -e CALLER_API_KEY \
  -p 3000:3000 -p 9090:9090 \
  ghcr.io/api7/aisix:latest

If any resource entry is invalid, the container exits at startup and docker logs aisix-quickstart prints every load error together — kind, entry, and field — rather than only the first one.

Verify It Works​

The gateway exposes the proxy listener on port 3000. Check that it is live:

curl -sS "http://127.0.0.1:3000/livez"

The command should return ok.

List the models visible to the caller API key:

curl -sS "http://127.0.0.1:3000/v1/models" \
  -H "Authorization: Bearer ${CALLER_API_KEY}"

The data array should include gpt-4o-mini:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "created": 1784186096,
      "owned_by": "openai"
    }
  ]
}

Send a chat request through the gateway:

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${CALLER_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Say hello from AISIX AI Gateway."}
    ]
  }'

You should receive an OpenAI chat-completions response similar to the following:

{
  "id": "chatcmpl-DnHR8vV2AmxQioGhIXRVvEGcf22hC",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello from AISIX AI Gateway! How can I assist you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 14,
    "total_tokens": 29
  }
}

Update and Reload the Configuration​

To change gateway resources, edit resources.yaml and reload — the running gateway does not watch the file. This example adds a second model and allows the caller API key to use it:

resources.yaml (updated)
_format_version: "1"

provider_keys:
  - display_name: openai-main
    provider: openai
    adapter: openai
    api_key: ${OPENAI_API_KEY}
    api_base: https://api.openai.com/v1

models:
  - display_name: gpt-4o-mini
    provider: openai
    model_name: gpt-4o-mini
    provider_key: openai-main
  - display_name: gpt-4o
    provider: openai
    model_name: gpt-4o
    provider_key: openai-main

api_keys:
  - display_name: quickstart-caller
    key_env: CALLER_API_KEY
    allowed_models:
      - gpt-4o-mini
      - gpt-4o

Before reloading, check the edited file with aisix validate. It runs the identical load pipeline — ${VAR} interpolation, name-reference resolution, and schema validation — without starting any listener. If anything is wrong, it exits non-zero with the full error report:

docker run --rm \
  -v "$(pwd)/resources.yaml:/etc/aisix/resources.yaml:ro" \
  -e OPENAI_API_KEY \
  -e CALLER_API_KEY \
  --entrypoint /usr/local/bin/aisix \
  ghcr.io/api7/aisix:latest \
  validate --resources /etc/aisix/resources.yaml

Expected output:

OK: /etc/aisix/resources.yaml loaded 4 resource(s)

Then send SIGHUP to the gateway process to reload the file:

docker kill --signal=HUP aisix-quickstart

Confirm that the new configuration was applied by querying GET /status/config on the dedicated metrics listener:

curl -sS "http://127.0.0.1:9090/status/config"

A successful reload reports "state": "synced" and the updated resource counts:

{
  "state": "synced",
  "source": {
    "type": "file",
    "source_hash": "…",
    "observed_at": "2026-07-16T07:15:34Z"
  },
  "applied": {
    "config_hash": "…",
    "apply_seq": 2,
    "applied_at": "2026-07-16T07:15:34Z",
    "resource_counts": {
      "api_keys": 1,
      "models": 2,
      "provider_keys": 1
    }
  },
  "last_reload": {
    "successful": true,
    "at": "2026-07-16T07:15:34Z"
  },
  "last_failure": null,
  "rejected": []
}

If a reload fails, the gateway keeps serving the last valid configuration, state reports out_of_sync, and the rejected array names each offending entry. For every field on this endpoint, see Configuration Status.

note

The gateway still binds an admin listener on port 3001, which the docker run command in this quickstart deliberately does not publish — the declarative flow never needs it. If you do publish it, treat it as sensitive: its read endpoints return resources as loaded, including interpolated provider credentials. Its resource write path is deprecated in favor of declarative configuration; on a file-configured gateway, resource writes are rejected with 409 and a message pointing back at the resources file.

Next Steps​

You have now run a standalone AISIX AI Gateway from one declarative file and sent provider-backed requests through it. From here: