> ## Documentation Index
> Fetch the complete documentation index at: https://gateway.forceaisecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin onboarding

> A new administrator's start-to-finish path: add a model, add a router, build a governed agent, publish it, and scope it to a team.

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

<Note>
  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.
</Note>

## 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

<Steps>
  <Step title="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

    <Check>The model appears under All Models with a healthy status.</Check>
  </Step>

  <Step title="Validate it in the Playground">
    AI Gateway -> Playground -> Chat. Select the model and send "reply with OK"

    <Check>You get an answer, and the call shows up under Observability -> Logs with a cost. That proves the credential, routing, and spend pipeline together.</Check>
  </Step>

  <Step title="Put a router in front">
    A router lets an agent name one stable target while ForceAI picks the model per
    request.

    <Tabs>
      <Tab title="Resilience (primary + fallback)">
        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
      </Tab>

      <Tab title="Smart routing (by difficulty)">
        Models + Endpoints -> Add Model -> Add Auto Router. Choose the Complexity Router to
        map SIMPLE, MEDIUM, COMPLEX, and REASONING tiers to different models, or the
        Semantic Router to route by similarity to example phrasings. Give it an Auto Router
        Name and a Default Model
      </Tab>
    </Tabs>

    <Check>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.</Check>
  </Step>

  <Step title="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

    <Check>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.</Check>
  </Step>

  <Step title="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

    <Check>The agent appears in the public agent hub listing end users browse.</Check>
  </Step>

  <Step title="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

    <Check>The agent's Entitlements list the server's tools, and a tool round shows in Logs.</Check>
  </Step>

  <Step title="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

    <Check>Send a request that should be blocked; confirm it is refused and Observability -> Guardrails Monitor records it.</Check>
  </Step>

  <Step title="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

    <Check>Put a tiny budget on a test key, spend past it, and confirm the next call is refused.</Check>
  </Step>

  <Step title="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

    <Check>A team member, on a team key, sees only the team's models and tools.</Check>
  </Step>

  <Step title="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

    <Check>Calling the gateway with the new key reaches only its allowed models and bills the right team.</Check>
  </Step>
</Steps>

## Day two: watch it

<CardGroup cols={3}>
  <Card title="Usage" icon="chart-line">
    Spend by team, model, and key
  </Card>

  <Card title="Logs" icon="list">
    Every request with model, cost, and correlation id
  </Card>

  <Card title="Guardrails Monitor" icon="shield">
    What was blocked and why
  </Card>
</CardGroup>

## 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