beammeup

beammeup is a local CLI cockpit that SSHes into your server and sets up a browser-usable proxy exit.

live: beammeup.pw

what beammeup is

beammeup is install-only. there is no hosted control plane.

you run beammeup on your own machine, and it configures services on your server over SSH.

core concepts

ships

A ship is a local saved profile in:

• ~/.beammeup/ships/*.ship

A ship stores:

• target host/IP
• SSH user/port
• default protocol (http or socks5)
• HTTP mode (auto or sidecar)
• proxy port and firewall preference

A ship never stores SSH passwords.

hangars

A hangar is the remote beammeup-managed setup on that ship's server.

A hangar can include:

• SOCKS5 proxy (microsocks)
• HTTP proxy (managed squid or isolated sidecar)
• remote metadata at /etc/beammeup/hangar.json

wizard terms:

• destroy hangar = remove beammeup-managed remote config
• abandon ship = remove local .ship file only

install

curl -fsSL https://beammeup.pw/install.sh | bash

then run:

beammeup

interactive cockpit (default)

beammeup

beammeup opens a persistent menu loop:

• if you have no ships, onboarding creates one
• select ship -> ship cockpit
• launch/hangar/edit/abandon actions
• all screens support back navigation

password behavior:

• prompted once per ship per app session
• cached in memory only
• never written to disk

protocols and HTTP modes

SOCKS5

• lightweight and reliable
• best when your client supports SOCKS5 auth properly

HTTP

for browser-extension compatibility.

HTTP modes:

• auto (default): beammeup may manage /etc/squid/squid.conf when safe
• sidecar: isolated HTTP service that does not overwrite existing system squid config

HTTP conflict wizard

if beammeup detects an existing non-beammeup squid config, it does not overwrite it.

in TUI, you get a conflict wizard with options to:

• switch to SOCKS5 fallback
• create isolated HTTP sidecar
• cancel

non-interactive CLI

beammeup keeps scriptable flags for automation.

list ships

beammeup --list-ships

configure SOCKS5

beammeup \
  --host example.invalid \
  --ssh-user root \
  --protocol socks5 \
  --proxy-port 18080 \
  --action configure

configure HTTP sidecar (safe with existing squid)

beammeup \
  --host example.invalid \
  --ssh-user root \
  --protocol http \
  --http-mode sidecar \
  --proxy-port 18181 \
  --action configure

show inventory

beammeup --ship myship --show-inventory

destroy hangar

beammeup --ship myship --action destroy --yes

updater

beammeup --self-update

or auto-update before run:

beammeup --auto-update

supported target servers

currently focused on Debian/Ubuntu with:

• root SSH access
• apt-get
• systemd

security notes

SSH host keys

beammeup records and verifies SSH host keys in:

• ~/.beammeup/known_hosts

first connection is TOFU (trust-on-first-use). if a host key changes (rebuild / MITM), beammeup will refuse to connect.

override:

• --strict-host-key (do not auto-trust new keys)
• --insecure-ignore-host-key (unsafe, disables host key verification)
• --ssh-known-hosts <path> or BEAMMEUP_SSH_KNOWN_HOSTS (custom known_hosts path)

installer + self-update integrity

install.sh and beammeup --self-update verify downloaded release archives using the SHA256SUMS file published with each release.

release builds

build release archives:

scripts/build-release.sh

artifacts:

• dist/beammeup_darwin_arm64.tar.gz
• dist/beammeup_darwin_amd64.tar.gz
• dist/beammeup_linux_amd64.tar.gz
• dist/beammeup_linux_arm64.tar.gz
• dist/version.txt

license

mit