SSH cannot connect

StoreFrame environments run SSH on a non-default port. Most connection failures have a straightforward cause. Work through the checklist below before assuming something is wrong with the environment.

Wrong port

Symptom: ssh: connect to host ... port 22: Connection refused or the connection hangs with no banner.

Cause: SSH on customer environments runs on port 2409, not the default 22. Most SSH clients default to 22 if no port is specified.

Fix: Always specify the port explicitly:

ssh app@{subdomain}.storeframe.store -p2409

The correct connection string is also shown on the environment's Settings → SSH tab in the Hub. Copy it from there to avoid typos.

Key not yet propagated

Symptom: Permission denied (publickey) immediately after adding a new SSH key in the Hub.

Cause: When you add a key on an environment's SSH Keys panel, the Hub runs a background job to install it on that environment. This takes up to 60 seconds. Adding a key only on the organization's SSH Keys page does not install it anywhere; see the next section.

Fix: Wait 60 seconds after saving the key, then retry. If it still fails after two minutes, check that the key was saved correctly — open the SSH key management panel, confirm the key fingerprint matches your local key (ssh-keygen -l -f ~/.ssh/your_key.pub), and try adding it again.

Wrong user

Symptom: Permission denied when connecting as root or as your local system username.

Cause: The application user on StoreFrame environments is app, not root or any other username. SSH is configured to reject root login.

Fix: Connect as app:

ssh app@{subdomain}.storeframe.store -p2409

To run commands that require elevated privileges, use sudo after connecting:

sudo systemctl status nginx
sudo docker ps

Org SSH key vs per-environment key

Symptom: SSH works on some environments but fails on a specific one, even though you recently added a key.

Cause: StoreFrame has two levels of SSH key registration:

• Organization keys (Settings → Organization → SSH Keys): a saved list of your team's keys. You pick one of them when you create an environment, and that key is installed at provision time. Keys added here later are not pushed to running environments.
• Per-environment keys (Environment → Settings → SSH Keys): installed on that specific environment.

If you added a key at the per-environment level for environment A, it is not available on environment B, and vice versa.

Fix: Open the environment's Settings → SSH Keys panel and add the key there. Repeat for each running environment you need access to. Saving the key at the organization level first lets you pick it quickly on each environment and when creating new ones.

Firewall block (CrowdSec)

Symptom: The connection is refused or dropped after the TCP handshake — no SSH banner, no authentication prompt. This happens from one specific IP but not others.

Cause: Each environment runs CrowdSec, an automated firewall that blocks IPs exhibiting suspicious behavior (repeated failed logins, port scanning, known threat intelligence). If your IP was previously used in a pattern that triggered a CrowdSec decision, SSH will appear to refuse connections.

Diagnosis: Check whether your IP has an active block by connecting from a different network (mobile hotspot, VPN) and seeing if SSH succeeds there.

Fix:

• If SSH succeeds from another IP: file a support ticket with your IP address and the environment ID. Support can remove the CrowdSec decision.
• If SSH fails from all IPs: the issue is not a firewall block — check the other sections on this page.

Still stuck?

If none of the above resolves it, file a support ticket with:

• The environment ID
• Your SSH public key fingerprint (ssh-keygen -l -f ~/.ssh/your_key.pub)
• The exact error output from ssh -v app@{subdomain}.storeframe.store -p2409
• The IP you are connecting from