> ## Documentation Index
> Fetch the complete documentation index at: https://phidatainc-studio-tools-doc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Reference

> Manage, customize, and troubleshoot your Docker deployment.

## Manage

| Task                  | Command                        |
| :-------------------- | :----------------------------- |
| Start containers      | `docker compose up -d --build` |
| View logs             | `docker compose logs -f`       |
| Restart containers    | `docker compose restart`       |
| Stop containers       | `docker compose down`          |
| Stop and remove data  | `docker compose down -v`       |
| Rebuild after changes | `docker compose up -d --build` |

## Customize

<AccordionGroup>
  <Accordion title="Add an agent">
    Create `agents/my_agent.py`:

    ```python theme={null}
    from agno.agent import Agent
    from agno.models.openai import OpenAIResponses
    from db import get_postgres_db

    my_agent = Agent(
        id="my-agent",
        name="My Agent",
        model=OpenAIResponses(id="gpt-5.5"),
        db=get_postgres_db(),
        instructions="You are a helpful assistant.",
    )
    ```

    Register in `app/main.py`:

    ```python theme={null}
    from agents.my_agent import my_agent

    agent_os = AgentOS(
        name="AgentOS",
        agents=[web_search, code_search, my_agent],
    )
    ```

    Restart: `docker compose restart agentos-api`
  </Accordion>

  <Accordion title="Add tools">
    Agno includes 100+ tool integrations. See the [full list](/tools/overview).

    ```python theme={null}
    from agno.tools.slack import SlackTools
    from agno.tools.google_calendar import GoogleCalendarTools

    my_agent = Agent(
        tools=[
            SlackTools(),
            GoogleCalendarTools(),
        ],
    )
    ```
  </Accordion>

  <Accordion title="Use a different model">
    Add your API key to `.env` and update your agent:

    ```python theme={null}
    from agno.models.anthropic import Claude

    my_agent = Agent(
        model=Claude(id="claude-sonnet-4-5"),
    )
    ```

    Add `anthropic` to `pyproject.toml` and rebuild:

    ```bash theme={null}
    ./scripts/generate_requirements.sh upgrade
    docker compose up -d --build
    ```
  </Accordion>

  <Accordion title="Add dependencies">
    1. Edit `pyproject.toml`
    2. Regenerate requirements: `./scripts/generate_requirements.sh upgrade`
    3. Rebuild: `docker compose up -d --build`
  </Accordion>

  <Accordion title="Enable Slack">
    Set both variables in `.env`:

    ```bash theme={null}
    SLACK_BOT_TOKEN=xoxb-...
    SLACK_SIGNING_SECRET=...
    ```

    The interface activates automatically on restart. See [Slack setup](/deploy/interfaces/slack/overview) for creating the Slack app.
  </Accordion>
</AccordionGroup>

## Local Development

Run without Docker for faster iteration:

```bash theme={null}
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Set up environment
./scripts/venv_setup.sh
source .venv/bin/activate

# Start PostgreSQL (required)
docker compose up -d agentos-db

# Run AgentOS
python -m app.main
```

## Environment Variables

| Variable               | Required   | Default                 | Description                               |
| :--------------------- | :--------- | :---------------------- | :---------------------------------------- |
| `OPENAI_API_KEY`       | Yes        | —                       | OpenAI API key                            |
| `RUNTIME_ENV`          | No         | `prd`                   | `dev` enables hot-reload and disables JWT |
| `JWT_VERIFICATION_KEY` | Production | —                       | Public key from os.agno.com               |
| `AGENTOS_URL`          | No         | `http://127.0.0.1:8000` | Scheduler base URL                        |
| `SLACK_BOT_TOKEN`      | No         | —                       | Enable Slack interface                    |
| `SLACK_SIGNING_SECRET` | No         | —                       | Enable Slack interface                    |
| `PARALLEL_API_KEY`     | No         | —                       | Parallel SDK key for WebSearch            |
| `DB_HOST`              | No         | `localhost`             | Database host                             |
| `DB_PORT`              | No         | `5432`                  | Database port                             |
| `DB_USER`              | No         | `ai`                    | Database user                             |
| `DB_PASS`              | No         | `ai`                    | Database password                         |
| `DB_DATABASE`          | No         | `ai`                    | Database name                             |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Port already in use">
    Modify `compose.yaml`: change `"8000:8000"` to `"8080:8000"` under the `agentos-api` service ports.
  </Accordion>

  <Accordion title="Database connection issues">
    Ensure PostgreSQL is running: `docker compose ps`. If the database isn't ready, wait a few seconds and try again.
  </Accordion>

  <Accordion title="Container keeps restarting">
    Check logs: `docker compose logs agentos-api`. Common causes: missing `OPENAI_API_KEY` in `.env` or database not yet available.
  </Accordion>
</AccordionGroup>