Getting started

Connecting ClickHouse

OptiHouse reaches your cluster in one of five modes. Pick the one that matches your security posture — if you cannot decide, the SSH bastion covers roughly 80% of corporate VPN setups today.

Pick a mode

Mode	When to use	Status
Direct	OptiHouse runs in the same VPC as ClickHouse	Available
SSH bastion	Cluster sits behind a jump host	Available
WireGuard / Tailscale	Multi-cluster or multi-region private networks	Planned
Cloudflare Tunnel	Zero-trust policy, no inbound ports allowed	Planned
Pull-based agent	Air-gapped or strict egress-only environments	Target architecture

The read-only user

Whichever mode you choose, the ClickHouse credentials should always be read-only. This is enough for everything OptiHouse does:

sql

CREATE USER dataeff IDENTIFIED WITH plaintext_password BY '<strong-random>';
GRANT SELECT ON system.* TO dataeff;
ALTER USER dataeff SETTINGS readonly = 1;

Never share write-capable credentials

Do not give any tool — including OptiHouse — a user that can write. Always create a dedicated readonly = 1 user scoped to system.*.

Direct

The simplest mode. OptiHouse runs as a container inside the same private network as ClickHouse — no tunnelling, no extra moving parts. In the connection form fill in host, port, username and password, and leave the SSH section collapsed. Lowest latency, lowest complexity.

SSH bastion

OptiHouse opens a short-lived SSH tunnel through a jump host on every scan, then talks to ClickHouse over the forwarded port. The bastion already exists in most corporate networks, so security teams do not have to greenlight new infrastructure.

1
Create a forwarding-only user on the bastion
sudo useradd -m -s /usr/sbin/nologin dataeff — nologin is fine, the account only forwards a port.
2
Generate a dedicated key pair
ssh-keygen -t ed25519 -f ./dataeff_bastion. Never reuse a personal key.
3
Allowlist the key, restricted to forwarding
Add the public key to ~dataeff/.ssh/authorized_keys with restrict,permitopen="clickhouse.internal:9000" so it can do nothing else.
4
Paste the private key into the form
Expand Connect via SSH bastion, fill bastion host/port/user and paste the PEM-encoded private key, then click Test.

How the key is stored

The private key lives server-side in an encrypted column and is never returned by the API — GET /connections only echoes host/port/user plus a bastion_configured boolean. Tunnels are opened per-scan and torn down immediately.

Planned modes

WireGuard / Tailscale runs a small sidecar that joins your private network as a peer. Cloudflare Tunnel suits a strict zero-trust mandate — you run cloudflared and no inbound ports are opened anywhere. The pull-based agent is the long-term target: a collector container runs inside your VPC and POSTs JSON snapshots out over HTTPS, so there are no inbound ports and no credentials on our side at all.

Troubleshooting

Symptom	Fix
`channel 0: open failed: administratively prohibited`	The `authorized_keys` line restricts the destination — add `permitopen="clickhouse.internal:9000"`.
`Could not parse SSH private key`	RSA, Ed25519, ECDSA and DSS keys in PEM format are supported. Convert a PuTTY `.ppk` with `puttygen key.ppk -O private-openssh -o key.pem`.
Tunnel works once, then hangs	The bastion's `MaxSessions` is likely set to 1 — raise it in `/etc/ssh/sshd_config`.