Install & Setup — Beam Viewer

After purchasing a key on your dashboard, install the Beam viewer on whatever PC you'll use to watch sessions. Pick your OS below.

Windows

macOS

Linux

Step 1 — Open PowerShell

Click Start → type PowerShell → press Enter.

Step 2 — Install Python (skip if you already have Python 3.9+)

Check first — run:

python --version

If it says Python 3.9 or newer, skip to Step 3. Otherwise:

winget install -e --id Python.Python.3.12 --accept-package-agreements --accept-source-agreements

Python 3.12 is recommended. Very new versions (3.14+) may lack pygame wheels and fail to install.

Close PowerShell and open a new window so Python is on your PATH.

Step 3 — Install Beam

If on normal internet (home / hostel Wi-Fi):

iex (irm https://beamsolutions.vercel.app/install.ps1)

If on a lab / office PC behind a college proxy — paste this whole block, replacing PROXY_HOST:PORT, USERNAME, and PASSWORD with the values your IT / network administrator gave you:

$wp=New-Object System.Net.WebProxy('http://PROXY_HOST:PORT')
$wp.Credentials=New-Object System.Net.NetworkCredential('USERNAME','PASSWORD')
[System.Net.WebRequest]::DefaultWebProxy=$wp
$env:HTTP_PROXY='http://USERNAME:PASSWORD@PROXY_HOST:PORT'
$env:HTTPS_PROXY=$env:HTTP_PROXY
iex (irm https://beamsolutions.vercel.app/install.ps1)

Common examples: proxy address 172.16.x.x:3128 or proxy.example.edu:8080. If your proxy doesn't need a username/password, use the version without credentials — just $env:HTTP_PROXY='http://PROXY_HOST:PORT'.

Step 4 — Close PowerShell, open a new one

PATH changes only take effect in new windows. Otherwise beam won't be recognized.

Step 5 — Register your key

beam key <your key>

Paste the key you bought from your dashboard. Example:

beam key bm_XyZ123AbCdEf456GhI789JkL0mNoPqRsTuVwXyZ

You should see: Beam key saved to .... This is a one-time step per PC.

Step 6 — Use it

To watch someone's session:

beam view <session code>

To share your own screen (become a host):

beam host

Other commands:

beam status      # is a session running?
beam stop        # stop sharing
beam key --show  # is a key saved?
beam             # help menu

Step 1 — Open Terminal

Cmd + Space → type Terminal → Enter.

Step 2 — Install Python 3.12 (skip if you already have Python 3.9–3.13)

Check first — run:

python3 --version

If it says Python 3.9–3.13, skip to Step 3.

If Python is missing — install Homebrew first, then:

brew install python@3.12

If your Python is 3.14+, you'll hit a pygame build error. Install 3.12 as above, then use python3.12 explicitly, or set it as default in your PATH.

Note: Xcode Command Line Tools alone (xcode-select --install) will give you an older Python that's usually fine, but Homebrew's is preferable — it's newer and can be updated cleanly.

Step 3 — Install Beam

If on normal internet:

curl -fsSL https://beamsolutions.vercel.app/install.sh | sh

If on a lab Mac behind a college proxy — replace PROXY_HOST:PORT, USERNAME, and PASSWORD with the values your IT / network administrator gave you:

export HTTPS_PROXY='http://USERNAME:PASSWORD@PROXY_HOST:PORT'
export HTTP_PROXY="$HTTPS_PROXY"
curl -fsSL https://beamsolutions.vercel.app/install.sh | sh

If your proxy doesn't need auth, drop the USERNAME:PASSWORD@ part — just http://PROXY_HOST:PORT.

Step 4 — Reload your terminal

source ~/.zshrc

Or close Terminal and open a new window.

Step 5 — Register your key

beam key <your key>

Example:

beam key bm_XyZ123AbCdEf456GhI789JkL0mNoPqRsTuVwXyZ

Step 6 — Use it

To watch someone's session:

beam view <session code>

To share your own screen:

beam host

macOS permissions: The first time you run beam host, macOS will ask for Screen Recording permission. Approve it in System Settings → Privacy & Security → Screen Recording → toggle on Terminal, then re-run beam host.

Other commands:

beam status      # is a session running?
beam stop        # stop sharing
beam key --show  # is a key saved?
beam             # help menu

Step 1 — Open a terminal

Step 2 — Install Python 3.9+ (skip if already installed)

python3 --version

If it says Python 3.9 or newer, skip. Otherwise:

Ubuntu / Debian:

sudo apt update
sudo apt install python3 python3-pip python3-venv

Fedora / RHEL:

sudo dnf install python3 python3-pip

Arch:

sudo pacman -S python python-pip

Step 3 — Install Beam

curl -fsSL https://beamsolutions.vercel.app/install.sh | sh

Behind a proxy — replace the placeholders with your admin-provided values:

export HTTPS_PROXY='http://USERNAME:PASSWORD@PROXY_HOST:PORT'
export HTTP_PROXY="$HTTPS_PROXY"
curl -fsSL https://beamsolutions.vercel.app/install.sh | sh

Step 4 — Reload your terminal

source ~/.bashrc

Or, if you use zsh: source ~/.zshrc

Step 5 — Register your key

beam key <your key>

Step 6 — Use it

beam view <session code>
beam host
beam status
beam stop
beam             # help menu

Wayland users: Some Wayland compositors don't allow full-screen capture from outside. If beam host shows a black screen, log out and log in with Xorg instead, or run under XWayland.

Troubleshooting

"beam: command not found" (Mac / Linux) — or "'beam' is not recognized" (Windows)

You need to open a NEW terminal window after installing, so the PATH change takes effect. On Mac/Linux you can also run source ~/.zshrc or source ~/.bashrc in the same terminal.

pygame won't install / "SDL.h file not found" / "Failed building wheel for pygame"

Your Python version is too new (3.14+) and pygame doesn't have prebuilt wheels for it yet. Install Python 3.12 (recommended) instead:

Windows: winget install -e --id Python.Python.3.12
macOS: brew install python@3.12
Linux: use your package manager — most distros ship 3.10-3.12 by default

Then re-run the installer.

"No Beam key found" when running beam view

beam key <your key>

"Key rejected: invalid_key" or "This key has expired"

Your key is expired (they last 7 days) or was revoked. Buy a new key on your dashboard.

Connection times out / "Reconnecting in Ns..."

Your PC can't reach the Beam relay at beamsolutions.duckdns.org:8767. Check:

Are you connected to the internet?
Are you behind a proxy or firewall that blocks port 8767? On a lab PC, run beam proxy http://USERNAME:PASSWORD@PROXY_HOST:PORT before beam view (fill in the values from your IT admin).
Is the session code correct? (6 digits, shown by the host)

Screen is black on Mac when hosting

macOS blocks screen capture until you grant permission. Go to System Settings → Privacy & Security → Screen Recording → toggle on Terminal (or whichever terminal app you used), then re-run beam host.

Uninstall Beam

beam uninstall

Removes all files and the PATH entry. Uninstall is reversible — just re-run the installer.

Still stuck? See our contact page — include your OS, the exact error message, and the output of beam --version if it runs.