Web access

Web access puts the same Beav workspace in a browser. You can turn it on in the desktop app for your own machine, a phone, or a trusted LAN device; or install Beav on a Linux server that stays online and open it from a browser.

Only web access mode is publicly available today. The API and channel options in Settings are not offered as public integration paths yet, so you do not need to configure them.

Choose a deployment

Scenario	Recommended approach	Requirements
Temporary use on your own computer, or a phone reaching Beav on the same LAN	Desktop web access mode	This machine and a trusted LAN
Beav always on, reachable from another computer	One-line Linux server install	Debian / Ubuntu x86_64 with systemd
Access from the internet on your own domain	Linux server + HTTPS reverse proxy	A domain, a TLS certificate, and control of the server firewall

Turn on web access in the desktop app

1. Keep the Beav desktop app running and open Settings → Remote access.
2. Switch on web access mode and wait until the status reads “Web access is on”.
3. Copy the local address or the LAN address shown on the page.
4. Open that address in the browser on the device you want to use.

The first time you enable it, the page shows an admin account and a login password. Save the password immediately, and do not send it into untrusted chats, documents, or groups. Later you can view, copy, or change the credentials on the same page; changing the account or password signs out the open web sessions.

The admin account must be 3–64 non-whitespace characters; the password must be 12–256 characters and must not start or end with whitespace.

Sign in with a phone QR code

Once it is on, the desktop app shows a login QR code. Scan it with a phone on the same trusted network to open a browser session:

1. Confirm the status reads “Web access is on” and a LAN address is shown.
2. Scan the QR code with your phone camera or browser, or copy the scan link and send it to your own device.
3. Open the link before the code expires. Each code is valid for 5 minutes and can be used once.

The QR code only brings you into the current web session; it is not a substitute for keeping the admin password safe. To authorize again, click “Regenerate” in the desktop app.

Local and LAN addresses

• The local address is only for the computer where Beav is installed.
• The LAN address is for phones, tablets, and computers on the same trusted network.
• Beav selects one private physical LAN adapter; it never listens on every virtual adapter, tunnel, or container interface for web access.
• If Windows or your system firewall asks whether to allow access, allow only “Private networks” or networks you have confirmed as trusted; never open access for public networks.

If the LAN address does not respond, first check that both devices are on the same network, then click “Refresh status” in the desktop app. If no LAN address is shown at all, check that the computer is connected to Wi-Fi or Ethernet and that the system firewall allows inbound connections on the trusted network.

Do not map the LAN port shown in the desktop app directly to the public internet. For internet access, use the Linux server and HTTPS reverse proxy path below.

One-line install on a Linux server

The official one-line install currently supports Debian or Ubuntu x86_64 servers that use systemd, allow sudo, and have HTTPS network access. It installs Beav, Xvfb, FFmpeg, and a systemd service; you do not need to download a DEB by hand or configure a desktop environment.

Sign in to the server over SSH and run this single command:

curl -fsSL https://www.getbeav.com/install.sh | bash

The installer requests sudo and then works through these steps:

1. Fetch the currently published Linux service package.
2. Verify the package SHA-256 and file size; a failed check stops the install.
3. Install the matching versions of Beav, Xvfb, and FFmpeg dependencies.
4. Create the permission-restricted beav system account and enable beav-web.service.
5. Wait until http://127.0.0.1:31938/health/ready is ready, then print the access address.

When the first install finishes, the terminal shows the admin account admin and a generated initial password. That initial password is displayed only once, during the first install, so store it in a password manager. Later updates keep the existing password. If it is lost, do not reinstall — run sudo beavctl reset-admin to set a new one.

First sign-in and connectivity check

On the server, run:

beavctl url
beavctl status

Open Beav in a browser at the address printed by beavctl url and sign in with the admin account and password. Check server availability with:

curl --fail http://127.0.0.1:31938/healthz
curl --fail http://127.0.0.1:31938/health/ready

/healthz reports that the service is still running; /health/ready also confirms that the workspace and web assets are usable. The installer itself uses the latter as its completion condition.

Routine operations

Goal	Command
Check service status	beavctl status
Show local and LAN access addresses	beavctl url
Show recent logs	beavctl logs
Follow logs continuously	beavctl logs --follow
Start, stop, or restart the service	sudo beavctl start / stop / restart
Reset the admin password	sudo beavctl reset-admin
Update to the current release	beavctl update
Uninstall the service and keep the data	sudo beavctl uninstall

beavctl update reruns the official installer and keeps existing data and the admin password. When access fails or an update breaks, run beavctl status and beavctl logs first instead of repeating the install several times.

Run the command below only when you clearly mean to delete the service, the workspace, and the server keys together:

sudo beavctl uninstall --purge

This deletes /etc/beav and /var/lib/beav and cannot be undone.

Data and backups

Persistent content on the server lives at these paths:

Content	Path
Beav data, encrypted credentials, workspaces, and media	/var/lib/beav
Service master key	/etc/beav/server-master.key
Web admin password	/etc/beav/webui-admin-password

When you back up, save /var/lib/beav together with /etc/beav/server-master.key in an encrypted backup behind access controls. If the master key is lost, stored third-party credentials cannot be recovered and must be reconnected. The admin password file is equally sensitive: never copy it into a repository, an image, or an ordinary cloud drive.

Reach it from the internet with a domain and HTTPS

A public deployment needs at least three layers of boundary: the reverse proxy owns the domain and TLS, Beav's 31938 port only accepts the reverse proxy, and browsers only connect to your HTTPS domain. Never expose 31938 directly to the internet.

1. Restrict the Beav port first

In your cloud security group and server firewall, block direct internet access to 31938. If the reverse proxy runs on the same server, the port should only accept localhost or that server's trusted private address.

2. Forward HTTPS through a controlled reverse proxy

With Nginx as an example, replace <beav-private-ip>, beav.example.com, and the certificate paths with your own values:

server {
    listen 443 ssl http2;
    server_name beav.example.com;

    ssl_certificate     /etc/letsencrypt/live/beav.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/beav.example.com/privkey.pem;

    location / {
        proxy_pass http://<beav-private-ip>:31938;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

Keep X-Forwarded-Proto: https, turn proxy buffering off, and use a long read timeout — only then do the web login cookie and the realtime event connections work correctly over HTTPS.

3. Trust only your own proxy

After confirming that 31938 can no longer be reached from the public internet, add a systemd drop-in for the Beav service:

sudo systemctl edit beav-web

In the editor that opens, add:

[Service]
Environment=REDBOX_WEBUI_TRUST_PROXY=1

Then apply the configuration:

sudo systemctl daemon-reload
sudo systemctl restart beav-web

Finally, sign in only through https://beav.example.com and verify from another network that 31938 cannot be reached directly. With REDBOX_WEBUI_TRUST_PROXY enabled, Beav trusts the HTTPS marker passed by the reverse proxy — so never enable it while arbitrary public clients can connect to 31938.

Need help?

If the desktop app will not open or LAN devices cannot connect, work through the network checks in this article first; for server problems, collect the output of beavctl status and beavctl logs. Other install and desktop issues: Troubleshooting.