Installation

Install Release Build

OpenRun manages TLS cert using LetsEncrypt for prod environments. For dev environment, it is recommended to install mkcert. OpenRun will automatically create local certs using mkcert if it is present. Install mkcert and run mkcert -install before starting OpenRun server.

For container based apps, Docker or Podman or Orbstack should be installed and running on the machine. OpenRun automatically detects the container manager to use.

OpenRun uses an admin user account as the default authentication for accessing apps. A random password is generated for this account during initial OpenRun server installation. Note down this password for accessing apps.

To install the latest release build on Linux, OSX or Windows with WSL, run the install script. Note down the password printed. Add the env variables as prompted and then start the service.

curl -sSL https://openrun.dev/install.sh | sh

Open a new terminal to get the updated environment values, then run:

openrun server start

To install apps declaratively, run

openrun apply --approve github.com/openrundev/openrun/examples/utils.star all

Open 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 openrun binary, creates an openrun service account with home directory /var/lib/openrun, generates the initial config with a random admin password (printed during install, note it down) and 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 openrun

Fedora

sudo dnf config-manager addrepo --from-repofile=https://download.opensuse.org/repositories/home:/ajayvk:/openrun/Fedora_Rawhide/home:ajayvk:openrun.repo
sudo dnf install openrun

For 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 openrun

Start the systemd service

sudo systemctl enable --now openrun

The server runs as the openrun user, using the config file at /var/lib/openrun/openrun.toml. Logs go to the journal (journalctl -u openrun) and /var/lib/openrun/logs. Open https://localhost:25223 to access the app listing UI, using admin and 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 sh

Install On Windows

To install the OpenRun application on Windows, run:

powershell -Command "irm https://openrun.dev/install.ps1 | iex"

The app is installed under $env:OPENRUN_HOME, defaulting to $HOME\openrun. Note down the generated password for the admin user. Open a new terminal to get the updated environment values, then run:

openrun server start

To run OpenRun as a Windows service, register openrun server start with the Windows Service Control Manager from an elevated shell:

$OpenRunExe = Join-Path $env:OPENRUN_HOME 'bin\openrun.exe'
$OpenRunConfig = Join-Path $env:OPENRUN_HOME 'openrun.toml'
sc.exe create openrun start= auto DisplayName= "OpenRun" binPath= "`"$OpenRunExe`" --config-file `"$OpenRunConfig`" server start"
sc.exe description openrun "OpenRun application server https://openrun.dev/"
sc.exe failure openrun reset= 86400 actions= restart/5000/restart/30000//
sc.exe start openrun

The paths from $env:OPENRUN_HOME are expanded when the service is created; re-create the service if the install location changes. 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.

Open https://localhost:25223 to access the app listing UI.

Brew Install

To install using brew, run

brew tap openrundev/homebrew-openrun
brew install openrun
brew services start openrun

Install from Source

The release binaries are available at releases.

To install from source

• Ensure that a recent version of Go is available, version 1.21.0 or newer.
• Checkout the OpenRun repo.
• The below instructions assume you are using $HOME/clhome/openrun.toml as the config file and $HOME/clhome as the work directory location.

First add the below env variables to your shell .profile or .bash_profile:

export OPENRUN_HOME=$HOME/clhome
export PATH=$OPENRUN_HOME/bin/:$PATH

Source the update profile file, like source ~/.bash_profile. Build the OpenRun binary

# 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

OpenRun manages TLS cert using LetsEncrypt for prod environments. For dev environment, it is recommended to install mkcert. OpenRun will automatically create local certs using mkcert if it is present. Install mkcert and run mkcert -install before starting OpenRun server. Installing OpenRun using brew will automatically install mkcert.

For container based apps, Docker or Podman or Orbstack should be installed and running on the machine. OpenRun automatically detects the container manager to use.

OpenRun uses an admin user account as the default authentication for accessing apps. A random password is generated for this account during initial OpenRun server installation. Note down this password for accessing apps if using system auth.

Initial Configuration

To use the openrun service, you need an initial config file with the service password and a work directory. Create the openrun.toml file, and create a randomly generate password for the admin user account

openrun password > $OPENRUN_HOME/openrun.toml

This will print a random password on the screen, note that down as the password to use for accessing the applications.

Start the service

To start the OpenRun server, run

openrun server start

The service logs will be going to $OPENRUN_HOME/logs. The service will be started on https://localhost:25223 by default.

Load an App

To create an app, ensure that code is available locally and then run the OpenRun client

openrun app create --dev $HOME/openrun_source/openrun/examples/disk_usage /disk_usage

To audit and approve the app’s security policies, run

openrun app approve /disk_usage

This will create an app at /disk_usage with the example disk_usage app. The disk_usage app allows the user to explore the subfolders which are consuming most disk space.

To access the app, go to https://localhost:25223/disk_usage. Use admin as the username and use the password previously generated.

The code for the disk usage app is in GitHub. app.star is the Starlark config and app.go.html is the html template. The other files are generated files and are created during app development.