AISIX Enterprise Quickstart

In this quickstart, you evaluate AISIX Enterprise on one machine using Docker Compose, the bundled PostgreSQL database, and local endpoints. You start the control plane and dashboard, attach an AISIX gateway, configure an OpenAI model, and send a request through the gateway.

The local setup runs the control-plane services, dashboard, and PostgreSQL as one management stack. The AISIX gateway runs separately, giving configuration and live traffic distinct paths:

This quickstart configures resources through the AISIX Enterprise Admin API so the workflow is reproducible and prepares the environment for subsequent guides. AISIX Enterprise sends those resources to the gateway. Client requests then travel through the gateway to OpenAI without crossing the control plane, while the dashboard provides gateway status, logs, and usage.

Prerequisites

• Install Docker with Docker Compose V2.
• Install cURL, jq, tar, and OpenSSL.
• Make sure the installation host can reach run.api7.ai, Docker Hub, and OpenAI.
• Make sure ports 5432, 8080, 7944, and 3000 are available on the installation host.
• Use a browser that can reach port 8080 on the installation host.
• Prepare an OpenAI API key for the model configured by this quickstart.

Start the Control Plane

On a host with Docker and internet access, run:

curl -fsSL "https://run.api7.ai/aisix-self-hosted/quickstart" | bash

The installer downloads the current on-premises package into ./aisix-self-hosted, generates a .env file with fresh secrets, pulls the container images, and starts the stack. Back up .env: it contains the database password and master key needed to recover stored provider keys.

Open ./aisix-self-hosted/.env and set the data-plane manager URL to:

AISIX_CLOUD_DPMGR_BASE_URL=https://host.docker.internal:7944

If your browser runs on the installation host, use the default dashboard URL, http://localhost:8080. If you access the dashboard from another machine, also set AISIX_CLOUD_PUBLIC_BASE_URL in .env to the exact origin you will open in the browser, including the scheme and port. For example:

AISIX_CLOUD_PUBLIC_BASE_URL=http://<HOST_IP>:8080

Recreate api and dpm so the dashboard uses the updated manager endpoint and dp-manager issues its TLS certificate for it:

cd aisix-self-hosted
docker compose up -d api dpm

If you changed AISIX_CLOUD_PUBLIC_BASE_URL, also recreate ui before creating an account:

docker compose up -d --force-recreate ui

The ui service uses AISIX_CLOUD_PUBLIC_BASE_URL as its BETTER_AUTH_URL unless you set BETTER_AUTH_URL separately. If account creation returns 403 INVALID_ORIGIN, compare the browser origin with those values and recreate ui after correcting .env.

Check the control-plane health endpoint:

curl -fsS "http://127.0.0.1:8080/healthz"

The command should return {"status":"ok"}. Keep this terminal in the aisix-self-hosted directory for the remaining shell commands.

Create an Admin Token

The AISIX Enterprise Admin API authenticates with an organization-scoped admin token. Create one in the dashboard:

1. Open http://localhost:8080 on the installation host, or the exact URL set in AISIX_CLOUD_PUBLIC_BASE_URL from another machine, and select Create an account.
2. Register your user account and accept the user agreement.
3. Create your first organization. The account that creates it becomes that organization's owner.
4. In the organization navigation, open Admin tokens and select New token.
5. Enter quickstart-admin as the name, choose an expiration period, and enable the write scope.
6. Create the token and copy its plaintext value before leaving the page. The value is shown only once.

Creating the organization makes you its owner. This is an organization role, not a deployment-wide administrator role. See User Accounts and Organization Access for account setup, password recovery status, and the current administrator model.

Export the control-plane API URL and token in the terminal:

export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"

For token scope, expiration, and rotation details, see Admin Tokens.

Create Gateway Resources

Create the environment, provider key, model, and caller API key through the Admin API. The dashboard can create the same resources with the corresponding fields, but this quickstart uses API requests to provide one copyable workflow and retain the IDs used by later guides.

Create the prod environment:

ENV_RESPONSE=$(curl -fsS -X POST "$AISIX_CP/environments" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"display_name": "prod"}')

export ENV_ID=$(echo "$ENV_RESPONSE" | jq -er '.environment.id')
echo "$ENV_RESPONSE" | jq

Create a provider key that stores your OpenAI credential and allow it in the environment:

export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

PROVIDER_KEY_RESPONSE=$(curl -fsS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "display_name": "OpenAI",
    "api_key": "'"${OPENAI_API_KEY}"'",
    "api_base": "https://api.openai.com/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }')

export PROVIDER_KEY_ID=$(echo "$PROVIDER_KEY_RESPONSE" | jq -er '.provider_key.id')
echo "$PROVIDER_KEY_RESPONSE" | jq

Create a gpt-4o-mini model backed by the provider key:

MODEL_RESPONSE=$(curl -fsS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gpt-4o-mini",
    "model_name": "gpt-4o-mini",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }')

export MODEL_ID=$(echo "$MODEL_RESPONSE" | jq -er '.model.id')
echo "$MODEL_RESPONSE" | jq

Create a caller API key that can use the model. Save the plaintext value because it is returned only once:

API_KEY_RESPONSE=$(curl -fsS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "quickstart-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }')

export API_KEY_ID=$(echo "$API_KEY_RESPONSE" | jq -er '.api_key.id')
export AISIX_API_KEY=$(echo "$API_KEY_RESPONSE" | jq -er '.plaintext')
echo "$API_KEY_RESPONSE" | jq

Each command saves the resource ID needed by the next step or by subsequent guides. If curl or jq reports an error, stop and correct it before continuing; a missing ID causes later commands to fail.

Attach an AISIX Gateway

The control plane manages gateway configuration but does not serve AI traffic. Attach a gateway to the prod environment:

1. In the dashboard, open the prod environment, select Data planes, and then select Issue certificate.
2. Open the Docker tab and copy the generated snippet. The snippet contains a gateway certificate and private key, so handle it as a secret.
3. On Linux, add --add-host host.docker.internal:host-gateway to the generated docker run command. Docker Desktop resolves host.docker.internal automatically.
4. Run the snippet. It starts a container named aisix-dp, publishes the proxy on port 3000, and follows the connection logs. When the logs show etcd connected, press Ctrl+C; the gateway continues running in the background.
5. Return to Data planes, refresh the page, and confirm that it reports one connected gateway instance.

For certificate handling, generated deployment commands, networking, and connection troubleshooting, see Connect an AISIX Gateway.

Send and Verify a Request

Export the local gateway origin, then check that it is live:

export AISIX_PROXY="http://127.0.0.1:3000"

Check the proxy listener:

curl -fsS "$AISIX_PROXY/livez"

The command should return ok. A gateway connected to AISIX Enterprise does not bind its proxy listener until it has applied its first configuration from the control plane, so if this command reports a refused connection instead, the gateway has not received that configuration yet. Its log records the wait; the line to look for is first configuration applied — binding the proxy listener. See Startup and the First Configuration. Then confirm that the configured model reached the gateway:

curl -fsS "$AISIX_PROXY/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

The data array should include gpt-4o-mini. Resource projection is asynchronous, so if the model is not listed yet, wait a few seconds and rerun the command. Do not continue until the model appears.

Then send a chat request:

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_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-compatible response with an assistant message under choices[0].message. In the dashboard, open Logs in the prod environment to inspect the request, and open Usage in the organization navigation to review its usage data.

Clean Up

Keep the example resources and admin token if you plan to continue to other AISIX Enterprise guides. Otherwise, delete the resources in dependency order:

curl -fsS -X DELETE \
  "$AISIX_CP/environments/$ENV_ID/api_keys/$API_KEY_ID" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" | jq

curl -fsS -X DELETE \
  "$AISIX_CP/environments/$ENV_ID/models/$MODEL_ID" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" | jq

curl -fsS -X DELETE \
  "$AISIX_CP/provider_keys/$PROVIDER_KEY_ID" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" | jq

Revoke quickstart-admin in the dashboard after the API cleanup if you no longer need it. Then remove the gateway container:

docker rm -f aisix-dp

Stop and remove the control-plane containers:

./run.sh down

This preserves the PostgreSQL data volume.

Next Steps

You have now sent a request through a gateway connected to your local control plane. From here:

• Follow On-Premises Installation to install the control plane for a persistent environment, then deploy gateways with the api7/aisix chart by following Deploy AISIX Gateways on Kubernetes.
• Use the AISIX Enterprise Admin API Reference to automate control-plane operations with the admin token created in this quickstart.
• Read Resource Model to see how provider keys, models, and caller API keys fit together.
• Call the gateway from application code with the OpenAI SDK or Anthropic SDK guide.