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 a model, and send a request.

The resource-creation steps use the AISIX Cloud Admin API so you can copy, paste, and automate them. You attach the gateway once in the dashboard. The dashboard can also create each resource used in this quickstart.

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.

This deployment has two parts:

  • The management stack contains the control-plane services (cp-api and dp-manager), the dashboard, and a bundled PostgreSQL database. You install the stack with one command and use it to manage gateways.
  • One or more AISIX gateways attach to the control plane as data planes and serve AI traffic.

Prerequisites​

  • Install Docker with Docker Compose V2.
  • Install cURL, jq, tar, and OpenSSL. The bootstrap script uses cURL, tar, and OpenSSL; the resource steps use cURL and jq.
  • Make sure the installation host can reach run.api7.ai and Docker Hub.
  • 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 script downloads the on-premises package into ./aisix-self-hosted, generates a .env file with fresh secrets, pulls the container images from Docker Hub, and starts the stack. When startup finishes, it prints the dashboard URL. The default is http://localhost:8080. Manage the running stack with ./aisix-self-hosted/run.sh (logs, stop, down).

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 Docker Compose service, which runs cp-api, so the dashboard uses the updated endpoint:

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

Create an Admin Token​

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

  1. Open the dashboard (default http://localhost:8080), select Create an account to register the first user, then create your first organization.
  2. Go to Admin tokens, select New token, enable the write scope required to create resources, and create the token.
  3. Copy the token (aisix_pat_...). The plaintext is shown only once.

Set the API base URL and your token:

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

Create Gateway Resources​

Create the resources the gateway needs through the AISIX Cloud Admin API. Each command saves an ID for the next step. If curl or jq reports an error, stop and resolve it before continuing; a missing ID causes later commands to fail.

Create an environment to scope your resources:

ENV=$(curl -fsS -X POST "$AISIX_CP/environments" \
  -H "Authorization: Bearer $AISIX_TOKEN" -H "Content-Type: application/json" \
  -d '{"display_name": "prod"}')
ENV_ID=$(echo "$ENV" | jq -er '.environment.id')
export ENV_ID

Create a provider key that stores your OpenAI credential, allowed in that environment:

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

PROVIDER_KEY=$(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"'"]
  }')
PROVIDER_KEY_ID=$(echo "$PROVIDER_KEY" | jq -er '.provider_key.id')
export PROVIDER_KEY_ID

Create a gpt-4o-mini model backed by that provider key. Clients send gpt-4o-mini, and AISIX AI Gateway calls OpenAI with the same upstream model:

MODEL=$(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"'"
  }')
MODEL_ID=$(echo "$MODEL" | jq -er '.model.id')
export MODEL_ID

Create a caller API key allowed to use that model. The plaintext key is returned only once, so save it:

API_KEY=$(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"'"]
  }')
AISIX_API_KEY=$(echo "$API_KEY" | jq -er '.plaintext')
export AISIX_API_KEY
echo "$AISIX_API_KEY"

Confirm every resource was created before continuing. An empty or null value means that the create call failed. Run the command again and read its response; a common cause is a 401 or 403 response from an admin token without the write scope.

printf 'ENV_ID=%s\n' "$ENV_ID"
printf 'PROVIDER_KEY_ID=%s\n' "$PROVIDER_KEY_ID"
printf 'MODEL_ID=%s\n' "$MODEL_ID"
printf 'AISIX_API_KEY=%s\n' "$AISIX_API_KEY"

Attach a Gateway​

The control plane does not serve traffic by itself. Attach an AISIX AI Gateway to your environment:

  1. In the dashboard, open your environment's Data planes view, issue a gateway certificate, and copy the generated install snippet. See Connect an AISIX Gateway.
  2. On Linux, add --add-host host.docker.internal:host-gateway to the generated docker run command so the gateway container can reach dp-manager on the host. Docker Desktop resolves host.docker.internal automatically.
  3. Run the gateway with that snippet on your local machine. An AISIX gateway connected to AISIX Cloud binds its proxy listener to port 3000 by default.

Wait until the dashboard shows the gateway as a healthy data plane for your environment. Your gpt-4o-mini model is then projected to that gateway.

Send a Request​

With the gateway serving on http://127.0.0.1:3000, send a request using the caller API key created earlier:

curl -sS -X POST "http://127.0.0.1:3000/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."}
    ]
  }'

Verify the Request and Usage​

You should receive an OpenAI-compatible chat-completions response with an assistant message. In the dashboard, usage for that request appears for your environment, confirming the request flowed through AISIX AI Gateway.

Clean Up​

Delete the caller API key, model, and provider key from the dashboard when you no longer need the example resources.

To stop the local containers without removing them, run:

./aisix-self-hosted/run.sh stop

To stop and remove the containers while preserving the PostgreSQL data volume, run:

./aisix-self-hosted/run.sh down

Next Steps​

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