The short version
- Your database stays private. Only a small SSH host (the bastion) has to be reachable, and only from our gateway's addresses.
- No bastion yet? On AWS (Azure in beta) we prepare a template that creates one in your account in about three minutes.
- We generate the key pair. The private key is encrypted and never shown; you install the public key with one command.
- The key can only open a tunnel to the database address you allow. No shell, no password, no TTY.
- You confirm the bastion's host key once. If it ever changes, every call stops until you trust the new one.
- Removing the key, or running the script with
--uninstall, cuts our access immediately.
1How it works
An SSH bastion (also called a jump host) is a machine with a public address that can also reach your private network. Saywire connects to it over SSH and asks it to forward one TCP connection to your database. The database itself never needs a public address, and our gateway never dials it directly: the bastion does, inside your network.
Saywire gateway ──SSH (22, outbound from us)──► bastion ──TCP──► your database
(public internet) key auth, host key pinned (your network) (private address)
1. The gateway resolves the bastion host and refuses anything that isn't a public address.
2. It checks the bastion's host key against the fingerprint you trusted. Mismatch = stop.
3. It logs in as the tunnel user with the key we generated for you.
4. It asks the bastion to open a TCP stream to the host:port in your connection string.
5. Postgres runs over that stream (TLS too, if you ask for it), in a read-only transaction.
6. The tunnel closes when the tool call ends. Nothing stays connected between calls.Only Postgres connections support a bastion today. If you can't run a public SSH host at all, an outbound connector (a container that dials out to us) is on the way; email us if you need it.
2Requirements
- A Linux host with OpenSSH (Ubuntu, Debian, Amazon Linux, RHEL and friends). A t4g.nano, e2-micro or Hetzner CX22 is plenty.
- A public IP or DNS name for it, with the SSH port (usually 22) open to our gateway's addresses (the dashboard shows them).
- A route to the database on its Postgres port (security group, firewall rule or private network).
- A database user for Saywire, ideally read-only (see below).
AllowTcpForwardingnot set tonoglobally. The script checks this, and setslocalfor the tunnel user only.
3One click on AWS or Azure (beta)
The AWS template is tested end to end. Azure is in beta: same flow, but it hasn’t had a full end-to-end run on a live subscription yet. If anything looks off, email us and we’ll help.
No bastion yet? On Integrations, add a database (or open an existing one's Connection), choose In a private network, then AWS or Azure. Every server that uses this database gets the bastion. Enter the database's host:port as it's seen inside your network (the RDS endpoint, the Azure private DNS name or a private IP), pick a region on AWS, and we open your cloud console with a template filled in:
- AWS: click the VPC field and pick your database's VPC, then click the subnet field and pick a public subnet of it. Both start empty and the stack fails without them. Optionally pick the database's security group, and the template adds one inbound rule so the bastion can reach it. Leave the fields under "Filled in by Saywire" as they are. Click Create stack.
- Azure: pick a resource group, your database's virtual network and a subnet (not a delegated one). Click Create.
- About three minutes later the bastion reports back. We check its host key from our gateway and fill in the bastion and its trusted host key on the database integration. Servers that use it switch to the bastion right away.
| AWS | Azure | |
|---|---|---|
| Machine | t4g.nano, Amazon Linux 2023, encrypted disk, IMDSv2 only | Standard_B1ls, Ubuntu 24.04 LTS |
| Address | Elastic IP | Static public IP |
| Inbound | TCP 22 from our gateway's addresses only | TCP 22 from our gateway's addresses only |
| Outbound | The database port and HTTPS (updates, the report) | Azure's defaults |
| Cloud permissions | None: no IAM role, and the template creates no IAM resources | None: no managed identity |
| Admin login | None (no key pair) | None usable (Azure requires an admin key; we put a throwaway one in and keep no private half) |
| Cost | About $3–4 a month for the machine, plus your cloud's price for a public IPv4 | |
On the machine, the template runs the same setup as the one-command script (embedded in the template, not downloaded), lets only the tunnel user log in, and turns on automatic security updates with reboots.
How we know it's your bastion: the link carries a one-time code, valid for two hours. The bastion sends it back with its address and its host key fingerprints. We connect from our gateway and trust the host key only if it's one the bastion reported. The code works once. If a second machine ever reports with it, we refuse it and show a warning on the database.
Only use a link you created in your own dashboard. Never create a bastion from a link someone sends you: it would give their Saywire server a tunnel into your network.
Once it's connected
The database integration shows a bastion card with:
- Status: Connected or Paused, the bastion's address and its trusted host key, and where it came from (e.g. "AWS one-click, eu-central-1").
- A live check when you open it: we go through the bastion to your database and run one read-only query. Check again repeats it.
- Pause / Resume: pausing stops Saywire from using the database at once, on every server that uses it, with no redeploy. Tools on it answer that it's paused, calls aren't counted, and we don't connect to the bastion at all until you resume.
- Stop or start the machine: a link to it in your cloud console. Stopping saves the machine's cost while you don't need it; its public IP is still billed. While it's stopped, calls fail until you start it again (pause it too, for a clear message).
- Remove: Saywire connects to the database directly again, once a test of that direct connection passes (it applies to every server that uses it). The machine keeps running until you delete it.
To remove it completely, click Remove on the card, then delete the CloudFormation stack (AWS), or the bastion's VM, disk, network interface, public IP and network security group (Azure; all named saywire-bastion…).
4One-command setup
In the dashboard, open Integrations, add a database (or open an existing one's Connection), choose In a private network and Manual, fill in the bastion, save, and click Generate key pair. Enter the database's host:port as the bastion sees it and the dashboard gives you this command, with your key filled in. Run it on the bastion:
curl -fsSL https://saywire.dev/scripts/bastion.sh | sudo bash -s -- \
--key 'ssh-ed25519 AAAA… saywire-my-server' \
--allow 10.0.1.5:5432Prefer to read a script before running it as root? Same thing in three steps, with a dry run first:
curl -fsSLO https://saywire.dev/scripts/bastion.sh
less bastion.sh # read it first
sudo bash bastion.sh --key 'ssh-ed25519 AAAA… saywire-my-server' --allow 10.0.1.5:5432 --dry-run
sudo bash bastion.sh --key 'ssh-ed25519 AAAA… saywire-my-server' --allow 10.0.1.5:5432Options:
--key '<public key>' the public key from the dashboard (required)
--allow <host:port> a database the tunnel may reach, as the bastion sees it (required, repeatable)
--user <name> tunnel user (default saywire; must match "SSH user" in the dashboard)
--from <ip[,cidr]> only accept the key from these addresses
--dry-run print what would change, change nothing
--uninstall remove the user and the sshd drop-inIt's safe to run again: it replaces the key and the allowed targets. At the end it prints the bastion's host key fingerprints; keep them for section 7.
5What the script does
- Checks its inputs: one public key line,
host:porttargets, a plain user name. Anything else is refused, so a pasted value can't add options. - Creates the user
saywire(comment "Saywire SSH tunnel"), with no password andnologinas its shell. It won't touch an existing user it didn't create. - Writes
~saywire/.ssh/authorized_keyswith the key prefixed byrestrict,port-forwarding,permitopen="…"(andfrom="…"if you pass--from). - Adds
/etc/ssh/sshd_config.d/saywire.conf, which enforces the same for that user on the server side, then validates the config withsshd -t. If validation fails, it removes the file and changes nothing. - Reloads sshd (open sessions, including yours, stay connected) and confirms local forwarding is allowed for the user.
- Tests that each target is reachable from the bastion, and prints the host key fingerprints and what to enter in the dashboard.
The source is short and commented: saywire.dev/scripts/bastion.sh.
6Manual setup
The same steps by hand, for hosts where you'd rather not run a script, or where you manage SSH with Ansible, Chef or cloud-init.
1. A tunnel-only user
sudo useradd --create-home --shell /usr/sbin/nologin --comment "Saywire SSH tunnel" saywire
sudo usermod -p '*' saywire # no password, but not "locked" (sshd refuses locked accounts)
sudo install -d -m 700 -o saywire -g saywire /home/saywire/.ssh2. The key, restricted to the tunnel
One line in authorized_keys: the options, then the public key exactly as the dashboard shows it.
restrict,port-forwarding,permitopen="10.0.1.5:5432" ssh-ed25519 AAAA… saywire-my-server| Option | Effect |
|---|---|
restrict | Turns everything off: port, agent and X11 forwarding, TTY, ~/.ssh/rc. |
port-forwarding | Turns local port forwarding back on, and nothing else. |
permitopen="host:port" | The only destination the key may open. Repeat it for several databases. |
from="203.0.113.7" (optional) | Only accept the key from these addresses or CIDRs. |
sudo tee /home/saywire/.ssh/authorized_keys >/dev/null <<'EOF'
restrict,port-forwarding,permitopen="10.0.1.5:5432" ssh-ed25519 AAAA… saywire-my-server
EOF
sudo chown saywire:saywire /home/saywire/.ssh/authorized_keys
sudo chmod 600 /home/saywire/.ssh/authorized_keys3. Enforce it in sshd too (recommended)
Key options travel with the key line. A Match block makes the server enforce the same rules for the user whatever the key line says.
# /etc/ssh/sshd_config.d/saywire.conf
Match User saywire
AllowTcpForwarding local
PermitOpen 10.0.1.5:5432
PasswordAuthentication no
KbdInteractiveAuthentication no
PermitTTY no
X11Forwarding no
AllowAgentForwarding no
AllowStreamLocalForwarding no
PermitTunnel no
GatewayPorts no
ForceCommand /usr/sbin/nologin4. Validate, reload and check
grep -n 'Include /etc/ssh/sshd_config.d' /etc/ssh/sshd_config # must be there (default on Ubuntu 22.04+, Debian 12+)
sudo sshd -t && sudo systemctl reload ssh # 'sshd' on RHEL, Amazon Linux, Fedora
sudo sshd -T -C user=saywire,host=x,addr=127.0.0.1 | grep -E 'allowtcpforwarding|permitopen'
timeout 3 bash -c '</dev/tcp/10.0.1.5/5432' && echo reachable5. Note the host key fingerprints
for k in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf "$k"; done
# 256 SHA256:vC46uxVnik3lVYkx/3QtvlI0pp9ZPzfLVAlfAZfo6Ck root@bastion (ED25519)7In the dashboard
The connection string
Use the database host as the bastion sees it, and the same host:port you allowed in step 2. We never dial that host ourselves, so a private IP or an internal DNS name is fine.
postgres://mcp_readonly:PASSWORD@10.0.1.5:5432/app?sslmode=require # database in your VPC, TLS
postgres://mcp_readonly:PASSWORD@db.internal:5432/app?sslmode=require # private DNS name
postgres://mcp_readonly:PASSWORD@127.0.0.1:5432/app?sslmode=disable # Postgres on the bastion itselfKeep TLS (sslmode=require) when the database is on another machine: SSH protects the hop to the bastion, TLS protects the hop from the bastion to the database. sslmode=disable is only for Postgres running on the bastion itself.
A read-only role
Read tools already run in a read-only transaction with a 5 second statement timeout. A read-only role makes that true even for a mistake in a tool.
create role mcp_readonly login password 'choose-a-strong-password';
grant connect on database app to mcp_readonly;
grant usage on schema public to mcp_readonly;
grant select on all tables in schema public to mcp_readonly;
alter default privileges in schema public grant select on tables to mcp_readonly;The bastion fields
- Bastion host: its public IP or DNS name. Private addresses (
10.x,192.168.x,localhost) are refused. - Port: the SSH port, usually 22.
- SSH user:
saywire, or what you passed to--user.
Trust the host key
- Click Test. The first test only reads the bastion's host key: no login, and no database traffic.
- Compare the
SHA256:…fingerprint with the ones from step 5 (usually the ED25519 line). They must match exactly. - Click It matches, trust this key, then Test again. You should see "Connected and ran a read-only test query".
Don't skip the comparison. It's what proves you're talking to your bastion and not to someone in between. Nothing goes through the bastion, and servers that use the database can't be deployed, until a host key is trusted.
8Cloud recipes
AWS (RDS or Aurora in a private subnet)
- Launch a small EC2 instance (Amazon Linux or Ubuntu) in a public subnet of the same VPC, with a public or Elastic IP.
- Bastion security group: inbound TCP 22 from the internet (or our egress IP). Database security group: inbound TCP 5432 from the bastion's security group.
- Use the RDS endpoint (
mydb.xxxx.eu-west-1.rds.amazonaws.com) in--allowand in the connection string: it resolves to the private IP from inside the VPC. - Keep
sslmode=require. On Amazon Linux, reload withsystemctl reload sshd.
Google Cloud (Cloud SQL with private IP)
- Create an e2-micro VM in the VPC that has private services access to Cloud SQL, with an external IP.
- Firewall rule: allow TCP 22 to the VM. Use the instance's private IP in
--allowand in the connection string.
Azure (Flexible Server with private access)
- Create a small Linux VM in the same virtual network (or a peered one), with a public IP. NSG: allow TCP 22 inbound.
- Use the server's private DNS name (
myserver.postgres.database.azure.com, resolved through the private DNS zone) or its private IP.
Hetzner, DigitalOcean and other VPS providers
- Attach the bastion and the database server to the same private network. Use the database's private IP (e.g.
10.0.0.3). - If Postgres runs on the bastion itself, bind it to
127.0.0.1, allow127.0.0.1:5432and usesslmode=disable.
Kubernetes
- Use a small VM in the cluster's network as the bastion, and allow the database Service's cluster IP or internal load balancer address. A pod as a public SSH bastion is possible but harder to keep safe.
9Security model
| What | Where it lives |
|---|---|
| Private key | Generated on our API, encrypted at once with a key only the gateway can decrypt. Never shown, never logged, never sent to the dashboard. |
| Public key, host key fingerprint | In the database integration's settings (not secret). |
| Connection string (database password) | An encrypted secret, like every other secret. |
| Open tunnels | None between calls: one tunnel per tool call, closed when it ends. |
- Least privilege: the key can't run commands or get a shell, and can reach only the
permitopentargets. sshd enforces the same through the drop-in. - No first-contact leak: before you trust the host key, we only do the SSH key exchange. No login, and your database password isn't sent anywhere.
- Pinned host key: every call checks it. A changed key stops all calls until you trust the new one.
- Read-only by default: read tools run in a read-only transaction with a 5 second timeout, with parameterized single statements and capped rows.
- Your off switch: remove the key line, run
bastion.sh --uninstall, or stop sshd. Access ends at once, whatever we do. - Only from our gateway: the dashboard's command includes
--fromwith our gateway's addresses, so the key works from nowhere else. Allow only those on port 22 in your firewall too.
10Rotation and host keys
- Rotate our key: click Replace key pair, then run the new command on the bastion. The old key stops working as soon as the line is replaced.
- You rebuilt the bastion (or its host keys changed): calls fail with "host key changed". Check the new fingerprint on the bastion, then trust it in Connections.
- You moved the bastion to a new host or port: edit the connection. The trusted host key is cleared and you confirm the new one.
11Troubleshooting
| Message | Cause | Fix |
|---|---|---|
| Blocked: … is not a public address / resolves to a non-public address | The bastion host is private or local. | Use the bastion's public IP or DNS name. The database host goes in the connection string instead. |
| SSH bastion …: Timed out while waiting for handshake | Port 22 isn't reachable from the internet. | Open the security group / firewall for TCP 22, and check the port in the dashboard. |
| SSH bastion …: connect ECONNREFUSED | Nothing is listening on that port. | Check sshd runs (systemctl status ssh) and the port number. |
| SSH bastion …: All configured authentication methods failed | The key isn't installed, the user is wrong, or the account is locked. | Run the command again; check "SSH user" matches; sudo usermod -p '*' saywire. |
| The SSH bastion's host key changed (it is now SHA256:…) | The bastion was rebuilt, or something is in between. | Compare with ssh-keygen -lf on the bastion before trusting the new key. |
| The SSH bastion couldn't reach host:port ((SSH) Channel open failure: …) | The bastion refused or couldn't open the tunnel: the connection string's host:port isn't in permitopen / PermitOpen (often "open failed"), or the bastion can't reach the database ("Connection refused", "connect failed"). | Use exactly the allowed host:port, or run the command again with the right --allow. Check the route from the bastion: timeout 3 bash -c '</dev/tcp/HOST/5432', and the database's security group / firewall. |
| A TLS error, e.g. "Client network socket disconnected before secure TLS connection was established" | The connection string asks for TLS (the default) and Postgres doesn't offer it. | Turn TLS on in Postgres, or add ?sslmode=disable only if Postgres runs on the bastion itself. |
| password authentication failed for user … | Wrong database user or password, or pg_hba.conf doesn't allow the bastion. | Fix the connection string; allow the bastion's private IP in pg_hba.conf. |
| Test this connection once and trust the SSH bastion's host key first. | No host key trusted yet. | On Integrations: Test, compare, trust. |
Debug from the bastion's side: sudo journalctl -u ssh -f (or -u sshd) while you click Test.
12Remove access
curl -fsSL https://saywire.dev/scripts/bastion.sh | sudo bash -s -- --uninstallIt removes the saywire user (only if the script created it) and the sshd drop-in, then reloads sshd. By hand: delete the key line or the user, and /etc/ssh/sshd_config.d/saywire.conf. Then remove the bastion from the connection in the dashboard.
13Reference
The database integration's settings, as servers that use it see them once resolved (an alias and kind added):
{
"id": "db",
"kind": "postgres",
"urlSecret": "DB_DATABASE_URL", // secret: the connection string (host as the bastion sees it)
"ssh": {
"host": "bastion.example.com", // public IP or DNS name
"port": 22,
"user": "saywire",
"keySecret": "DB_SSH_KEY", // secret: the private key (generated, never shown)
"publicKey": "ssh-ed25519 AAAA… saywire-my-server",
"hostKey": "SHA256:…", // pinned after you trust it; required to deploy
"hostKeyType": "ssh-ed25519" // we only ask the bastion for this key type
}
}- Key type: ed25519, OpenSSH format, one pair per generation (comment
saywire-<server name>). - Host key check: SHA-256 fingerprint of the host key, as
ssh-keygen -lfprints it. - Timeouts: 10 s to connect and authenticate; 5 s per SQL statement.
- Questions or a setup we don't cover? Email support@saywire.dev.