Skip to content
📌 OpenRun 1.0 is released, read the announcement
Plugin Catalog

Plugin Catalog

The page lists the available plugins and their API details.

PluginPurpose
store.inDocument store on SQLite or PostgreSQL
container.inContainer config for backend APIs
proxy.inProxy config for API calls
http.inHTTP API calls
exec.inRun host commands
fs.inLocal file system access
openrun.in, openrun_admin.in, build.inOpenRun management APIs

Database Storage

The store.in plugin supports a document store interface for writing data to SQLite or PostgreSQL. See store for details.

Container Config

The container.in plugin supports configuring for using a container for deploying backend APIs. See container for details.

Proxy Config

The proxy.in plugin supports proxying API calls to deploying backend APIs. See proxy for details.

HTTP Plugin

get,head,options,post,put,delete,patch

The http.in plugin supports making HTTP API calls. The APIs available are:

APITypeNotes
getReadHTTP Get request
headReadHTTP Head request
optionsReadHTTP Options request
postWriteHTTP Post request
putWriteHTTP Put request
deleteWriteHTTP Delete request
patchWriteHTTP Patch request

All the APIs support the following parameters:

ParameterTypeRequiredNotes
urlstringyesThe url to send the request to. A url starting with container.URL (from the container.in plugin) is sent to the app’s own container, like http.get(container.URL + "/api/items"); the default server config allows these calls without an explicit permission
paramsdictnoUrl params to send, string values
headersdictnoHTTP headers to send, string values
bodystringnoBody to send
form_bodydictnoForm body to send
form_encodingstringnoThe form encoding to use, application/x-www-form-urlencoded (default) or multipart/form-data
json_bodyobjectnoThe object to send as json encoded body
auth_basictuple(string, string)noHTTP basic auth username and password
auth_signaturedictnoSignature based auth. The dict keys are type (only SL is supported), user (the key id) and api_key; a signed Authorization header (and a date header if not already set) is added to the request
error_on_failboolnoWhether to fail on non-2xx status code, default true
timeoutintnoRequest timeout in seconds, default 300

The response for all APIs (value within plugin_response) contains the following properties:

PropertyTypeNotes
urlstringThe url the response is for
status_codeintThe HTTP status code
headersdictThe output headers, multiple values for a header are joined with ,
encodingstringThe transfer encoding header
body()stringThe response body as a string
json()objectThe response body un-marshalled as a json
  • If the API call fails to go through, the plugin response error property is set.
  • If the API returns a non 2xx status code (1xx and 3xx included), error is set (unless error_on_fail is False). The status_code indicates whether the API succeeded on the server.
  • The response body is read only when body() or json() is called; an unread body is closed at the end of the request.

To make an API call and parse the response as JSON, do

app.star
ret = http.get("http://localhost:9999/test").value.json()

Exec Plugin

run

The exec.in plugin allows running external commands, starting a new process for the specified command. The command runs on the server host as the server user, so two approvals apply: the app’s exec.in permission for the command, and the server’s security.allowed_exec_commands allowlist of executables (empty by default), which is matched on the resolved file. The OpenRun binary itself cannot be run. See host commands. The APIs available are:

APITypeNotes
runRead/WriteRuns the command as a new process

The API supports the following parameters:

ParameterTypeRequiredNotes
pathstringyesThe command to run
argslist of stringsnoArguments to pass to the cmd
envlist of stringsnoThe env to pass to the cmd, in the form key=value. The command gets exactly these variables, never the server’s environment. Each name must be in the server’s security.allowed_exec_env list (empty by default), or the call is refused
process_partialboolnoWhether to process the output when there is a failure
stdout_fileboolnoWhether to send the stdout for the process to a temporary file on disk. Not supported with stream
parsestringnoWhether to parse the stdout. Supported options are json (the whole output is one JSON object, returned as a list with that one dict) and jsonlines (each output line is a JSON object, returned as a list of dicts)
streamboolnoReturn the output as a stream which is read as the response is generated, instead of buffering the full output. The output is delivered in chunks of complete lines as the command produces it (lines of any length), and a non-zero exit ends the stream with an error after the output. Return the response from a route handler to stream it as the HTTP response, or from an action handler in ace.result(stream=...) to show it live in the action UI (see streaming output). Not supported with parse="json"
include_stderrboolno, default TrueWhether to include the stderr output in the command output. If False, stderr is reported only in the error message when the command fails
cwdstringnoThe working directory to run the command in

The default response (when stdout_file is False) for the exec API (value within plugin_response) is a list of strings: the stdout is scanned and split on newlines. For example

app.star
ret = exec.run("ls", ["-l", "/"], process_partial=True).value
for line in ret:
    print(line)
Note: Only first 100MB of the command stdout output is scanned currently, the rest is discarded.

If stdout_file is True, then the plugin output value is the name for the temp file to which the output was written. There is no size limit on this file output. The user is responsible for deleting this file.

FS Plugin

The fs.in allows working with local file system. The metadata for serve_tmp_file is saved in the database configured in the [plugin."fs.in"] section of openrun.toml (db_connection, by default sqlite:$OPENRUN_HOME/metadata/clace_fs.db). The APIs available are

APITypeNotes
absReadReturns the absolute path for given relative path
listReadList files in specified directory
findReadFind files under specified directory matching criteria
serve_tmp_fileReadLoad file metadata to the OpenRun database and make available through API

abs

The abs API supports the following parameter:

ParameterTypeRequiredNotes
pathstringyesThe file path

The response for the API (value within plugin_response) is of type string, the absolute path for given path.

list

The list API supports the following parameters:

ParameterTypeRequiredNotes
pathstringyesThe directory path
recursive_sizeboolno, default falseWhether to include the recursive size of sub-directories
ignore_errorsboolno, default falseWhether to ignore errors when accessing entries

The response for the API is a list of type FileInfo, one entry per directory entry plus a final entry for the directory itself (path as the name, is_dir true) whose size is the total size of the listed entries. The FileInfo struct contains the fields:

FieldTypeNotes
namestringThe file path, the directory path joined with the entry name
sizeintThe file size in bytes, rounded up to 4K. For directories, the recursive size when recursive_size is set
is_dirboolIs it a directory
modeintFile mode info

find

The find API supports the following parameters:

ParameterTypeRequiredNotes
pathstringyesThe directory path
namestringnoThe file name glob pattern to match
limitintno, default 10K, max 100KThe limit on number of entries to return
min_sizeintnoThe minimum file size in bytes to look for
ignore_errorsboolno, default falseWhether to ignore errors when accessing entries

The response for the find API is a list of type FileInfo, same as returned by list (files only, no entry is added for the directory itself). Sub-directories are searched recursively. When more than limit files match, the largest files are kept.

serve_tmp_file

The serve_tmp_file API supports the following parameters:

ParameterTypeRequiredNotes
pathstringyesThe file path to serve
namestringno, default basename of pathThe file name to use (when serving the API)
visibilitystringno, default fs.USERThe API access level for the file: fs.USER serves it to the user who registered it only (anyone, for an app without authentication), fs.APP to anyone who has access to the app. The file is served by the app that registered it
mime_typestringno, default application/octet-streamThe mime type to use when serving the file
expiry_minutesintno, default 60 minutesHow long to keep the file metadata, set to zero for no deletion
single_accessboolno, default TrueWhether to serve the file just once and then automatically delete it

The response for the serve_tmp_file API is a dict with the fields:

FieldTypeNotes
idstringThe id of the metadata entry
urlstringThe url path (without domain) for downloading the file
namestringThe file name

The serve_tmp_file API creates a metadata entry in the OpenRun database. The file can then be served through an API using this entry.

  • Allowed paths: the file has to be under one of the directories listed in the fs.file_access app config setting, by default ["$TEMPDIR", "/tmp"], otherwise the call fails with a file access denied error.
  • Download url: the url returned has the form <app_path>/_openrun_app/file/<id>.
  • Access: by default the file is accessible only to the user who created it. Setting visibility to fs.APP makes the API available to anyone who has access to the app.
  • Deletion: the first download serves the file and automatically deletes it. The file is deleted after 60 minutes in case there is no API access before that. Deleting the metadata entry removes the database entry and also deletes the file from disk.

If the file should not be deleted, do:

ret = fs.serve_tmp_file("/tmp/myfile", single_access=False, expiry_minutes=0)

See number_lines app code:demo for an example of using this API.

System Plugins

Three plugins expose the OpenRun management APIs to apps, for use by the management console and by apps automating server operations. Their functions mirror the openrun CLI commands and the management REST API, with the same arguments (see the openrun <command> --help output for the semantics), and are subject to the caller’s RBAC permissions. openrun_admin.in and build.in require an authenticated (non-anonymous) caller, see system plugin access.

  • openrun.in : read-only server information. list_apps, list_all_apps, get_app, audit_app, list_specs, list_versions, list_version_files, get_version_file, get_version_zip, export_app, export_app_diff, get_permissions, list_audit_events, list_operations, analytics_summary, list_sync, list_jobs, list_job_runs, job_logs, list_actions, get_action, list_action_runs, get_action_run, list_bindings, binding_health, list_services, service_health, replication_status, list_containers, get_container, container_logs, container_logs_stream, container_kubernetes_status, kubernetes_stats, get_rbac_config, list_rbac_permissions, list_api_operations, get_config_entries, get_config_values, list_config_history, get_config_version, list_auths, list_git_auths, server_info and system_plugins_allowed.
  • openrun_admin.in : management operations, listed in the table below. Most write functions accept dry_run=True and, for staged changes, promote (default True).
  • build.in : the AI app builder sessions. list_sessions, get_session, get_messages, session_events, list_files, read_file, get_source_zip, get_publish_config, list_activity, create_session, send_message, cancel_turn, stop_session, resume_session, delete_session, check_publish_path, publish_app, unpublish_app and verify_config.

openrun_admin.in functions by area:

AreaFunctions
Appscreate_app, delete_apps, reload_apps, approve_apps, promote_apps, switch_version, update_params, update_auth, update_bindings, update_mcp
Sync and jobscreate_sync, run_sync, delete_sync, run_job, cancel_job, cancel_action_run
RBACset_rbac_group, delete_rbac_group, set_rbac_role, delete_rbac_role, add_rbac_grant, update_rbac_grant, delete_rbac_grant, publish_rbac_config, discard_rbac_draft
Configset_config_entry, delete_config_entry, set_config_value, delete_config_value, restore_config
Services, bindings and containerscreate_service, delete_service, create_binding, update_binding, delete_binding, start_container, stop_container
Secretscreate_secret, delete_secret, list_secrets, get_secret, rekey_secrets and secret_reveal (see revealing secrets)