Skip to main content
API7.ai Logo

On-Premises AISIX Cloud Quickstart

In this quickstart, you run an on-premises AISIX Cloud deployment — the control plane, dashboard, and an AISIX gateway — on your own machine. You then configure a model and send a request.

The resource-creation steps use the AISIX Cloud Admin API (cp-api) so you can copy, paste, and automate them. Attaching a gateway (Step 4) is a one-time action in the dashboard, and every resource step can also be done in the dashboard.

Licensing

The AISIX gateway is open-source software under the Apache License 2.0. The on-premises 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, talk to API7 or email support@api7.ai.

An on-premises AISIX Cloud deployment has two parts:

  • the control plane and dashboard — cp-api, dp-manager, the dashboard, and a bundled PostgreSQL. You install these with one command; you administer AISIX AI Gateway through the cp-api or the dashboard.
  • one or more AISIX AI Gateways — the data planes that attach to the control plane and serve the AI traffic.

Prerequisites​

  • Install Docker with Docker Compose.
  • Install cURL and jq to call the API and read IDs from responses.
  • An OpenAI API key (or another supported provider key) to back a model.

Step 1 — Start AISIX Cloud​

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

Step 2 — Create an Admin Token​

The 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 mint it.
  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"

Step 3 — Create an Environment, a Model, and a Caller API Key​

Create the resources AISIX AI Gateway needs, through the cp-api. Each command saves an ID for the next step.

Create an environment to scope your resources:

ENV=$(curl -sS -X POST "$AISIX_CP/environments" \
  -H "Authorization: Bearer $AISIX_TOKEN" -H "Content-Type: application/json" \
  -d '{"display_name": "prod"}')
export ENV_ID=$(echo "$ENV" | jq -r '.environment.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 -sS -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" | jq -r '.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 -sS -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" | jq -r '.model.id')

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

API_KEY=$(curl -sS -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 AISIX_API_KEY=$(echo "$API_KEY" | jq -r '.plaintext')
echo "$AISIX_API_KEY"

Confirm every resource was created before continuing. An empty or null value means that create call failed — re-run it and read its response, most often a 401 or 403 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"

Step 4 — 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. 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.

Step 5 — Send a Request​

With the gateway serving on http://127.0.0.1:3000, send a request using the caller API key from Step 3:

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 It Works​

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.

Other setups
  • Prefer a visual UI? You can do every step above in the dashboard instead — create the environment, provider key, model, and caller API key from the browser.
  • Want only a standalone gateway, with no control plane or dashboard? Use the Open-Source AISIX Gateway Quickstart — it runs an AISIX AI Gateway in one container, configured from a declarative resources.yaml file.

Next Steps​

You now run AISIX Cloud on premises and have sent a request through its AISIX gateway. From here: