Skip to content

Remote Access via SSH

The Connector listens on the host on port 3000 (dashboard) and 8080 (API). In many deployments those ports aren’t opened on the network — the host sits behind a firewall or security group that only admits SSH. Anyone who can SSH to the host can still use the dashboard and call the API by forwarding the ports to their own machine. Nothing needs to change on the server.

If SSH access itself isn’t available either — for example, an SSH proxy that only issues credentials for a shell, not a raw tunnel — putting a reverse proxy in front on a network-approved port is the other option; see Bundle Install Reference → Changing the API and dashboard ports for moving the Connector off 3000/8080 first if the proxy needs to reach it across a network boundary where those ports aren’t approved.

How the pieces fit: the dashboard is server-rendered and talks to the API itself, from inside its container, over the host. Your browser only ever talks to the dashboard. That means forwarding port 3000 alone is enough to use the dashboard fully; forwarding 8080 as well lets you call the API directly with curl, scripts, or any HTTP client on your workstation.

From your workstation (macOS, Linux, or Windows with the built-in OpenSSH client in PowerShell):

ssh -N \
-L 3000:127.0.0.1:3000 \
-L 8080:127.0.0.1:8080 \
user@connector-host

-N opens the tunnel without a remote shell; leave the command running. While it’s up:

On your workstation Reaches on the host
http://localhost:3000 the dashboard — open this in your browser and sign in
http://localhost:8080/v1/… the Connector API

Quick check from a second terminal:

curl -fsS http://localhost:8080/v1/healthcheck && echo " API OK"
curl -fsS http://localhost:3000/api/health && echo " Dashboard OK"

Press Ctrl-C in the ssh terminal to close the tunnel.

If 3000 or 8080 is already in use on your workstation, pick different local ports — only the number before the first colon changes:

ssh -N -L 13000:127.0.0.1:3000 -L 18080:127.0.0.1:8080 user@connector-host
# then browse to http://localhost:13000

The dashboard works on any local port because it never asks the browser to contact the API directly.

If the Connector host is only reachable from another machine you can SSH to:

ssh -N -J user@bastion -L 3000:127.0.0.1:3000 -L 8080:127.0.0.1:8080 user@connector-host

Add an entry to ~/.ssh/config so the forwards are set up every time you connect, and the session survives idle periods:

Host a10e
HostName connector-host.example.internal
User operator
# ProxyJump user@bastion # uncomment if you go through a jump host
LocalForward 3000 127.0.0.1:3000
LocalForward 8080 127.0.0.1:8080
ServerAliveInterval 30
ServerAliveCountMax 3
ExitOnForwardFailure yes

Then either of these works:

ssh a10e # interactive shell on the host, with the forwards active for as long as you're logged in
ssh -N a10e # forwards only, no shell
ssh -fN a10e # forwards only, in the background; stop it with: pkill -f 'ssh -fN a10e'

ExitOnForwardFailure yes makes ssh fail loudly if a local port is taken, instead of silently connecting without the forward.

The bundled database is bound to 127.0.0.1:5433 on the host and is never reachable from the network. To inspect it with psql or a desktop client, add a third forward:

ssh -N -L 3000:127.0.0.1:3000 -L 8080:127.0.0.1:8080 -L 5433:127.0.0.1:5433 user@connector-host
# in another terminal, password from /opt/a10e/shared/env-manager/postgres-password on the host
psql "host=localhost port=5433 user=a10e dbname=a10e_db"

Use this for read-only inspection. Do not change data directly while the Connector is running.

For a shared operator workstation or a monitoring box that should always have the ports available, run the tunnel under a supervisor so it reconnects after a network drop. autossh is the usual choice:

autossh -M 0 -fN a10e # uses the ~/.ssh/config profile above

Or as a user-level systemd service on Linux:

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/a10e-tunnel.service <<'EOF2'
[Unit]
Description=SSH tunnel to the Alien Giraffe Connector
After=network-online.target
[Service]
ExecStart=/usr/bin/ssh -N a10e
Restart=always
RestartSec=5
[Install]
WantedBy=default.target
EOF2
systemctl --user daemon-reload
systemctl --user enable --now a10e-tunnel.service
  • The forwarded ports listen on 127.0.0.1 of your machine only. Other people on your network can’t use your tunnel unless you deliberately bind it wider (-L 0.0.0.0:3000:…), which you should avoid.
  • Sign-in, sessions, and everything else in the dashboard work exactly as they would on the host. No CORS_ALLOWED_ORIGINS change is needed, because the browser talks only to the dashboard.
  • If the dashboard loads but shows errors from the API, check the API on the host itself first (curl http://127.0.0.1:8080/v1/healthcheck — see Operations: Health Checks & Backups); a tunnel can’t fix a service that’s down.
  • SSH access to the host is the security boundary here. Anyone who can open the tunnel has the same access to the Connector as someone sitting at the host, so manage SSH keys accordingly.