Installation
OpenRun can run as a self-hosted web app platform on a Linux VPS, private server, local workstation or Kubernetes cluster. This page covers the install methods, running OpenRun as a service, the initial configuration and installing the first apps.
| Method | Platforms | Command |
|---|---|---|
| Install script | Linux, macOS, Windows with WSL | curl -sSL https://openrun.dev/install.sh | sh |
| Native packages | openSUSE Tumbleweed, Fedora, Debian | zypper install openrun, dnf install openrun, apt install openrun |
| Windows script | Windows | powershell -Command "irm https://openrun.dev/install.ps1 | iex" |
| winget | Windows | winget install OpenRunDev.OpenRun |
| Brew | macOS, Linux | brew install openrun |
| Source | Any platform with the Go toolchain | go build -o $OPENRUN_HOME/bin/openrun ./cmd/openrun/ |
Self-Hosted VPS Deployment
A single-node VPS installation uses Docker or Podman to run application containers and requires no external control plane. OpenRun provides a PaaS-style workflow with Git-based deployments, application routing, automatic TLS, authentication and scale-to-zero on infrastructure you control.
For a complete public VPS setup with DNS, TLS and OAuth, follow the self-hosted web apps on a VPS guide.
Install Release Build
Before installing:
- TLS certs: OpenRun manages TLS certs using Let’s Encrypt for prod environments. For a dev environment, install mkcert and run
mkcert -installbefore starting the OpenRun server. OpenRun automatically creates local certs using mkcert if it is present. - Containers: For container based apps, Docker, Podman or OrbStack should be installed and running on the machine. OpenRun automatically detects the container manager to use.
- Admin account: OpenRun creates an
adminaccount during installation or first server start. Save the generated password for the console and apps configured withsystemauthentication. Apps usenoneauthentication by default; see default authentication to change this.
To install the latest release build on Linux, macOS or Windows with WSL, run the install script. Note down the password printed and add the env variables as prompted.
curl -sSL https://openrun.dev/install.sh | shThe script:
- installs the latest release under
$OPENRUN_HOME(default$HOME/openrun, or/var/lib/openrunif that directory exists) - adds
$OPENRUN_HOME/binto the PATH in the shell profile - creates
openrun.tomlwith a generatedadminpassword, if noopenrun.tomlis present
To install a specific release, pass the version: curl -sSL https://openrun.dev/install.sh | sh -s v1.2611.130.
Open a new terminal to get the updated environment values, then run:
openrun server startTo install apps declaratively, run
openrun apply --approve github.com/openrundev/openrun/examples/utils.star /utils/bookmarksOpen https://localhost:25223 to access the app listing UI. See start the service for details.
Install On Linux (Native Packages)
Native packages (rpm/deb) are published for openSUSE Tumbleweed, Fedora and Debian through the Open Build Service. The package:
- installs the
openrunbinary - creates an
openrunservice account with home directory/var/lib/openrun - generates the initial config with a random
adminpassword (printed during install, note it down) - sets up the systemd service
openSUSE Tumbleweed
sudo zypper addrepo https://download.opensuse.org/repositories/home:/ajayvk:/openrun/openSUSE_Tumbleweed/home:ajayvk:openrun.repo
sudo zypper --gpg-auto-import-keys refresh
sudo zypper install openrunFedora
sudo dnf config-manager addrepo --from-repofile=https://download.opensuse.org/repositories/home:/ajayvk:/openrun/Fedora_Rawhide/home:ajayvk:openrun.repo
sudo dnf install openrunFor dnf 4, use sudo dnf config-manager --add-repo <repo url> instead.
Debian
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.opensuse.org/repositories/home:/ajayvk:/openrun/Debian_Unstable/Release.key | gpg --dearmor | sudo tee /etc/apt/keyrings/openrun.gpg > /dev/null
echo 'deb [signed-by=/etc/apt/keyrings/openrun.gpg] https://download.opensuse.org/repositories/home:/ajayvk:/openrun/Debian_Unstable/ /' | sudo tee /etc/apt/sources.list.d/openrun.list
sudo apt update && sudo apt install openrunStart the systemd service
sudo systemctl enable --now openrun- User: the server runs as the
openrunuser. - Config:
/var/lib/openrun/openrun.toml. - Logs: the journal (
journalctl -u openrun) and/var/lib/openrun/logs. - UI: open https://localhost:25223 to access the app listing UI, using
adminand the password printed during package installation.
On systemd-based distros without a native package, the same setup (openrun user, /var/lib/openrun home, systemd service) can be done with the setup script:
curl -sSL https://raw.githubusercontent.com/openrundev/openrun/refs/heads/main/deploy/setup_systemd.sh | sudo shZero downtime restarts and updates
On Linux and macOS, the server can restart in place with no downtime and no dropped connections. A new server process takes over the listening sockets, re-reads the config and starts serving. The old process finishes its in-flight requests and websockets (up to restart.drain_timeout_secs, default 300) and exits. Use this to apply config file changes or to move to a new server version. For a version update, upgrade the openrun binary first (e.g. apt upgrade openrun), then restart in place. Any of the following triggers the restart:
sudo systemctl reload openrun # systemd installs
openrun server restart # any install, uses the management API
kill -HUP <server pid>Apps are not affected: app containers keep running through the restart.
kubectl rollout restart, app traffic is drained via the pod’s termination grace period.Install On Windows
OpenRun can be installed on Windows either with the install script or with winget. The two methods use different home directory conventions, see switching between install methods before moving from one to the other.
| Method | OPENRUN_HOME | Binary location | Service setup |
|---|---|---|---|
| Install script | Set by the script (user env var) | $env:OPENRUN_HOME\bin | Script Service Install |
| winget | Left unset | winget packages directory, exposed through a links shim | Winget Service Install |
Install Using Script
To install the latest release with the install script, run:
powershell -Command "irm https://openrun.dev/install.ps1 | iex"The script:
- installs OpenRun under
$env:OPENRUN_HOME, defaulting to$HOME\openrun: the binary goes in$env:OPENRUN_HOME\binand the config file is$env:OPENRUN_HOME\openrun.toml - sets the
OPENRUN_HOMEuser environment variable to the install directory and adds thebindirectory to the user PATH - creates
openrun.tomlwith a generatedadminpassword, if noopenrun.tomlis present. Note down the password printed.
To install a specific release, set $v="v1.2611.130" before running the script. To install to a custom location, set $env:OPENRUN_HOME to the desired directory before running the script.
Open a new terminal to get the updated environment values, then run:
openrun server startOpen https://localhost:25223 to access the app listing UI.
Script Service Install
To run a script installed OpenRun as a Windows service, register openrun server start with the Windows Service Control Manager.
Register and start the service
From an elevated shell:
$OpenRunExe = Join-Path $env:OPENRUN_HOME 'bin\openrun.exe'
$OpenRunConfig = Join-Path $env:OPENRUN_HOME 'openrun.toml'
$BinPath = "`"$OpenRunExe`" --config-file `"$OpenRunConfig`" server start"
New-Service -Name openrun -DisplayName OpenRun -StartupType Automatic -BinaryPathName $BinPath -Description "OpenRun application server https://openrun.dev/"
sc.exe failure openrun reset= 86400 actions= restart/5000/restart/30000//
Start-Service openrunChoose the service account
The service runs as LocalSystem by default; for a network facing server, consider a less privileged account using sc.exe config openrun obj= <account>.
When started this way, OpenRun reports service status to Windows and handles service stop, shutdown and pre-shutdown requests as graceful server shutdowns.
Install Using Winget
To install OpenRun using winget, run:
winget install OpenRunDev.OpenRunWinget installs the binary under the user’s winget packages directory and exposes it through a links shim on the PATH; the winget install does not set OPENRUN_HOME. Open a new terminal so openrun is on the PATH, then run:
openrun server startIf OPENRUN_HOME is not set, no config path is configured and no existing installation is found, the first server start creates the home directory at $HOME\openrun, with the config file at $HOME\openrun\openrun.toml, and generates an admin password. Note down the password printed. To use a custom home directory, set $env:OPENRUN_HOME, create the directory and initialize the config with openrun password > "$env:OPENRUN_HOME\openrun.toml" before starting the server.
Open https://localhost:25223 to access the app listing UI.
Winget Service Install
To run OpenRun as a Windows service on a machine where it was installed with winget, the recommended approach is a machine scoped install with the service registered against an explicit config file. All commands run from an elevated shell.
Install at machine scope
winget install --scope machine OpenRunDev.OpenRunMachine scope installs the binary under Program Files\WinGet instead of the installing user’s profile, which is preferable for a service.
Create the home directory and config
Open a new elevated terminal so openrun is on the PATH, then create the home directory at %ProgramData%\openrun and the config file with a generated admin password:
$OpenRunHome = Join-Path $env:ProgramData 'openrun'
New-Item -ItemType Directory -Force $OpenRunHome | Out-Null
openrun password | Out-File -Encoding utf8 (Join-Path $OpenRunHome 'openrun.toml')Note down the password printed.
Register the service against the config file
$OpenRunExe = (Get-Command openrun.exe).Source
$OpenRunConfig = Join-Path $env:ProgramData 'openrun\openrun.toml'
$BinPath = "`"$OpenRunExe`" --config-file `"$OpenRunConfig`" server start"
New-Service -Name openrun -DisplayName OpenRun -StartupType Automatic -BinaryPathName $BinPath -Description "OpenRun application server https://openrun.dev/"
sc.exe failure openrun reset= 86400 actions= restart/5000/restart/30000//
Start-Service openrun- Upgrades:
(Get-Command openrun.exe).Sourceresolves to the winget links shim, which stays valid acrosswinget upgrade. After an upgrade, runsc.exe stop openrunandsc.exe start openrunto switch to the new binary. - Service account: the service runs as LocalSystem by default; for a network facing server, consider a less privileged account using
sc.exe config openrun obj= <account>.
How the service and the CLI find the home directory
Passing --config-file pins the server home directory to the config file’s directory (%ProgramData%\openrun here), keeping the service independent of any user profile. Without it, a service would resolve its home under the service account profile (for LocalSystem, C:\Windows\System32\config\systemprofile), and OpenRun refuses to auto-create a config there.
The openrun CLI finds this server automatically. A winget binary is a links shim, so the CLI cannot locate the server home relative to the executable like it does for script installs. When OPENRUN_HOME is not set it checks %ProgramData%\openrun\openrun.toml and connects over the unix domain socket under that home. On OpenRun releases before this discovery was added, set the env variable at machine scope instead:
[Environment]::SetEnvironmentVariable('OPENRUN_HOME', (Join-Path $env:ProgramData 'openrun'), 'Machine')Env changes apply to shells opened after the change, not existing ones.
Service for a user scoped winget install
For a default user scoped winget install, keep everything under the user profile instead:
- Run
openrun server startonce interactively to create$HOME\openrun\openrun.toml(note down the generated admin password). - Stop it with Ctrl+C.
- Register the service with
$OpenRunConfig = Join-Path $HOME 'openrun\openrun.toml'in theNew-Servicecommand above.
No env variable is needed in this setup: the CLI defaults to the same $HOME\openrun home. The upgrade and service account notes above apply to this flow too.
Switching Between Install Methods
The install script sets the OPENRUN_HOME environment variable, while winget installs rely on it being unset (the CLI then defaults to $HOME\openrun or discovers the %ProgramData%\openrun service home). When switching from one install method to the other, clear OPENRUN_HOME at both the user and the system (machine) level before installing with the other method, otherwise the CLI and server can end up pointing at a stale home directory. From an elevated shell:
[Environment]::SetEnvironmentVariable('OPENRUN_HOME', $null, 'User')
[Environment]::SetEnvironmentVariable('OPENRUN_HOME', $null, 'Machine')Then open a new terminal before installing with the other method. Also remove the previous install so that only one openrun is found on the PATH.
Removing the previous install
- Script to winget: remove the script install’s
bindirectory ($env:OPENRUN_HOME\bin,$HOME\openrun\binby default) from the user PATH, so that the winget links shim is theopenrunfound on the PATH. - Winget to script: uninstall the winget package with
winget uninstall OpenRunDev.OpenRun(add--scope machinefor a machine scoped install) before running the install script. This removes the winget links shim from the PATH. The install script appends itsbindirectory to the end of the user PATH, so if the shim is left in place it keeps taking precedence andopenruncontinues to resolve to the winget managed binary rather than the one the script installed.
To keep the existing apps and config, move or copy the old home directory contents to the new home directory (for example from $env:OPENRUN_HOME to $HOME\openrun) before starting the server.
Brew Install
On macOS and Linux, OpenRun can be installed using brew. Run
brew tap openrundev/homebrew-openrun
brew install openrun
brew services start openrunInstall from Source
The release binaries are available at releases. The instructions below assume $HOME/openrun/openrun.toml as the config file and $HOME/openrun as the work directory location.
Install the Go toolchain
Install the Go toolchain required by the checked-out revision’s go.mod. The current source requires Go 1.27.4 or newer.
Set the environment variables
Add the below env variables to your shell .profile or .bash_profile:
export OPENRUN_HOME=$HOME/openrun
export PATH=$OPENRUN_HOME/bin/:$PATHSource the updated profile file, for example source ~/.bash_profile.
Check out and build
# Ensure go is in the $PATH
mkdir -p $OPENRUN_HOME/bin
mkdir $HOME/openrun_source && cd $HOME/openrun_source
git clone -b main https://github.com/openrundev/openrun && cd openrun
go build -o $OPENRUN_HOME/bin/openrun ./cmd/openrun/Certs and Default password
The prerequisites listed under Install Release Build apply to every install method: mkcert for local TLS certs (installing OpenRun using brew automatically installs mkcert), a running Docker, Podman or OrbStack for container based apps, and the admin password generated during installation or first server start. Save that password for the console and apps configured with system authentication. New apps use none authentication unless the server default or app configuration selects another auth type.
Initial Configuration
The install scripts and native packages initialize the config. When no home or config path is configured and no installation is found, the first server start initializes $HOME/openrun/openrun.toml.
For the source installation above, or any custom OPENRUN_HOME, initialize the config explicitly. Run the following once for a new installation, before adding other settings; it overwrites the destination file:
openrun password > "$OPENRUN_HOME/openrun.toml"This prints a random admin password to the terminal and saves its hash in the config. Save the password for the console and apps using system authentication.
Start the service
To start the OpenRun server, run
openrun server startThe service logs go to $OPENRUN_HOME/logs. The service is started on https://localhost:25223 by default.
| Command | Effect |
|---|---|
openrun server status | Reports ok when the CLI can connect to the server |
openrun server version | Reports the server build version |
openrun server stop | Stops the server; add --wait to block until the server process has fully exited |
Apply a Sample App File
Apps can be installed declaratively from an app declaration file, which lists one or more app definitions. The examples/utils.star file in the OpenRun repo is a sample declaration which installs a few utility apps, a proxy app, a static file app and some container based apps (Python and Go). To apply it directly from GitHub, run
openrun apply --approve github.com/openrundev/openrun/examples/utils.star--approveapproves the plugin permissions requested by the apps.- Running the same command again updates the apps to match any changes in the file; apps already present are left as is if their declaration has not changed.
- The container based apps in the file need Docker or Podman to be running.
To apply only some of the apps from the file, pass an app path glob as the second argument. For example
openrun apply --approve github.com/openrundev/openrun/examples/utils.star /utils/bookmarksinstalls just the bookmarks app. Open https://localhost:25223/utils/bookmarks to access it. See declarative app management for the file format and apply options.
Schedule a Sync
Instead of applying manually, OpenRun can sync the declaration file from Git on a schedule, picking up app additions and config changes as they are committed. To create a scheduled sync for the sample file, run
openrun sync schedule --approve --promote github.com/openrundev/openrun/examples/utils.starThe sync runs every 15 minutes by default; use --minutes to change the frequency. --promote promotes the applied changes to prod immediately instead of staging them.
| Command | Effect |
|---|---|
openrun sync list | See the configured syncs |
openrun sync run <id> | Run a sync immediately |
openrun sync delete <id> | Remove a sync |
See automated sync for the full set of sync options, including webhook based sync.
Install the Console App
The management console is a web UI for managing the OpenRun server: apps, syncs, service bindings, containers, audit logs, server configuration and the AI app builder. A live demo of the console is available. The console is itself an OpenRun app, installed from the openrundev/console repo:
openrun app create --approve --auth system \
--param enable_all_features=true --param enable_updates=true \
github.com/openrundev/console /consoleOpen https://localhost:25223/console and log in as admin, using the password printed during the OpenRun installation.
The console requires an authenticated user for management operations. --auth system selects the admin account created during installation. OAuth/OIDC/SAML and builtin-user authentication can also be used with appropriate RBAC grants.
none auth for the console: management operations are blocked for anonymous users.The console features are controlled through app params, set with --param name=value during create:
| Param | Default | Description |
|---|---|---|
enable_updates | false | Enable write operations (create/update/delete). Without this, the console is read-only. |
enable_container | false | Enable the containers area |
enable_config | false | Enable the server configuration area |
enable_builder | false | Enable the AI app builder area |
enable_all_features | false | Enable all the areas above; write operations still need enable_updates |
The default install (no params) is a read-only console covering apps, syncs, bindings, the overview and audit logs. A disabled area registers no routes and requests no plugin permissions.
Params can be changed after install. Enabling a new area adds plugin permissions, which require re-approval; the change is staged and goes live on promotion:
openrun param update enable_builder true /consoleAfter enabling a new area, review and approve the added plugin permissions with openrun app approve --promote /console. The AI builder also requires server-side builder configuration; enabling the console area alone does not start it.