Skip to main content
API7.ai Logo

AISIX Cloud Quickstart

In this quickstart, you evaluate AISIX Cloud 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 Cloud Admin API so the workflow is reproducible and prepares the environment for subsequent guides. AISIX Cloud 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.

Licensing

The AISIX Cloud control plane and dashboard are commercial software. Certain features are free for development, testing, and evaluation, but production use requires a commercial license. To run the control plane in production, contact API7 or email support@api7.ai.

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. The default dashboard URL is http://localhost:8080.

For this single-host quickstart, open ./aisix-self-hosted/.env and set the data-plane manager URL to:

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

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

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

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 Cloud Admin API authenticates with an organization-scoped admin token. Create one in the dashboard:

  1. Open http://localhost:8080 in a browser and select Create an account.
  2. Register the first user, accept the user agreement, and create your first organization.
  3. In the organization navigation, open Admin tokens and select New token.
  4. Enter quickstart-admin as the name, choose an expiration period, and enable the write scope.
  5. Create the token and copy its plaintext value before leaving the page. The value is shown only once.

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. 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 Cloud 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: