← All docs

Deploy the shaft proxy

For strict data-residency or when the database must never be exposed outside your network, deploy the shaft proxy next to the database (in the same VPC). The agent connects through the proxy over SOCKS5, so the database only ever accepts connections from inside your network.

agent ──SOCKS5──▶ shaft proxy (your VPC) ──▶ database (private)

This is the transport for the split-runtime model: the agent can run anywhere the proxy is reachable, while the database stays private to your VPC.

1. Generate the proxy's TLS certificate

The agent talks to the proxy over TLS (SOCKS5-over-TLS), so the SOCKS handshake, credentials, and tunneled traffic are all encrypted. Create a server certificate for the proxy and bundle it into a PKCS#12 keystore:

openssl req -x509 -newkey rsa:2048 -nodes -days 365 \
  -keyout proxy.key -out proxy.crt -subj "/CN=shaft-proxy"
openssl pkcs12 -export -in proxy.crt -inkey proxy.key \
  -out proxy.p12 -passout pass:CHANGEME -name shaft-proxy

Keep proxy.crt — you'll pin it in the portal so the agent verifies the proxy.

The proxy image is published to europe-west3-docker.pkg.dev/coreshaft-prod/shaft/shaft-proxy. To pull it, authenticate Docker once (gcloud auth configure-docker europe-west3-docker.pkg.dev) with an identity that has the Artifact Registry Reader role on the repo.

2. Run the proxy near the database

Run the proxy on a small host in the same network as the database. It only needs outbound reach to the database, and inbound TLS from the agent.

docker run -d --name shaft-proxy \
  --restart unless-stopped \
  -p 1080:1080 \
  -v "$PWD/proxy.p12:/etc/shaft/proxy.p12:ro" \
  -e PROXY_USERNAME=agent \
  -e PROXY_PASSWORD='a-strong-password' \
  europe-west3-docker.pkg.dev/coreshaft-prod/shaft/shaft-proxy:latest \
  --listen 0.0.0.0:1080 \
  --allow-cidr AGENT_CIDR \
  --allow-target DB_HOST:5432 \
  --tls-keystore /etc/shaft/proxy.p12 \
  --tls-keystore-password CHANGEME

Expose port 1080 only to the agent (security group / firewall rule scoped to the agent's address).

2. Confirm reachability

From the agent host:

nc -vz PROXY_HOST 1080

3. Configure the connector in the portal

On the connector's Configure page, choose Connection → Proxy agent and set:

| Field | Value | |-------|-------| | Proxy host | the proxy's address reachable by the agent | | Proxy port | 1080 | | Proxy username | agent (matches --username) | | Proxy password | the SOCKS5 password (encrypted at rest) | | Proxy TLS certificate | paste the contents of proxy.crt, or a path to it on the agent host |

Pinning proxy.crt means the agent trusts only your proxy (leave it blank only if the proxy uses a publicly-trusted certificate). Keep the connector's JDBC URL pointing at the database as seen from the proxy (e.g. jdbc:postgresql://db.internal:5432/appdb). The agent dials that address through the proxy over TLS — the database needs no public route.

Combining with authentication

The proxy carries the transport only; you still choose an authentication method (password, client certificate, or IAM) independently. For end-to-end encryption to the database, pair the proxy with client-certificate TLS.

More guides