Skip to main content
This is the path a brand new administrator follows once the ForceAI Gateway is installed and running. It goes in order from your first login to a governed agent a team can actually use, and every step ends with a quick check so a problem later is never ambiguous about which step caused it
You need the deployment’s master key (the value of LITELLM_MASTER_KEY, sometimes called the ForceAI key). Hand out scoped virtual keys to teams and applications; keep the master key as the break-glass admin credential only.

​
Sign in

Open http://localhost:4000/ui, using your gateway host for a real deployment; the gateway serves the dashboard under /ui. Sign in with username admin and your master key as the password, or a separate UI_PASSWORD if your deployment set one As an administrator you see every section. The left navigation is grouped as AI Gateway, Observability, Access Control, Developer Tools, and Settings, and the walkthrough moves through them in a deliberate order

​
The path

1

Add your first model

AI Gateway -> Models + Endpoints -> Add Model. Pick the provider, give a friendly Public Model Name (for example claude-haiku), set the mode to chat, and supply a credential. Use Test Connection before saving; it runs a real probe so a wrong key fails here, not later inside an agent
The model appears under All Models with a healthy status.
2

Validate it in the Playground

AI Gateway -> Playground -> Chat. Select the model and send “reply with OK”
You get an answer, and the call shows up under Observability -> Logs with a cost. That proves the credential, routing, and spend pipeline together.
3

Put a router in front

A router lets an agent name one stable target while ForceAI picks the model per request.
Register two models with the same Public Model Name so they form one group, then set the failover under Settings -> Router Settings. This is the pattern behind the built-in forceai-auto alias: the primary serves normally, and on failure the approved fallback serves
In the Playground, select the router by name and send an easy and a hard message; confirm in Logs they resolved to different models (complexity router), or that the fallback answers when the primary is forced to fail.
4

Create an agent on the model or router

AI Gateway -> Agentic -> Agents -> Add New Agent. The wizard runs Configure -> Entitlements -> Governance -> Agent Management -> Ready. Set the agent’s Model to your router name so it inherits governed selection and failover. Under Governance attach guardrails and set session budget and TPM/RPM limits; that is where whole-agent governance is turned on
A new agent starts pending. Approve it on the Agents page, invoke it once, and confirm the turn appears in Logs attributed to the agent.
5

Publish it in the AI Hub

Approving makes an agent usable; publishing makes it discoverable. Developer Tools -> AI Hub -> Agent Hub -> Select Agents to Make Public. You can also mark an agent public at creation with the Make Public switch
The agent appears in the public agent hub listing end users browse.
6

Add tools with an MCP server

AI Gateway -> MCP Servers -> Add New MCP Server. Set the name, transport (SSE, HTTP, stdio, or OpenAPI), URL, and auth, and optionally an MCP access group. Attach it to an agent through the agent’s Entitlements step
The agent’s Entitlements list the server’s tools, and a tool round shows in Logs.
7

Add guardrails and a policy

AI Gateway -> Agentic -> Guardrails to create a guardrail, then attach it on a key, an agent’s Governance step, a team, or bundle several into a reusable pipeline under Policies
Send a request that should be blocked; confirm it is refused and Observability -> Guardrails Monitor records it.
8

Set budgets and rate limits

Access Control -> Budgets to create a named budget, then reference it on a key, team, user, or workspace; keys and agents also take an inline budget. Limits apply at several levels and the tightest wins
Put a tiny budget on a test key, spend past it, and confirm the next call is refused.
9

Onboard a team with the right access

Optionally create a Workspace as the top grouping. Create a Team with its allowed models and budget, add people under Internal Users, and create an Access Group to bundle what they may reach. A model access group gates which models are visible; an MCP access group gates which tools are reachable
A team member, on a team key, sees only the team’s models and tools.
10

Mint a virtual key for the team

AI Gateway -> Virtual Keys -> create a key. Set the owner, team, workspace, and allowed models, and under Optional Settings add the budget, rate limits, guardrails, and access groups. Hand this key to the team, never the master key
Calling the gateway with the new key reaches only its allowed models and bills the right team.

​
Day two: watch it

Usage

Spend by team, model, and key

Logs

Every request with model, cost, and correlation id

Guardrails Monitor

What was blocked and why

​
Why this order

Add and prove a model, put a router in front for resilience or smart selection, build the agent on that router so it inherits governed selection, protect it with guardrails and budgets, scope it to a team with an access group and a virtual key, and only then publish it. Every layer rests on one you already proved