Security Configuration
The default configuration for the OpenRun server is:
- Application management (admin APIs) are accessible over unix domain sockets only (not accessible remotely). Since UDS enforces file permissions checks, no additional authentication is needed for admin APIs.
- Apps use
noneauthentication by default. Set--auth systemto require the admin account, or select another configured authentication provider. - Installers and first-start setup save a generated admin password hash in the config file. If an existing config omits the hash, the server generates a temporary password on each restart.
- Builtin users, OAuth/OIDC, SAML and client certificate authentication are supported. Builtin users can be managed through
openrun userwithout restarting the server. - RBAC is enforced for app access and management operations. The default grant allows every principal, including
anonymous, to access and list apps; additional management permissions require grants or resource ownership.
This page covers the admin account and admin API, the server-level plugin permission defaults (including host commands, container secrets and mounts), the unsafe_* development flags, disk path access over the remote API, CSRF, security headers, CORS, trusted proxies and git access to private repositories.
Admin Account Password
When the OpenRun server starts, it looks for this entry in the config file:
[security]
admin_password_bcrypt = "" # the password bcrypt value- If the value is undefined or empty in an existing config, a random password is generated for that server session and printed during startup. This temporary password changes on every restart.
- Normal installation and first-start setup persist the hash, so the generated password remains valid across restarts.
- The admin username is
adminby default. Change it with the top-leveladmin_userkey inopenrun.toml.
To generate a random admin password, use the password helper command:
openrun passwordThis prints the password and its bcrypt value. Save the password in your password manager and add the bcrypt hash to your config file.
To use a particular value for the admin password, run:
openrun password --promptThis prompts for the password and prints the bcrypt hash to add to the config file.
Admin API Access
- By default, the OpenRun client uses Unix domain sockets to connect to the OpenRun server. Admin API calls to manage applications are disabled over HTTP/HTTPS by default.
- Unix sockets work when the client is on the same machine as the server; the client does not need to pass any credentials to connect over unix sockets.
- The socket is created at
server_uri(default$OPENRUN_HOME/run/openrun.sock) with file mode0700, so only the OS user running the server (and root) can connect. - Only local CLI requests over the unix domain socket are treated as transport-trusted and skip the RBAC checks; remote requests are always attributed to their credential’s user.
To manage the server from another machine (the remote CLI) or connect an AI client over MCP, enable the remote API surfaces. See Remote API and MCP for the setup walkthrough, API keys, openrun login, defaults and security best practices.
Application Security
See appsecurity for details about the application level sandboxing and authentication for details about adding OAuth/OIDC/SAML/cert-based auth for apps.
Default Plugin Permissions
OpenRun can allow plugin calls at the server level so apps do not need an explicitly approved permission entry in app metadata. The default server permissions are:
[[permissions.allow]]
plugin = "proxy.in"
method = "config"
arguments = ["<CONTAINER_URL>"]
[[permissions.allow]]
plugin = "container.in"
method = "config"
arguments = ["regex:.*"]
secrets = [] # no secrets allowed by default
[[permissions.allow]]
plugin = "http.in"
method = "regex:.*"
arguments = ["regex:^<CONTAINER_URL>"] # only calls to the app's own container are auto-allowed
secrets = []How a permissions.allow entry matches:
- Scope:
permissions.allowadds globally approved plugin calls for all apps. method: an exact method name or aregex:pattern (thehttp.indefault covers every method of the plugin that way).arguments: exact values orregex:patterns matched against the positional arguments of the call, position by position. A call that passes a restricted argument by keyword is not approved by an entry with argument patterns.secrets: when present, controls which secrets the globally approved plugin call can resolve. An emptysecretslist means the global approval does not grant access to any secret values.- Secret templates: when an argument carries a
{{secret ...}}template, the argument patterns are checked twice: on the raw text before the call is approved, and again on the resolved value the plugin receives. The resolved value must match the patterns of the permission that approved the call and must not match apermissions.disallowentry, so a template cannot assemble a value the raw text did not show.
Outbound HTTP (http.in):
- The default only auto-allows outbound HTTP calls to the app’s own container (
<CONTAINER_URL>...), so a Starlark frontend can call its own backend without an approval. Calls to any other host fall back to requiring an approvedhttp.inpermission. - The pattern is anchored with
^because the argument matcher is unanchored. Without it an app could embed<CONTAINER_URL>inside an external URL to bypass the restriction. - The
paramsvalues are merged into the url’s query, so the url the request goes out with is checked the same way as theurlargument (against the disallow list and the app’s approvedhttp.inpermissions). - When a response redirects, each redirect target is checked the same way before it is followed, so a permitted host cannot redirect the request to one that is not. When the call resolved secrets (in
ace.evalor param template values), the permission approving the redirect target must also grant those secrets, since custom headers and a 307/308 body are forwarded to the target. - To allow all outbound HTTP, use
arguments = ["regex:.*"]. This opens an SSRF surface, since these calls originate from the server’s network position and can reach internal or metadata endpoints. To allow specific hosts, list them, e.g.arguments = ["regex:^https://api\\.example\\.com/.*"].
permissions.disallow blocks matching plugin calls for every app, even when the app’s approved permissions (or the permissions.allow list) would permit them:
- Entries match with the same options as
allow: an emptymethodmatches every method of the plugin (aregex:method matches by pattern), andarguments(exact orregex:) narrow the block to matching calls. - An entry with argument patterns also blocks a call that passes keyword arguments in place of the positional arguments the patterns cover, since the patterns cannot see keyword values.
For example, to stop every app from revealing secret values through the admin plugin:
[[permissions.disallow]]
plugin = "openrun_admin.in"
method = "secret_reveal"Host commands (exec plugin)
The exec.in plugin runs commands on the server host, as the server user. Besides the per-app approval of each command, the server keeps an allowlist of the executables any app may run, security.allowed_exec_commands, and of the environment variables an app may pass them, security.allowed_exec_env. Both are empty by default, so no host command runs until the operator lists it.
exec.in. The allowlist bounds which program starts, not what the program does: the app chooses the arguments, and a program that runs other programs hands the app everything those can do. There is no safe way to allowlist a shell, an interpreter, or a general-purpose tool, and the lists do not substitute for trusting the apps and everyone who can change their code. Before adding an entry, assume the apps will use it in every way the program allows. For workloads that are not trusted to that degree, run the command inside the app’s container with container.in instead, which the host lists do not govern. Adding the openrun binary to the allow list can allow app code to do admin operations against the openrun server, so it is not recommended.[security]
allowed_exec_commands = [
"du", # bare name, looked up on the server PATH
"/usr/local/bin/ffmpeg", # absolute path
"/opt/tools/*", # glob: * does not cross a slash, ** does
"!/opt/tools/*sh", # exclusion, applied after the allow entries
]- Two layers apply: the server list says which executables the host permits at all, and the app’s approved
exec.inpermission says which of them that app may call, with which arguments. An app approved forexec.in runwithout argument restrictions is still bounded by the server list, but its arguments are then entirely up to the app’s code. "*"allows every executable, restoring the behavior of a server with no allowlist.- The OpenRun binary itself is always refused, whatever the list says. An app that needs management operations uses the
openrun_admin.inplugin, which is subject to authentication and RBAC. - Entry syntax: environment variables in entries are expanded. Globs must be absolute. A malformed entry is rejected at startup and on dynamic config updates.
- Privileged plugin: the exec plugin is additionally a privileged system plugin. Like
openrun_adminandbuild, it requires an authenticated (non-anonymous) caller unlesssecurity.unsafe_allow_system_plugins_anonis set.
How commands are matched
- Commands are matched on the file that would actually run, not on the string the app passes: a bare name is resolved on the server’s
PATH, a relative path against the call’scwd, and symlinks are followed before matching. - An exact entry (a bare name or an absolute path) matches when the requested command is the same file and has the same name as the entry. A symlink or a relative path cannot stand in for another program, and one command of a multi-call binary cannot stand in for another.
- Multi-call binaries: on Alpine (the base of the official container image)
ls,shand nearly every other command are the singlebusyboxfile, and on recent Ubuntu the coreutils are oneuutilsfile. Matching the file alone would make an entry oflsadmitshorenv. - Globs match the resolved path under any name. The literal directory prefix of a glob is itself resolved, so
/bin/*also covers/usr/binon Linux distributions where/binis a symlink. - Exclusions: a
!exclusion is broader than an allow entry. It matches by file or by name, so excluding one name of a multi-call binary excludes the file, and with it every command it provides.
When choosing entries, avoid:
| Avoid | Why |
|---|---|
Shells and interpreters (sh, bash, python, perl, node, awk) | They run whatever the app passes. |
Programs that start other programs: env, xargs, find (-exec), tar (--to-command), git (-c core.sshCommand=..., hooks), make, nohup, timeout, nice, watch, sudo, su | Many utilities have such an option; check before listing one. |
Globs over system directories (/bin/*, /usr/bin/*) | They contain all of the above, and on a multi-call system the glob covers every name of the binary, so /bin/* admits the shell whether or not !/bin/*sh is listed, since busybox sh is also a shell. A glob is for a directory the operator populates with specific tools, such as /opt/tools/*. |
Programs that read or write arbitrary paths (cat, cp, tee, dd, curl) when the arguments are not restricted | They reach the server’s configuration, database and secrets as the server user. |
Instead, list the specific programs an app needs, by name or absolute path, and restrict the call in the app’s exec.in approval: ace.permission("exec.in", "run", ["du"]) pins the command, and a second regex: entry can constrain the text of the arguments list.
The environment an app passes to a host command (the env argument of exec.run) is bounded by security.allowed_exec_env, a list of variable names:
[security]
allowed_exec_env = [
"TZ", # a name
"MYAPP_*", # a pattern: * ? and [...] on the name
"!MYAPP_AUTH", # an exclusion, applied after the allow entries
]- The list is empty by default: a call that passes any variable is refused, while a call that passes none runs with an empty environment (the server’s own environment is never inherited).
"*"allows every name. Prefer the variables the program is documented to read over"*".- Names are compared case-insensitively on Windows, where the child sees
PathasPATH, and exactly elsewhere.
Environment variables that load code (never list these)
The environment is the usual way to make an allowed program run other code even when the file that runs is the right one:
| Variable | What it does |
|---|---|
LD_PRELOAD, LD_LIBRARY_PATH (DYLD_* on macOS) | Honored by the dynamic loader for every dynamically linked program. |
BASH_FUNC_* | bash imports function definitions from these variables. |
BASH_ENV, ENV | bash runs these files. |
GIT_SSH_COMMAND, GIT_EXTERNAL_DIFF, GIT_CONFIG_* | git runs the programs named in them. |
PERL5OPT, PYTHONSTARTUP | Load code into interpreters. |
PATH | Decides which helpers a script finds. |
Containerized apps and secrets
The default OpenRun server config already includes two implicit approvals used by containerized apps:
proxy.config(container.URL, ...)container.config(...)
Because of these defaults, a standard containerized app does not need explicit ace.permission(...) entries just to call proxy.config(container.URL) and container.config(...).
- No secrets by default: the default
container.config(...)approval does not allow secrets. If a containerized app passes secrets through params, build args or generated secret volumes, the app must declare and receive approval for acontainer.configpermission with the requiredsecrets=[...]allowlist, or the server config must be intentionally changed to allow those secrets globally. - Two levels: the server entry approves the plugin call, so an app whose
container.configpermission declaressecrets=[...]still deploys without approval. The secrets themselves are granted by the app’s approved permissions (plus any secrets on the server entry): until the app is approved, the declared secrets do not resolve and the container fails to start with an error saying so. - Warnings and approval:
openrun app createandopenrun app reloadprint a warning when the app declares secret access it does not have, andopenrun app approve <path>(or--approveon create/reload) records the declared secrets as approved.openrun param updatewarns in the same way when the new value references a secret the app cannot resolve, or when it declares the access (thesecretsparam of the built-in specs). - Built-in container specs: secret access is opt-in. Their
container.configpermission uses thesecretsparam as its allowlist, which defaults to none, so an app passing no secrets needs no approval. Setting it declares the access, e.g.--param secrets='[["DB_PASSWORD"]]'(or[["regex:.*"]]for all secrets), after which the app must be approved.
For example, to restore blanket server-level secret access for containerized apps:
[[permissions.allow]]
plugin = "container.in"
method = "config"
arguments = ["regex:.*"]
secrets = [["regex:.*"]]Bind mounts and other allowlists
Container bind-mount sources are constrained separately from Starlark plugin permissions. Relative bind sources must stay inside the app source directory. Absolute bind sources must be inside the app source directory, the app runtime directory, or a directory listed in security.allowed_mounts:
[security]
allowed_mounts = ["$OPENRUN_HOME/mounts", "/srv/openrun/shared"]security.allowed_mounts entries are expanded with environment variables before validation.
Related allowlists in the [security] section:
| Setting | Allows | Default |
|---|---|---|
allowed_container_args | Raw Docker/Podman flags apps may set, see Container Config | |
allowed_sidecar_images | Foreign images sidecars may use | Empty allows any |
allowed_job_images | Foreign images jobs may use | ["*"] |
Development-only Flags
The unsafe_* settings turn off a safety boundary and are meant for development and test setups only. They are static config: none of them can be set through the dynamic config API.
| Setting | Effect |
|---|---|
security.unsafe_disable_rbac | Turns off all RBAC enforcement. Setting it also disables the remote API surfaces. |
security.unsafe_allow_system_plugins_anon | Lets anonymous callers use the privileged system plugins, see System Plugin Access. |
security.unsafe_enable_testurl_rbac | Enables the _cl_perm=<perm> and _cl_role=<role> URL path directives (for example /myapp/_cl_perm=appread/page) on dev mode apps with none auth, to simulate RBAC permissions and roles while developing an app which uses custom permissions. |
security.unsafe_agent_without_sandbox | Runs app builder agents on the host instead of in a container sandbox. |
security.unsafe_enable_remote_disk_read | Accepts disk paths from any caller, see Disk Paths Over The Remote API. |
bindings.unsafe_allow_http | Allows plain http source urls for openrun provider install. |
System Plugin Access
The privileged system plugins perform server-side management operations and are used by the management console app:
openrun_admin: app lifecycle, config, RBAC, secrets, containers, …build: the AI app builder
By default, these plugins require an authenticated (non-anonymous) caller regardless of RBAC status, so a console app accidentally served with none auth cannot be driven by anonymous users to create/delete apps, edit config, or run the builder. The read-only openrun plugin is never gated.
To let anonymous callers use these plugins (for example, a development console running with none auth), set:
[security]
unsafe_allow_system_plugins_anon = trueThis is an unsafe, development-only escape hatch. In production, serve the console with an auth type that requires login and leave this off.
Disk Paths Over The Remote API
An app source, apply file or sync path which is not a git url is a path on the server’s disk, read as the server user. Over the remote management surfaces (the REST API, the MCP endpoint and the console’s in-process openrun_admin calls) that would let any caller with app:create or app:apply fetch any file the server can read, by creating an app from it. So by default, disk paths are accepted over the unix domain socket only:
- On the server:
openrun app create ./myapp /myapp,openrun apply ./apps.star,openrun sync schedule ./apps.starandopenrun apply --pretty-printwork. - Over a remote client (or the console): the same commands are refused with an error saying so. Remote callers deploy from git urls.
- Dev mode and
static_from_diskapps need a disk source, so remotely they can only be created from a git url (dev mode) or on the server. - Only naming a new path is gated. Reloading, promoting or running a sync of an app or sync entry whose disk path was recorded by a caller on the server stays possible from anywhere: the path was chosen by someone with the server’s file access.
- Remote sync entries: a sync entry created remotely keeps that standing for its scheduled runs, so a git hosted apply file it syncs cannot declare disk sources either.
Directories listed in security.remote_disk_read_paths are exempt: paths under them are accepted from any caller.
- Default: the server’s own publish and checkout area,
$OPENRUN_HOME/app_src, where the app builder publishes apps in local mode and dev mode apps created from a git url are checked out. So a console user can create an app from$OPENRUN_HOME/app_src/myappor re-apply$OPENRUN_HOME/app_src/apps.star, while the rest of the disk stays off limits. - Entries are expanded with environment variables, and symlinks are resolved before the check.
- Static config only: a
config:updateholder cannot widen the list.
Set it to [] to exempt nothing:
[security]
remote_disk_read_paths = []To lift the restriction entirely, for example on a trusted single-user host:
[security]
unsafe_enable_remote_disk_read = trueLike every unsafe_ setting this is static config only, not settable through the dynamic config API.
CSRF Protection
CSRF protection is automatically enabled for OpenRun internal APIs and for API calls to apps. This uses the CrossOriginProtection middleware.
- To disable globally for all apps, set
app_config.security.disable_csrf_protection = trueinopenrun.toml. - To disable for one app, run
openrun app update conf --promote 'security.disable_csrf_protection=true' /myapp.
Security Response Headers
OpenRun adds security related HTTP response headers to app responses based on the security.headers_level app config. The level is a value from 0 to 10; only 0, 2, 5 and 10 are implemented, other values round down. The default is 2.
| Level | Headers added |
|---|---|
0 | None. |
2 (default) | X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN and Referrer-Policy: strict-origin-when-cross-origin. |
5 | Level 2 plus X-Frame-Options: DENY, Strict-Transport-Security, Cross-Origin-Opener-Policy: same-origin and X-Permitted-Cross-Domain-Policies: none. |
10 | Level 5 plus a restrictive Content-Security-Policy: default-src 'self', Cross-Origin-Embedder-Policy, Cross-Origin-Resource-Policy and Permissions-Policy. This can break apps which use inline scripts or external resources, so it is opt-in. |
- Each header is only added when the response does not already carry that header, so an app (including a proxied containerized app) can override any of them by setting its own value.
- The exceptions are
X-Frame-Optionsat level 5+ andStrict-Transport-Securityat level 10, which are forced. - The default for all apps can be changed with
app_config.security.headers_levelinopenrun.toml.
Apps that need to be embedded in cross-origin iframes should either set their own X-Frame-Options/Content-Security-Policy headers or lower the level:
openrun app update conf --promote 'security.headers_level=0' /myappCORS
CORS headers are disabled by default for apps. Containerized apps are normally accessed through OpenRun, which performs authentication before proxying the request to the app. With the default config, OpenRun does not add Access-Control-Allow-Origin and does not answer CORS preflight requests before they reach the app.
To allow browser requests from a specific frontend origin, set an app-level CORS origin:
openrun app update conf --promote 'cors.allow_origin="https://frontend.example.com"' /myappTo reflect the request origin as the allowed origin, use:
openrun app update conf --promote 'cors.allow_origin="origin"' /myappFor credentialed browser CORS requests, enable credentials explicitly:
openrun app update conf --promote 'cors.allow_credentials="true"' /myappcors.allow_origin="*". Browsers reject wildcard origins for credentialed CORS, and it can expose authenticated app endpoints too broadly.Trusted Proxies and Client IP Headers
By default, OpenRun does not trust X-Forwarded-For or X-Real-IP headers supplied by the client. The client IP exposed to apps in req.RemoteIP is taken from the direct peer connection unless the peer is explicitly configured as a trusted proxy.
To allow a reverse proxy or load balancer to supply the client IP, set security.trusted_proxies to a list of IP addresses or CIDR ranges:
[security]
trusted_proxies = ["127.0.0.1", "10.0.0.0/8", "192.168.0.0/16"]Behavior:
- If the direct peer is not in
trusted_proxies, OpenRun ignoresX-Forwarded-ForandX-Real-IP. - If the direct peer is trusted, OpenRun uses the rightmost non-trusted address from the
X-Forwarded-Forchain as the client IP. - If
X-Forwarded-Foris not present and the direct peer is trusted, OpenRun falls back toX-Real-IP. - When OpenRun proxies requests to an upstream service, it strips inbound forwarding headers and rebuilds a clean set based on the resolved client IP.
This setting should include only infrastructure that is allowed to rewrite client IP headers, such as your ingress proxy or load balancer.
Private Repository Access
OpenRun can read public GitHub/GitLab repositories automatically. For a private repository, specify the ssh key or personal access token that has access to it. Same for GitLab.
SSH Keys
For SSH key, in the openrun.toml config file, create an entry like:
[git_auth.mykey]
key_file_path = "/Users/myuser/.ssh/id_rsa"
password = "mypassphrase"mykeyis the git auth key name.key_file_pathpoints to the location of a private key file for a user with access to the repository.passwordis the passphrase if any for the file.
Instead of a file path, the key contents can be provided inline with private_key. The value supports {{secret ...}} references, so the key can live in a secrets manager or the embedded secrets store instead of on disk:
[git_auth.mykey]
private_key = '{{secret_from "db" "gitauth_key1"}}'
password = '{{secret_from "db" "gitauth_pass1"}}'When both are set, private_key takes precedence. In the management console, the git auth form’s private key field can store a picked key file into the embedded secrets store with one click.
ssh-keygen -l -f ~/.ssh/id_rsa.pub (on public key) to check if the fingerprint matches the SHA256 fingerprint shown at https://github.com/settings/keys. To verify the passphrase, use ssh-keygen -y -f ~/.ssh/id_rsa (on the private key) and type in the passphrase to check if the passphrase is correct.Personal Access Token
For personal access token, set
[git_auth.mypat]
user_id = "myid"
password = "github_pat_11A7FXXXXXXX"The user_id needs to be set to a non-empty value like the github id even though it is ignored for the auth.
Using a git auth entry:
- When running
app create, add the--git-auth mykeyor--git-auth mypatoption. The private key specified is used for accessing the repository. app reloadautomatically uses the same key as specified during the create.- The default git key, used for
applyandsyncalso, is set in config:
[security]
default_git_auth = "mykey"To change the git auth key for an app, run:
openrun app update git-auth --promote newkey /myappGitLab Groups and Subgroups
GitLab Cloud and on-prem supports group and sub-groups. By default in OpenRun, a git path like gitlab.com/myuser/a/b/c is assumed to be referencing myuser user or org, repo a and folder b/c. If using groups in GitLab, this might be incorrect. Two forward slashes // are required to indicate the end of the repo name:
- If
bis the repo name, reference the above path asgitlab.com/myuser/a/b//c. The repo isa/band the folder isc. - If no folder is present, that is if
cis the repo, specify the path asgitlab.com/myuser/a/b/c//. - Without the
//delimiter, the repo name is assumed to immediately follow the user name.