App Management Overview
Use openrun --help for the full command list and openrun <command> --help for current options. The main app-management commands include:
$ openrun
NAME:
openrun - OpenRun client and server https://openrun.dev/
USAGE:
openrun [global options] command [command options]
COMMANDS:
server Manage the OpenRun server
app Manage OpenRun apps
apply Apply app configuration declaratively
delete Delete the apps and bindings declared in an apply file
export Export current app and binding config as a declarative config file
pretty-print, fmt Pretty print a declarative config file
sync Manage sync operations, scheduled and webhook
job Run and inspect app jobs (scheduled, manual and before_deploy). Jobs are defined in app.star, apps.ace, --job or app update jobs
action List and run app actions. Actions are the operations an app exposes, they run as the logged in user
service Manage service entries
provider Manage out-of-process providers (binding and Starlark plugin providers)
binding Manage binding entries
replication Litestream replication status
secret Manage secrets in the embedded secrets store
param Manage app parameter values
version Manage app versions
app-webhook Manage app level webhooks
preview Manage OpenRun preview apps
account Manage OpenRun accounts
user Manage builtin auth users, for apps using the "builtin" auth type
api-key, apikey Manage API keys for remote CLI and MCP access
login Log in to a remote OpenRun server (browser flow, tokens stored in the OS keychain)
logout Log out from a remote OpenRun server (revokes the grant, clears stored tokens)
password Generate a password bcrypt config entry
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--config-file value, -c value TOML configuration file [$CL_CONFIG_FILE]
--server-uri value The server uri to connect to (unix socket path or https://host[:port]). Takes precedence over server_uri in the config file [$OPENRUN_SERVER_URI]
--as value Run the command as this user id (like builtin:user1) with RBAC enforcement. Requires RBAC to be enabled; supported over the unix domain socket only [$OPENRUN_AS_USER]
--client-version, --version, -v Print the client version, then run the command if one is given (default: false)
--help, -h show help
$ openrun app
NAME:
openrun app - Manage OpenRun apps
USAGE:
openrun app command [command options]
COMMANDS:
create Create a new app
list List apps
delete Delete an app
approve Approve app permissions
reload Reload the app source code
promote Promote the app from staging to production
settings Update OpenRun apps settings. Settings changes are NOT staged, they apply immediately to matched staging, prod and preview apps.
update Update OpenRun app metadata. Metadata updates are staged and have to be promoted to prod. Use "openrun param" to update app parameter metadata.
help, h Shows a list of commands or help for one commandThe app management subcommands are under app. The preview and version commands manage previews and versions, and account manages saved app login accounts. This page covers:
- App Management and the glob pattern used by multi-app commands
- App Listing: list output formats, listing and switching versions, version retention
- App Authentication
- Declarative App Management: the
applyanddeletecommands and the app declaration format - Automated Sync from Git and its frequency
Related workflows: export and formatting, service bindings, jobs and webhooks.
App Management
- All the app management subcommands except
createtake a glob pattern, so multiple apps can be updated using one command. - Use the
--dry-runoption with any update CLI call to verify the options before the actual run. No database changes are committed during dry-run and no changes are done in memory.
Glob Pattern
The reload/delete/promote/approve/list/update commands accept a glob pattern. Place the pattern inside double-quotes to avoid issues with shell star expansion, for example "example.com:**".
| Pattern | Matches |
|---|---|
example.com:** | Apps under the example.com domain |
*:** | All apps in all domains |
all | Shortcut for *:** |
app listlists all apps by default. All other commands require a glob pattern to be specified explicitly.- Multi-app operations commit app metadata atomically: if an app fails before the transaction commits, metadata changes for the operation are rolled back. This does not roll back external effects such as database migrations or commands run by deployment hooks.
App Listing
Use the app list command to list apps. With the --internal option, the internal staging and preview apps for each matched prod app are also listed.
$ openrun app list
Name Type Ver Auth AppPath
Memory Usage PROD 3 NONE memory.demo.clace.io:/
Cowbull PROD 3 NONE cowbull.co:/
Demo PROD 3 NONE /
Disk Usage PROD 3 NONE du.demo.clace.io:/
Bookmarks PROD 5 NONE utils.demo.clace.io:/bookmarks
$ openrun app list -i
Name Type Ver Auth AppPath
Memory Usage PROD 3 NONE memory.demo.clace.io:/
Memory Usage STG 3 NONE stage.memory.demo.clace.io:/
Cowbull PROD 3 NONE cowbull.co:/
Cowbull STG 3 NONE stage.cowbull.co:/
Demo PROD 3 NONE /
Demo STG 3 NONE stage.localhost:/
Disk Usage PROD 3 NONE du.demo.clace.io:/
Disk Usage STG 3 NONE stage.du.demo.clace.io:/
Bookmarks PROD 5 NONE utils.demo.clace.io:/bookmarks
Bookmarks STG 5 NONE stage.utils.demo.clace.io:/bookmarks| Type | Meaning |
|---|---|
PROD | Production app |
STG | Staging app |
VIEW | Preview app |
DEV | Development app |
PROD* | A star indicates staged changes waiting to be promoted. It shows up any time the prod app is at a different version than the stage app |
The table format (--format table) adds the app id, source URL, spec and git branch/commit columns.
Output Formats
The list commands (app list, version list, version files, binding list, service list, secret list, job list, job runs, action list, action runs, apikey list, user list, sync list, app-webhook list, provider list, replication status) take a --format option.
- Fixed formats:
basic(the default, fewer columns),table,csv,json,jsonlandjsonl_pretty. - Default format: set by the
client.default_formatconfig entry (defaultbasic). Theversion listexamples on this page use thetableformat. - Templates: any other
--formatvalue which contains{{is treated as a Go template, the waydocker --formatworks. The template is rendered once per entry, one line per entry. The data is the entry in its JSON form, so the field names are the ones--format jsonshows:
$ openrun app list --format '{{.metadata.name}} v{{.metadata.version_metadata.version}} {{.source_url}}'
bookmarks v5 github.com/openrundev/apps/utils/bookmarks
$ openrun version list --format '{{if .active}}* {{end}}{{.version}} {{.metadata.version_metadata.git_commit | trunc 8}}' /bookmarks
1 86385ff6
* 2 ed7545aeFunctions available in the template:
| Function | Effect |
|---|---|
| sprig functions | The full sprig library |
json | Prints a value as compact JSON ({{json .}} prints the whole entry) |
relTime | Renders a timestamp as a relative age like 3 hours ago |
A template which does not parse is reported as an error before the server is called.
Listing Versions
Use the version list command to list versions for particular apps. This command works on the prod app or, with --stage, on the staging app specifically.
$ openrun version list --stage utils.demo.clace.io:/bookmarks
Active Version Previous CreateTime GitCommit GitMessage
1 0 2024-03-01 19:59:27 +0000 UTC 86385ff67deab288c362 Updated bookmarks app
2 1 2024-03-01 20:00:20 +0000 UTC 86385ff67deab288c362 Updated bookmarks app
3 2 2024-03-01 20:16:08 +0000 UTC 86385ff67deab288c362 Updated bookmarks app
4 3 2024-03-02 00:12:28 +0000 UTC 8080fcfe6be832a1f6f5 Update styling for bookmarks app
=====> 5 4 2024-03-02 00:23:35 +0000 UTC ed7545ae739dfe85140a Update styling for bookmarks app
$ openrun version list utils.demo.clace.io:/bookmarks
Active Version Previous CreateTime GitCommit GitMessage
1 0 2024-03-01 19:59:27 +0000 UTC 86385ff67deab288c362 Updated bookmarks app
2 1 2024-03-01 20:00:20 +0000 UTC 86385ff67deab288c362 Updated bookmarks app
=====> 5 2 2024-03-02 00:23:35 +0000 UTC ed7545ae739dfe85140a Update styling for bookmarks appIn this listing, the staging app has five versions. Three of those (1, 2 and 5) were promoted to prod.
Switching Versions
| Command | Effect |
|---|---|
version switch | Switch versions, up or down or to a particular version. Accepts previous, next or an actual version number as the version to switch to |
version revert | Revert the last change |
app promote | Make the prod app run the same version as the current staging app |
Continuing the listing above:
version switch --stage previous utils.demo.clace.io:/bookmarkschanges the stage app to version 4.version switch previous utils.demo.clace.io:/bookmarkschanges the prod app to version 2.- After that,
app promote utils.demo.clace.io:/bookmarkschanges prod to also be at version 4, same as stage.
Version Retention
- By default, OpenRun keeps the current version plus 5 older versions for each app. Version cleanup runs automatically after operations which create or promote new app versions, so the version list does not grow without bound.
- The retention count can be changed globally with
app_config.fs.retain_versionsinopenrun.toml, or per app withopenrun app update conf --promote fs.retain_versions=<count> /myapp. - In Docker/Podman mode, the images of older versions are kept for quick version switches. The count is controlled by
container.retain_previous_images(default1), see container config. Switching to a version whose image was removed rebuilds it.
App Authentication
- By default, apps are created with the no authentication type.
systemauth usesadminas the username. The password is displayed on the screen during the initial setup of the OpenRun server config.- To set the auth type at creation, add
--auth systemto theapp createcommand. After an app is created, change it by runningapp update auth --promote system /myapp. - OAuth based authentication is also supported, see authentication for details.
Changes done to the app settings using the app settings command are NOT staged or versioned, they apply immediately to the stage/prod/preview apps.
All other changes done to app metadata using app update, app reload, param update etc are staged before deployment. Use the --promote option on the change to promote the change immediately when applying it on the staging app. Use app promote command to promote later. When a promotion is done, ALL currently staged changes for that app are promoted, not just the most recent change. After promote, the prod app is exactly same as staging app.
Declarative App Management
The CLI and management apps allow imperative management of OpenRun apps. Apps can also be managed declaratively: declare them in an app declaration file and OpenRun applies the configuration, similar to the Kubernetes apply functionality.
Create a Starlark declaration file containing one or more app definitions. Any filename is accepted; apps.ace and apps.star are conventions. For example, in apps.ace:
app("/myapps/disk_usage", "github.com/openrundev/apps/system/disk_usage")
app("/myapps/memory_usage", "github.com/openrundev/apps/system/memory_usage")
app("/myapps/list_files", "github.com/openrundev/apps/system/list_files")defines three apps. Running
openrun apply --approve apps.acewill create the apps if not already present. If present, the app configuration is updated to match the new configuration.
Apply Command
The apply command takes one or two arguments: <filePath> [<appPathGlob>]. The first is a file path, which can be a glob pointing to multiple files. The files can be from local disk or from a Git URL. The second optional argument is an app path glob which specifies which apps to apply from the loaded files. By default, all apps in the file(s) are applied.
The options the apply command takes are:
OPTIONS:
--dev, -d Create apps in development mode (default: false)
--branch value, -b value The branch to checkout if using git source (default: "main")
--commit value, -c value The commit SHA to checkout if using git source. This takes precedence over branch
--git-auth value, -g value The name of the git_auth entry in server config to use
--approve, -a Approve the app permissions (default: false)
--reload value, -r value Which apps to reload: none, updated, matched
--promote, -p Promote changes from stage to prod (default: false)
--verify Verify reload by reloading app containers (default: false)
--clobber Force update app config, overwriting non-declarative changes (default: false)
--force-reload, -f Force reload even if there is no new commit (default: false)
--dry-run Verify command but don't commit any changes (default: false)
--help, -h show help| Option | Effect |
|---|---|
--branch, --commit, --git-auth | Apply to the apply file itself, if the file path is a Git URL. For the app source code, the git config has to be specified in the config file |
--promote | By default, changes are applied to the stage app. Add --promote to promote the changes |
--approve | Approve any permission changes required by apps |
--reload none | No apps are reloaded |
--reload updated | Apps which have a config update are reloaded |
--reload matched | The default. All apps matched by the app glob are reloaded, even if there is no config update |
--verify | Verify reloads for every matched app, see reload verification below |
--clobber | Overwrite any changes applied imperatively through the CLI or UI. The new declarative config overwrites any existing state |
--dev | Create the apps in dev mode. For apps with source path pointing to git, a local source folder is created under $OPENRUN_HOME/app_src. This allows for easy zero-config dev environment setup |
The --reload option controls whether new source code is loaded for apps during the apply operation.
Without --clobber, changes are applied as a three way merge. The old config and new config are compared against the live config. If there are changes between old and new declarative config, those changes are applied. Changes done imperatively are not overwritten.
Reload Verification
- Verification starts the reloaded app container and waits for it to become healthy before the metadata transaction opens. Traffic switches to it only when the transaction commits.
- If verification fails for any app, the apply operation fails and the changes are reverted.
- Kubernetes apps with persistent volumes cannot start a second version: their objects are validated before the transaction and the rollout runs when it commits, see Kubernetes.
- When any apply verification runs successfully, OpenRun retries pending service binding grants for bindings in the current apply file after the app reload, so grants for tables created during startup can be applied. Grants already recorded in
grants_appliedare not retried.
To verify specific apps in a declarative apply file instead of using the top-level --verify option, set verify=True on those app declarations:
app("/todo/admin", "github.com/example/todo", bindings=["/todo-data/admin"], verify=True)
app("/todo/app", "github.com/example/todo", bindings=["/todo-data/app"])Delete Command
The delete command is the counterpart of apply for removal. It takes the same <filePath> [<appPathGlob>] arguments (with the --branch, --commit, --git-auth and --dry-run options): the apps and bindings declared in the file that match the glob and currently exist are deleted, similar to kubectl delete -f.
openrun delete apps.ace
openrun delete apps.ace "example.com:**"- Any matching declared resource is deleted, regardless of whether it was created declaratively or imperatively.
- Declared resources that do not exist are skipped and reported.
- All deletes run in one transaction, apps before bindings. A blocked delete (for example a declared base binding that still has derived bindings not covered by the file) fails and rolls back the whole command.
- Deleted apps are fully removed, containers, images, volumes and networks included. Deleted bindings drop their backend objects the same way
binding deletedoes.
App Configuration
The declarative app configuration uses Starlark syntax. An app is defined using the app struct which has these properties:
| Property | Optional | Type | Default | Notes |
|---|---|---|---|---|
| path | false | string | The app installation domain:path | |
| source | false | string | The app source code url | |
| dev | true | bool | false | Whether app is in dev mode |
| auth | true | string | default | The app authentication type (none or system or default or |
| git_auth | true | string | default | The git auth entry to use |
| git_branch | true | string | main | The git branch to use |
| git_commit | true | string | The git commit to use | |
| params | true | dict | The params for the app | |
| spec | true | string | The app spec to use for the app | |
| app_config | true | dict | The config settings for the app | |
| container_opts | true | dict | The container options for the app | |
| container_args | true | dict | The container build args options for the app | |
| container_vols | true | list string | The container volumes for the app | |
| stage_at | true | string | system | Staging location for new prod apps: domain_suffix, domain, path, or a staging domain. Applies when the app is created |
| sidecars | true | list dict | The sidecar containers for the app, same JSON fields as --sidecar | |
| bindings | true | list string | The paths of the service bindings to attach to the app | |
| jobs | true | list | [] | Jobs and deploy hooks, declared with job(...), dictionaries or JSON strings |
| verify | true | bool | false | Verify reload for this app only |
| mcp | true | bool/string/dict | MCP setting: True, False (all MCP off), "/path" or a dict with the same fields as --mcp |
For example, a definition like
app("/streamlit", "github.com/streamlit/streamlit-example",
git_branch="master", spec="python-streamlit",
params={"app_file": "streamlit_app.py"}, container_opts={"cpus": 1},
container_vols=["/data"], app_config={"container.idle_shutdown_secs": 600}
)defines a Streamlit app. Config can also be updated through the CLI or UI. Subsequent applies retain those imperative changes unless the same property changes in the declaration or --clobber is used. For example, a new parameter added through the CLI is retained. Changing app_file in the declaration updates that parameter on the next apply.
auth and git_auth, can be updated declaratively and is staged before promotion. New versions can be reverted with openrun version revert. Only app settings changes, such as staging write access, apply immediately without versioning.Automated Sync
OpenRun supports automatically syncing the app declarations from Git. The commands to manage sync are:
openrun sync
NAME:
openrun sync - Manage sync operations, scheduled and webhook
USAGE:
openrun sync command [command options]
COMMANDS:
schedule Create scheduled sync job for updating app config
run Run specified sync job
list List the sync jobs
delete Delete specified sync job
help, h Shows a list of commands or help for one commandopenrun sync schedule --approve --promote github.com/openrundev/openrun/examples/utils.star will create a scheduled sync which will run every 15 minutes and check for app config updates to apply. Use --minutes option to change the frequency.
openrun sync schedule --help
NAME:
openrun sync schedule - Create scheduled sync job for updating app config
USAGE:
args: <filePath>
<filePath> is the path to the apply file containing the app configuration.
Examples:
Create scheduled sync, reloading apps with code changes: openrun sync schedule ./app.ace
Create scheduled sync, reloading only apps with a config change: openrun sync schedule --reload=updated github.com/openrundev/apps/apps.ace
Create scheduled sync, promoting changes: openrun sync schedule --promote --approve github.com/openrundev/apps/apps.ace
Create scheduled sync, verifying reload before promoting changes: openrun sync schedule --verify --promote --approve github.com/openrundev/apps/apps.ace
Create scheduled sync, overwriting changes: openrun sync schedule --promote --clobber github.com/openrundev/apps/apps.ace
OPTIONS:
--branch value, -b value The branch to checkout if using git source (default: "main")
--git-auth value, -g value The name of the git_auth entry in server config to use
--approve, -a Approve the app permissions (default: false)
--reload value, -r value Which apps to reload: none, updated, matched
--promote, -p Promote changes from stage to prod (default: false)
--verify Verify reload by reloading app containers (default: false)
--minutes value, -s value Schedule sync for every N minutes (default: 0)
--clobber Force update app config, overwriting non-declarative changes (default: false)
--force-reload, -f Force reload even if there are no new commits (default: false)
--prune Delete apps and bindings created by this sync that are no longer declared (default: false)
--dry-run Verify command but don't commit any changes (default: false)
--help, -h show helpScheduled sync takes all the same options as the apply command except --dev and --commit. The apply is done automatically by OpenRun on schedule.
--verify: each sync run verifies app reloads before promoting changes.--prune: each sync run deletes the apps and bindings this sync itself created that are no longer present in the apply file, making the file the full source of truth for the resources it manages.- Only resources originally created by the sync are pruned. Apps and bindings created imperatively (or by another sync), even if they were later updated by this sync, are left alone.
- Pruned apps are fully deleted, containers, images, volumes and networks included. Pruned bindings drop their backend objects the same way
binding deletedoes. - Pruning runs in the same transaction as the apply, so a blocked delete (for example a pruned base binding that still has derived bindings created outside the sync) fails and rolls back that sync run.
| Command | Effect |
|---|---|
openrun sync list | List syncs |
openrun sync run <sync_id> | Run a sync immediately. A successful run resets the failure count and re-enables a disabled sync |
openrun sync delete <sync_id> | Remove the schedule. Deleting a sync does not delete its deployed apps or bindings |
A scheduled sync which fails system.max_sync_failure_count times in a row (default 5) is marked Disabled in sync list and skipped by the scheduler. A successful openrun sync run <sync_id> re-enables it.
Sync Frequency
The default sync frequency is every 15 minutes. This can be changed for each sync by passing --minutes 10 during sync creation. To change the default globally, for any new sync being created, set
[system]
default_schedule_mins = 10GitHub imposes a rate limit for API calls.
- Every sync run makes one list API call to the apply file repo and one API call to each source file repo. If apply files and source files are in the same repo, there is just one API call in total.
- If there are multiple sync operations, each runs independently.
- If a new commit is found, then a clone is done on the repo.
- Sync can be run more frequently, making sure rate limits are respected. If a default git auth entry is added, that will be used for all list API calls. The rate limits are higher for authenticated requests.