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

# AWS Reference

> Manage, customize, and troubleshoot your AWS deployment.

## Manage

| Task            | Command                    |
| :-------------- | :------------------------- |
| Deploy updates  | `ag infra patch --env prd` |
| Stop deployment | `ag infra down --env prd`  |
| Force rebuild   | `ag infra up --env dev -f` |
| Restart local   | `ag infra up`              |

<Warning>
  `ag infra down --env prd` removes all AWS resources, including the database. Back up your data first.
</Warning>

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

    ```bash theme={null}
    ag infra up --env dev
    ```
  </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">
    Update your agent:

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

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

    Add the dependency to `pyproject.toml` and regenerate requirements:

    ```bash theme={null}
    ./scripts/generate_requirements.sh
    ag infra up --env dev
    ```
  </Accordion>

  <Accordion title="Add dependencies">
    1. Edit `pyproject.toml`
    2. Regenerate requirements: `./scripts/generate_requirements.sh`
    3. Rebuild: `ag infra up --env dev`

    To upgrade all libraries:

    ```bash theme={null}
    ./scripts/generate_requirements.sh upgrade
    ```
  </Accordion>

  <Accordion title="Enable Slack">
    Add your credentials to `infra/secrets/prd_api_secrets.yml`:

    ```yaml theme={null}
    SLACK_BOT_TOKEN: xoxb-...
    SLACK_SIGNING_SECRET: ...
    ```

    Redeploy to AWS:

    ```bash theme={null}
    ag infra up prd:aws
    ```

    The interface activates automatically. 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}
# Set up environment
./scripts/venv_setup.sh
source .venv/bin/activate

# Start PostgreSQL (required)
docker run -d --name agentos-db \
  -e POSTGRES_USER=ai -e POSTGRES_PASSWORD=ai -e POSTGRES_DB=ai \
  -p 5432:5432 pgvector/pgvector:pg17

# 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            |
| `PORT`                 | No         | `8000`                  | API server port                           |
| `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="AWS credentials error">
    Reconfigure credentials with `aws configure`, then validate with `aws sts get-caller-identity`.
  </Accordion>

  <Accordion title="RDS connection timeout">
    RDS can take about 5 minutes to become available. Check status in AWS Console (RDS → Databases).
  </Accordion>

  <Accordion title="ECS task failing">
    Check CloudWatch logs for container startup errors, missing environment variables, or database connectivity issues.
  </Accordion>

  <Accordion title="Load Balancer returns 503">
    The ECS service may still be starting. Wait 2-3 minutes for target health checks to pass.
  </Accordion>
</AccordionGroup>