Docs / Hosting OwnBase

Windows and LAN

Build an installer with pnpm build:win. The output is apps/desktop/release/OwnBase-Setup-0.2.0.exe. Local builds are unsigned unless you supply a signing certificate; Windows may show SmartScreen. A published release carries the installer, the server bundle and SHA256SUMS; check a download with Get-FileHash -Algorithm SHA256 <file> against that list. Its notes name the commit it was built and tested from, which Diagnostics in the app and /api/server-info on a server also report. Release installers are not code-signed yet.

Every change to the app merged to main is built, tested and published as the next alpha (v0.2.0-alpha.4 after v0.2.0-alpha.3) by the Release workflow. It is published as a normal release, not a pre-release, and marked Latest on GitHub, so GitHub, the download buttons on the website and the desktop app's updates all name the same newest version. A run by hand, or from a pushed version tag, still leaves a draft to look over first, marked as a pre-release when its tag has a hyphen. Publishing that draft creates its tag, and a tag whose release is already out builds nothing, so no second draft appears.

Releases were betas (v0.1.0-beta.1 to v0.1.0-beta.39) until November 2026, when they became alphas of 0.2.0 so the versions keep rising. A Windows copy of a beta does not update to an alpha by itself, because electron-updater never moves a beta down to an alpha; install the newest alpha from the website once.

Install, choose Host a workspace on this computer, name it, and create the owner account. Allow incoming TCP on the displayed port through the host firewall. Other desktop users can discover the workspace on the same LAN or connect using 192.168.1.42:8543. Browsers can use the same address for chat.

The host computer must stay running and awake. For temporary internet sharing, use Open to all and Cloudflare Tunnel as described below. A VPN such as Tailscale, a VPS, or a public IP with port forwarding are alternatives. An IP address alone does not bypass NAT, CGNAT, or firewalls. LAN discovery does not cross routers.

Each hosted workspace has its own folder under the app's user-data folder (%APPDATA%\OwnBase on Windows, ~/Library/Application Support/OwnBase on macOS, ~/.config/OwnBase on Linux), in hosted/w-<random id>/. The folder is fixed when the workspace is created and does not follow its name, so two workspaces may share a name and renaming one moves nothing; folders made by earlier versions, named after the workspace, are adopted as they are. Manage hosting shows the running workspace's data folder. Advanced deployments can set OWNBASE_USER_DATA_DIR to choose the desktop profile location.

Closing the window, and quitting#

While a workspace is hosted, or starting or stopping, closing OwnBase's window does not stop it. The window goes to the system tray, whose icon offers Open OwnBase, what is hosted and on which port, Stop hosting and Stop hosting and quit. Neither asks first, since each already says that hosting stops. Launching OwnBase again, or opening an ownbase:// link, also brings the window back. On a desktop with no tray, closing minimizes the window instead. With nothing hosted, closing the last window quits on Windows and Linux; macOS keeps the app in the dock as usual.

A bar under a workspace you are hosting says so and offers Manage hosting: the workspace's name, the addresses teammates connect to, its port and its data folder. Its Stop hosting stops at once, as the tray's does, and disconnects everyone connected. Quitting while hosting other than from the tray asks first. Messages, files and accounts stay on disk. Quitting waits for a start already under way, and for the server to finish what it is doing. If stopping fails, OwnBase stays open and says so. If it fails while quitting, you can keep OwnBase open or quit anyway; quitting anyway ends at once and may lose changes still being written, but never deletes workspace data.

If the last-used hosting settings cannot be saved, the workspace keeps running and Manage hosting shows a warning.

Reopening, renaming and starting with the computer#

Every workspace hosted on this computer is listed under Hosted on this computer in the host dialog, where each can be started again with its messages, renamed, given a different port or backed up. The join screen offers the most recently hosted one back with one click. Use the list to reopen a workspace: creating a new one under the same name starts a separate, empty workspace, and the dialog says so. The workspace's owner and administrators can also rename it from Workspace settings while it runs, and the list takes the new name.

While a workspace is running, When this computer starts offers two choices: Start hosting it when OwnBase opens, and, where the system supports it, Open OwnBase when you sign in to this computer. With both on, the workspace is back for teammates once the computer restarts and someone signs in, and OwnBase waits in the tray. Only one workspace can be chosen. Starting this way hosts on the network; a temporary Open to all link is never reopened by itself, since its address changes every time. When a stable address is set up (see below), a third choice appears: Also reopen it when the workspace starts with OwnBase. It is kept for that workspace and that address only. After starting, OwnBase opens the address the usual way, checking that it reaches this workspace, and new accounts need an invite. If the address has changed, cannot be reached or fails the check, the workspace keeps running on the network and the reason is shown the next time the window is opened. A restored workspace still held from a backup is never started this way. If the chosen workspace cannot start, the reason is shown the next time the window is opened.

A port you chose for a workspace, when creating it or with Change port, is kept: if another program holds it, the workspace does not start and says so, rather than moving to another port. A workspace left on the usual port moves to a free one and Manage hosting says where.

While nothing is running, the same section appears above the list whenever a workspace is chosen to start, a start failed, or OwnBase opens at sign-in, so a workspace that cannot start can be taken off starting with OwnBase, and OwnBase off sign-in, without starting it first or removing it from the list.

Current limit: opening at sign-in has not been tried on an installed macOS system. If macOS holds the registration for approval, the dialog says to allow OwnBase under Login Items in System Settings.

Backing up from the desktop#

Back up now copies a hosted workspace into a new folder you choose, and Automatic backups does the same every day or week into one folder, keeping the newest few. A copy is kept only if it holds the same workspace as the one listed, retention never removes the copy it has just made, and an older copy counts toward the number kept only after it passes the same check as verify-backup. A failed automatic copy keeps its error across restarts and waits one hour before retrying; repeated failures double that delay up to 24 hours. Back up now can make an immediate copy, and choosing an automatic backup folder explicitly resets the delay. Try the backup again in the tray or hosting window also retries immediately. Failed captures never trigger removal of older verified backups.

Restore from a backup… checks a backup, then restores it as a hosted workspace without starting it; it will not restore over a workspace already hosted here. A restored workspace is held until you put it back in use, and the hold survives restarting OwnBase. While held, it is listed as "Restored, not in use yet", is taken off starting with OwnBase, and Look inside starts it on this computer only: nothing it had queued is sent, no app is called, it is not announced on the network and it cannot be opened to all. After restoring, the dialog says what the backup would bring back: sign-ins it still accepts, scheduled messages waiting, app events not yet delivered and the apps it calls. Put back in use… asks first, then starts it as the workspace itself, which clears the hold for good.

Only Windows has been checked. The packaged tests close the window while hosting, read the tray menu, stop hosting from the tray and from Manage hosting, quit from the tray, and quit with nothing hosted; the system's own quit confirmation is answered by the test, never shown. Whether a tray appears on Linux depends on the desktop environment, and macOS has not been run.

This page is made from docs/DEPLOYMENT.md.