Skip to main content
API7.ai Logo

Open-Source AISIX Gateway Quickstart

Use this quickstart to run the open-source AISIX gateway in a single Docker container and send your first AI request through it. You will declare the required provider key, model, and caller API key in one resources.yaml file, start the gateway, and verify the request through its OpenAI-compatible API.

This setup does not require a dashboard, control plane, or separate configuration store, making it the fastest way to evaluate the gateway locally. The example uses OpenAI as the upstream provider. Your client authenticates to AISIX with a caller API key, while the gateway uses a separate provider key to authenticate to OpenAI.

The request follows this path:

When the client requests the AISIX model name gpt-4o-mini, the gateway authenticates the request with the caller API key and uses the stored provider key to call OpenAI. The upstream OpenAI key is never exposed to the client.

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

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.

The gateway derives stable IDs from resource names, so each name must be unique within its collection.

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:
  enabled: false

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

❷ proxy.addr listens for gateway traffic on port 3000 across all container interfaces. The Docker command below publishes this port at http://127.0.0.1:3000 on the host.

For the remaining startup options, see the Startup Configuration Reference.

Start AISIX AI Gateway​

Export the two values referenced by resources.yaml and the local gateway origin:

# 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"

# This quickstart publishes the gateway at this origin.
export AISIX_PROXY="http://127.0.0.1:3000"

Before starting the gateway, validate resources.yaml in a short-lived container. This catches interpolation, reference, and schema errors without starting a listener:

docker run --rm \
  -v "$(pwd):/etc/aisix: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

The command should report that the file loaded three resources. Then start the gateway, mounting the working directory so later edits remain visible inside the running container:

docker run -d --name aisix-quickstart \
  -v "$(pwd):/etc/aisix: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. docker logs aisix-quickstart reports every invalid kind, entry, and field rather than stopping at the first error.

Verify the Gateway​

Check that the proxy listener is live:

curl -sS "$AISIX_PROXY/livez"

The command should return ok.

List the models visible to the caller API key:

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

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

Send a chat request through the gateway:

curl -sS -X POST "$AISIX_PROXY/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."}
    ]
  }'

The response should use the OpenAI chat-completions format and contain an assistant message under choices[0].message.

Update and Reload the Configuration​

The running gateway does not watch resources.yaml. To apply a change without restarting the container, edit the mounted file, validate it, and then send SIGHUP to the gateway process.

For example, update resources.yaml to add a second model and allow the existing 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

Validate the edited file inside the running container:

docker exec aisix-quickstart \
  /usr/local/bin/aisix validate --resources /etc/aisix/resources.yaml

The command should report that the file loaded four resources. If validation fails, correct the reported entries before continuing.

Reload the file:

docker kill --signal=HUP aisix-quickstart

Confirm that the caller can see both models:

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

The data array should include both gpt-4o-mini and gpt-4o. For configuration states, rejected-resource details, and other resource sources, see Configuration Propagation.

Clean Up​

Stop and remove the quickstart gateway when you are done:

docker rm -f aisix-quickstart

The config.yaml and resources.yaml files in your working directory are untouched.

Next Steps​

You have now run an open-source AISIX gateway from one declarative file and sent provider-backed requests through it. From here: