Knowledge stores
A knowledge store is a database you connect to your account from the Knowledge section of the dashboard. Once connected, any of your agents can use it — so several agents can read and write the same data instead of each keeping its own copy.
Connect a store
In the dashboard, go to Knowledge > Add store and enter your database’s host, port, and credentials. Postgres, MySQL, Redis, Qdrant, Neo4j, and Pinecone are supported. Your credentials are encrypted and never shown in plain text again.
Once the store shows as Ready, it’s available to use with your agents.
If your database is behind a firewall but reachable over the public network, allowlist the Astropods outbound IPs first — see Allowlist the Astropods egress IPs.
Connect a private database
If your database runs in an AWS VPC and you don’t want to expose it to the public internet, connect it over AWS PrivateLink. Traffic flows entirely within the AWS backbone and never touches the public internet.
You’ll need a database reachable inside an AWS VPC (RDS, Aurora, EC2-hosted, or anything behind an internal load balancer) and the ability to create a VPC Endpoint Service in that VPC. For a complete example, see the sample Postgres deployment on EKS.
Expose your database through a VPC Endpoint Service
In your AWS VPC, put an internal Network Load Balancer (NLB) in front of your database, then create a VPC Endpoint Service pointing to that NLB. In the AWS Console go to VPC > Endpoint Services > Create endpoint service, select your NLB, and note the generated service name:
If your database already sits behind an NLB or endpoint service, reuse it.
The NLB’s security group must allow your database port from 100.64.0.0/10 as well as your VPC CIDR. PrivateLink traffic reaches the NLB from 100.64.0.0/10, not from your VPC CIDR. If the rule allows only your VPC CIDR, the NLB drops every Astropods connection without an error. As an alternative, turn off Enforce inbound rules on PrivateLink traffic on the NLB’s security settings. Access is then controlled only by the endpoint service’s allowed principals.
If the NLB comes from a Kubernetes Service managed by the AWS Load Balancer Controller, set both CIDRs in the source-ranges annotation:
The source-ranges key has no aws- prefix. The controller ignores aws-load-balancer-source-ranges and falls back to 0.0.0.0/0.
Your endpoint service must also allow Astropods to connect. When you turn on PrivateLink in the next step, the dashboard shows the principal to allow and the supported region to add. Set both on your endpoint service before you click Connect.
Connect it in the dashboard
Go to Knowledge > Add store, then:
- Give the store a name and select your database type.
- Turn PrivateLink on.
- Paste the
com.amazonaws.vpce.*service name from step 1. - Choose the regions your agents run in. Astropods creates a VPC endpoint in each one, and agents in other regions can’t reach the store.
- Fill in the port, database, and credentials.
- Click Connect.
The store moves to Pending while it waits for your approval.
To connect from the CLI instead, pass the service name as the host to ast knowledge connect:
Approve the connection in AWS
The store’s detail page links you to the right AWS console page. In VPC > Endpoints, approve the pending connection request from Astropods. You get one request for each region you chose.
Wait for Ready
The store turns Ready when the PrivateLink endpoint in every region you chose is available. Ready confirms the endpoint exists, not that your database accepts connections through it.
Confirm traffic reaches your database
Deploy an agent with the store, then ask it a question that only your data can answer. If the agent’s queries hang and time out, see Troubleshooting.
Use a store with an agent
When you deploy an agent that needs a database, the deploy form lets you choose, for each database the agent declares:
- Shared — use one of your connected knowledge stores. The agent gets its connection details automatically, and the same store can be used by as many agents as you like.
- Local — spin up a fresh database just for that deployment. This isn’t a knowledge store and isn’t shared with anything else.
A store can only be used by an agent that asks for the same type of database. Because this is chosen at deploy time, the same agent can use a shared store in one environment and a local one in another.
You make this choice on the dashboard’s deploy form. astropods.yml declares the database the same way for both, and the CLI has no flag for it. A deployment keeps its choice when you redeploy it, including from the CLI.
For the end-to-end walkthrough — declaring a database in your agent, running it locally, and binding a store at deploy — see Using Knowledge stores.
Manage a store
Each store has a detail page in the dashboard where you can check whether it’s connected and healthy, view its logs and activity, and see the connection details your agents receive. If a store gets stuck connecting, the page shows what’s blocking it — most often a PrivateLink connection still waiting for approval in your AWS console.
Troubleshooting
Next steps
- Using Knowledge stores: build and deploy an agent that uses a store, step by step
- Host Postgres on EKS for PrivateLink: run a private database to connect
- Allowlist the Astropods egress IPs: reach a firewalled database over the public network