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

# Local Development

> Build and run your application locally with Docker

Local development uses Docker Compose. Resources are defined in `infra/dev_resources.py`.

## Start Local Environment

```bash theme={null}
ag infra up
```

This starts:

* PostgreSQL database (port 5432)
* AgentOS API (port 8000)

Access points:

* **API docs:** [http://localhost:8000/docs](http://localhost:8000/docs)
* **Health check:** [http://localhost:8000/health](http://localhost:8000/health)

## View Logs

```bash theme={null}
docker logs -f {infra_name}-api
```

Expected startup output:

```
INFO:     Started server process [1]
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000
```

## Building Custom Images

By default, the dev environment uses pre-built `agno` images. To build your own:

### 1. Update Settings

```python infra/settings.py theme={null}
infra_settings = InfraSettings(
    ...
    image_repo="local",
    build_images=True,
)
```

### 2. Build the Image

```bash theme={null}
ag infra up dev:docker -t image
```

Force rebuild (no cache):

```bash theme={null}
ag infra up dev:docker -t image -f
```

## Common Operations

| Task               | Command                                    |
| ------------------ | ------------------------------------------ |
| Start all          | `ag infra up`                              |
| Stop all           | `ag infra down`                            |
| Restart containers | `ag infra restart dev:docker -t container` |
| Rebuild everything | `ag infra up dev:docker -f`                |
| View API logs      | `docker logs -f {infra_name}-api`          |
| View DB logs       | `docker logs -f {infra_name}-db`           |

## Target Types

The `-t` flag filters what to create:

| Target      | Creates           |
| ----------- | ----------------- |
| (none)      | Everything        |
| `image`     | Docker image only |
| `container` | Containers only   |

## Troubleshooting

| Issue            | Solution                                                        |
| ---------------- | --------------------------------------------------------------- |
| Port 8000 in use | Stop other services: `docker ps` then `docker stop <container>` |
| Port 5432 in use | Stop local PostgreSQL: `brew services stop postgresql`          |
| Database errors  | Restart: `ag infra down && ag infra up`                         |
| Old image cached | Force rebuild: `ag infra up dev:docker -t image -f`             |