> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-codex-homepage-20260719-015142.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Locally

> Run AgentOS and Postgres locally with Docker.

Today we're going to run an agent platform made of:

* AgentOS on FastAPI
* Postgres + pgvector

## Prerequisites

* [Docker Desktop](https://docs.docker.com/desktop/) installed and running
* An [OpenAI API key](https://platform.openai.com/api-keys) for models and embeddings

## Run your agent platform

<Steps>
  <Step title="Clone the template">
    ```bash theme={null}
    git clone https://github.com/agno-agi/agentos-railway.git agent-platform
    cd agent-platform
    ```

    <Tip>
      Make the codebase yours by pushing it to a repository you own. To start with a clean Git history, run these commands inside the cloned `agent-platform` directory:

      ```bash theme={null}
      rm -rf .git
      git init
      git add .
      git commit -m "Initial commit"
      git branch -M main
      git remote add origin https://github.com/your-org/your-repo.git
      git push -u origin main
      ```

      `rm -rf .git` removes the template's Git history. Replace the repository URL before running the final two commands.
    </Tip>
  </Step>

  <Step title="Configure your environment">
    ```bash theme={null}
    cp example.env .env
    ```

    Open `.env` and set `OPENAI_API_KEY`. Everything else has sensible defaults.
  </Step>

  <Step title="Start the platform">
    ```bash theme={null}
    docker compose up -d --build
    ```

    This runs two containers: a FastAPI app on port 8000 and a Postgres database on port 5432. The first build takes a few minutes.
  </Step>

  <Step title="Verify it's running">
    Open [http://localhost:8000/docs](http://localhost:8000/docs).

    You'll see the OpenAPI spec: every agent action exposed as a REST endpoint.

    <Frame caption="AgentOS API">
      <img src="https://mintcdn.com/agno-v2-codex-homepage-20260719-015142/eh3ruyt1i8EA1Ky0/videos/first-agent-api.gif?s=ef3ff6ecca3aa5042022895870eb5ce0" alt="AgentOS API" width="800" height="524" data-path="videos/first-agent-api.gif" />
    </Frame>
  </Step>

  <Step title="Verify the MCP interface">
    ```bash theme={null}
    ./scripts/mcp_check.sh
    ```

    This checks the MCP handshake, tool discovery, and one agent run against the local platform.
  </Step>
</Steps>

You now have AgentOS on FastAPI with Postgres and pgvector. The API exposes 80+ endpoints for runs, sessions, memory, knowledge, and evals.

## Connect the AgentOS UI

1. Open [os.agno.com](https://os.agno.com) and sign in.
2. Click **Connect OS**, enter `http://localhost:8000` as the URL, and name it **Local AgentOS**.
3. Click **Connect**.

You should see three agents:

| Agent                | Pattern          | What it does                                                    |
| -------------------- | ---------------- | --------------------------------------------------------------- |
| **Agent Builder**    | Studio builder   | Builds agents, teams, and workflows from a chat prompt.         |
| **Platform Manager** | Context provider | Monitors the platform and answers questions about the codebase. |
| **WebSearch**        | Direct tools     | Searches the web and synthesizes answers grounded in citations. |

Try a prompt against each:

> *"Build an agent that tracks AI news and writes a daily brief"* → **Agent Builder** creates the agent through AgentOS Studio.

> *"How healthy is the platform?"* → **Platform Manager** answers from eval history, deployment checks, and schedules.

> *"What did Anthropic publish about agents recently?"* → **WebSearch** returns a summary with citations.

After Agent Builder finishes, click **Refresh**, choose the new agent from the **Agents** dropdown, and try it.

Open **Sessions** and **Traces** in the sidebar. They capture message history, tool calls, and timing so you can inspect behavior and improve your agents.

## Summary

| Capability       | What is running                                                                                          |
| ---------------- | -------------------------------------------------------------------------------------------------------- |
| Runtime          | AgentOS on port 8000 with request isolation, session management, scheduling, MCP, and 80+ REST endpoints |
| State            | Postgres for sessions, memory, knowledge, traces, schedules, and eval history                            |
| Development loop | Six skills in `.agents/skills/` for setup, creation, extension, improvement, evaluation, and maintenance |

<Tip>
  Hot-reload is on. Edits to Python files in the source (`agents/`, `app/`, `db/`, `evals/`, `workflows/`) are live in \~2s.
</Tip>

## Next

[Create an agent →](/agent-platform/create-agent)