> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For full documentation content, see https://docs.astropods.com/llms-full.txt.

# Connect to a private database

Agents run in Astro's managed cloud infrastructure. To reach a database that lives inside your VPN or private network, you need to do two things:

1. Open your network to Astro's outbound IPs so traffic can pass through your firewall.
2. Pass the connection string to your agent as a secret input in `astropods.yml`.

Both options below satisfy step 1. Choose based on your infrastructure.

***

## Option 1: IP allowlisting

Agents egress through a fixed set of NAT Gateway Elastic IPs. Allowlisting these IPs in your firewall or VPN policy is the fastest path, requiring no AWS account or infrastructure changes on your side.

```mermaid
flowchart LR
    subgraph astro["Astro infrastructure"]
        A[Agent pod] --> B[NAT Gateway<br />3.213.168.251<br />13.222.89.6]
    end
    B --> C[Internet]
    subgraph vpn["Your private network / VPN"]
        D[Firewall<br />allowlist] --> E[Your database]
    end
    C --> D
```

<Steps>
  <Step title="Get Astro's egress IPs">
    All agent workloads egress through the following static Elastic IPs. These are fixed and do not change unless we announce it:

    | IP              | CIDR               |
    | --------------- | ------------------ |
    | `3.213.168.251` | `3.213.168.251/32` |
    | `13.222.89.6`   | `13.222.89.6/32`   |
  </Step>

  <Step title="Allowlist the IPs in your network">
    Add each IP to the inbound rules of whatever controls access to your database:

    | Setup                              | Where to add the rule                                                  |
    | ---------------------------------- | ---------------------------------------------------------------------- |
    | AWS RDS / Aurora                   | Security group inbound rule: TCP on your DB port from each IP (`/32`)  |
    | GCP Cloud SQL                      | Authorized networks: add each IP with `/32` mask                       |
    | Azure Database                     | Firewall rules: one rule per IP                                        |
    | Self-hosted (on-prem)              | Firewall / VPN policy: allow TCP from each IP to your DB host and port |
    | Corporate VPN with split tunneling | Add Astro's IPs to your VPN's allowed-source list for the DB subnet    |

    Use the port your database listens on. Common defaults: PostgreSQL `5432`, MySQL `3306`, MSSQL `1433`, MongoDB `27017`, Redis `6379`. Check your database's documentation if you're unsure.
  </Step>

  <Step title="Declare the connection string in astropods.yml">
    Use `inputs` with `secret: true` so credentials are stored encrypted and never logged. The example below uses PostgreSQL; adjust the variable names and connection logic to match your database:

    ```yaml
    spec: blueprint/v1
    name: my-agent

    meta:
      visibility: private

    agent:
      build:
        context: .
        dockerfile: Dockerfile
      inputs:
        - name: DATABASE_URL
          datatype: string
          secret: true
          description: Connection string for your private database
    ```

    At deploy time, `ast configure` will prompt for the value. For PostgreSQL this looks like:

    ```
    postgresql://user:password@your-db-host.internal:5432/mydb?sslmode=require
    ```

    The format and client library will differ for other databases; refer to your database driver's documentation. In your agent code, read the value from the environment:

    ```python
    import os
    import psycopg2  # replace with your database driver

    conn = psycopg2.connect(os.environ["DATABASE_URL"])
    ```

    ```typescript
    import { Pool } from "pg"; // replace with your database driver

    const pool = new Pool({ connectionString: process.env.DATABASE_URL });
    ```
  </Step>
</Steps>

***

## Option 2: AWS PrivateLink

If your database (or a proxy in front of it) runs in an AWS VPC and your security policy does not allow inbound connections from public IPs, you can establish an AWS PrivateLink connection. Traffic flows entirely within the AWS backbone and never touches the public internet.

**How it works:**

```mermaid
flowchart LR
    subgraph astro["Astro VPC"]
        A[Agent pod] --> B[Interface VPC<br />Endpoint]
    end
    subgraph yours["Your VPC / private network"]
        C[VPC Endpoint<br />Service] --> D[Internal NLB] --> E[Your database]
    end
    B --> C
```

**Requirements:**

* Your database is reachable from within an AWS VPC (RDS, Aurora, EC2-hosted, or any service behind an internal NLB).
* You can create a VPC Endpoint Service in that VPC.

<Steps>
  <Step title="Create an internal NLB targeting your database">
    In your AWS VPC, create an internal Network Load Balancer (NLB) that targets your database instance on its port. If your database is already behind a load balancer, you can skip this step.
  </Step>

  <Step title="Create a VPC Endpoint Service">
    Create a VPC Endpoint Service pointing to the NLB. In the AWS Console go to **VPC → Endpoint Services → Create endpoint service**, select your NLB, and note the generated service name, which looks like:

    ```
    com.amazonaws.vpce.us-east-1.vpce-svc-xxxxxxxxxxxxxxxxx
    ```
  </Step>

  <Step title="Contact Astro to establish the connection">
    Email [support@astropods.com](mailto:support@astropods.com) with the following:

    | Field                     | What to provide                                         |
    | ------------------------- | ------------------------------------------------------- |
    | **Endpoint service name** | The full `com.amazonaws.vpce.*` name from step 2        |
    | **Your AWS account ID**   | 12-digit account ID that owns the endpoint service      |
    | **AWS region**            | Region your endpoint service is in (e.g. `us-east-1`)   |
    | **Database port**         | Port your database listens on                           |
    | **Description**           | Brief note on the database type and what agent it's for |

    We'll authorize your account and create an Interface VPC Endpoint on our side.
  </Step>

  <Step title="Use the endpoint hostname in your connection string">
    Once Astro confirms the connection is live, we'll send you a private DNS hostname for the endpoint. Use that as your database host in `DATABASE_URL`, then follow step 3 from Option 1 above to declare it in `astropods.yml`.
  </Step>
</Steps>

<Note>
  PrivateLink requires the same `astropods.yml` input configuration as IP allowlisting (step 3 above). Only the network path differs.
</Note>

***

## Verifying the connection

The fastest way to confirm connectivity is to have your agent attempt a connection on startup and log the result before doing any real work. The exact approach depends on your database driver. If the agent starts successfully after deploy, the network path is clear. If it times out, the IPs are not yet allowlisted or the PrivateLink endpoint is not routing correctly; double-check the firewall rules and reach out to [support@astropods.com](mailto:support@astropods.com).