> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-ai-gateway/quick-start.md).

# Quick start

Both gateways running on one machine in a few minutes, checked end to end without a model provider.

You need Docker with Compose v2 and access to the `VirtusLab/visdom-ai-gateway` repository.

{% stepper %}
{% step %}

### Get the repository and generate secrets

```bash
git clone https://github.com/VirtusLab/visdom-ai-gateway.git
cd visdom-ai-gateway
./scripts/init-env.sh
```

`init-env.sh` writes `deploy/compose/.env` with random values for every secret and refuses to overwrite an existing file.
{% endstep %}

{% step %}

### Start the gateways

```bash
cd deploy/compose
docker compose --profile smoke up -d
```

The LLM gateway listens on port 4000 and the MCP gateway on 4444. The `smoke` profile adds a one-tool MCP server the test registers; leave it out in any real installation. Both create their database schema on first start; give them a minute.
{% endstep %}

{% step %}

### Run the smoke test

```bash
cd ../..
./scripts/smoke-test.sh
```

```
Visdom AI Gateway smoke test
  ok   LLM gateway is live
  ok   MCP gateway is live
  ok   team created with a 10 USD budget and an alert at 8 USD (80%): …
  ok   virtual key issued to the team
  ok   OpenAI-compatible call through the key: "Visdom AI Gateway is up."
  ok   model outside the team's allow-list refused (HTTP 403)
  ok   spend attributed to the team: 5e-05 USD
  ok   key over its hard budget refused (HTTP 429)
  ok   Anthropic Messages call through the same key: "Visdom AI Gateway is up."
  ok   MCP gateway refuses a call without a token (HTTP 401)
  ok   tool server registered, its tool discovered: echo-…-echo
  ok   virtual server with a curated tool set: /servers/…/mcp
  ok   tool called over MCP Streamable HTTP through the gateway: "echo: ping"
all checks passed
```

The test uses a built-in model alias, `visdom-smoke`, that answers without calling any provider, and the one-tool MCP server from the `smoke` profile.
{% endstep %}

{% step %}

### Connect a real model

Add the provider credential to `deploy/compose/.env`, uncomment the matching entry in `deploy/compose/litellm/config.yaml`, and restart the LLM gateway:

```bash
docker compose up -d llm-gateway
```

Then point a client at the gateway with a virtual key, for example Claude Code:

```bash
export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_AUTH_TOKEN=<virtual key>
```

or any OpenAI SDK with `base_url="http://localhost:4000/v1"`. The client asks for a model by name; that name must be an alias in `config.yaml` and on the team's allow-list.
{% endstep %}
{% endstepper %}

Next: [Teams, keys and budgets](/visdom-ai-gateway/user-guide/teams-keys-and-budgets.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.visdom.virtuslab.com/visdom-ai-gateway/quick-start.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.