Running the runtime

This page describes the main ways to start the opscotch runtime.

tip

In the documentation the executable is shown as opscotch-agent, but the binary name may differ in your installation.

In short

For most installs, start the runtime with a bootstrap:

opscotch-agent <bootstrap>

<bootstrap> can be:

• a path to a bootstrap file
• a base64-encoded bootstrap string
• an encrypted bootstrap

Runtime startup inputs

The runtime accepts the bootstrap from either:

• the first positional argument
• the OPSCOTCH_BOOTSTRAP environment variable

Both inputs accept the same bootstrap forms:

• a bootstrap file path
• a base64-encoded bootstrap
• an encrypted bootstrap

If both are present, the positional argument is used.

Encrypted bootstraps are decrypted using OPSCOTCH_BOOTSTRAP_SECRETKEY.

For the encrypted bootstrap format and expected secret value, see Packaging.

Bootstrap input formats

The bootstrap can be provided in these forms:

Mode	Description	Example
file path	Path to a bootstrap file	opscotch-agent /path/to/bootstrap.json
base64 encoded	Base64-encoded bootstrap contents	opscotch-agent dGhpcyBpcyBhIGJvb3RzdHJhcAo=
encrypted bootstrap	An encrypted bootstrap supplied either as a file path or as encoded bootstrap content	opscotch-agent /path/to/encrypted-bootstrap

Starting the runtime from the command line

The simplest way to start the runtime is from a shell.

Bootstrap file:

Linux/macOS

opscotch-agent /path/to/bootstrap.json

Windows

opscotch-agent.exe C:\path\to\bootstrap.json

Base64-encoded bootstrap:

Linux/macOS

opscotch-agent dGhpcyBpcyBhIGJvb3RzdHJhcAo=

Windows

opscotch-agent.exe dGhpcyBpcyBhIGJvb3RzdHJhcAo=

Using OPSCOTCH_BOOTSTRAP instead of a positional argument:

Linux/macOS

OPSCOTCH_BOOTSTRAP=/path/to/bootstrap.json opscotch-agent

Windows

set OPSCOTCH_BOOTSTRAP=C:\path\to\bootstrap.json && opscotch-agent.exe

OPSCOTCH_BOOTSTRAP can also contain a base64-encoded bootstrap or an encrypted bootstrap value.

Encrypted bootstraps

Encrypted bootstraps are decrypted through OPSCOTCH_BOOTSTRAP_SECRETKEY.

Example:

Linux/macOS

OPSCOTCH_BOOTSTRAP_SECRETKEY=<senderPublicKeyHex/decryptPrivateKeyHex> opscotch-agent /path/to/encrypted-bootstrap

Windows

set OPSCOTCH_BOOTSTRAP_SECRETKEY=<senderPublicKeyHex/decryptPrivateKeyHex> && opscotch-agent.exe C:\path\to\encrypted-bootstrap

For details on producing encrypted bootstraps, see Packaging.

Running the runtime in Docker

Opscotch is well suited to running in a container.

Workflow Persistence

When running in a container, make sure any workflow persistence is backed by storage you manage explicitly.

The two main runtime image tags are:

• ghcr.io/opscotch/opscotch-agent:latest for production
• ghcr.io/opscotch/opscotch-agent:latest-dev for non-production

For the full list of published Docker tags and package browsing, see Downloads.

The published runtime image uses these environment variables:

Environment Variable	Default	Description
CONFIG_DIR	/config	Directory used when BOOTSTRAP_FILE is a relative path
BOOTSTRAP_FILE	bootstrap.json	Bootstrap file name to load from CONFIG_DIR, or an absolute path if it starts with /
BOOTSTRAP_B64	empty	Base64-encoded bootstrap contents; takes precedence over BOOTSTRAP_FILE
RESOURCE_DIR	empty	Optional resource path or ;-separated paths forwarded to the runtime
XMX	unset	Optional Java heap size passed as -Xmx
OPSCOTCH_OPTS	empty	Additional runtime arguments such as JVM system properties

Docker defaults

By default the container looks for bootstrap.json in /config.

If you mount a directory containing that file to /config, the runtime will start without extra configuration.

Docker using a mounted config directory

docker run --rm \
  -v "$PWD:/config:ro" \
  ghcr.io/opscotch/opscotch-agent:latest-dev

Docker using a custom bootstrap file name

docker run --rm \
  -v "$PWD:/config:ro" \
  -e BOOTSTRAP_FILE=my-bootstrap.json \
  ghcr.io/opscotch/opscotch-agent:latest-dev

Docker using an absolute bootstrap path

docker run --rm \
  -v "$PWD/secure:/secure:ro" \
  -e BOOTSTRAP_FILE=/secure/bootstrap.json \
  ghcr.io/opscotch/opscotch-agent:latest-dev

Docker using a base64 bootstrap

docker run --rm \
  -e BOOTSTRAP_B64="$(base64 -w0 bootstrap.json)" \
  ghcr.io/opscotch/opscotch-agent:latest-dev

Docker with an encrypted bootstrap

docker run --rm \
  -v "$PWD:/config:ro" \
  -e OPSCOTCH_BOOTSTRAP_SECRETKEY="<senderPublicKeyHex/decryptPrivateKeyHex>" \
  ghcr.io/opscotch/opscotch-agent:latest-dev

This example assumes the encrypted bootstrap is mounted as /config/bootstrap.json.

Building a custom image

If you want to bake your bootstrap and packaged app into your own image:

FROM ghcr.io/opscotch/opscotch-agent:latest

COPY my-opscotch.bootstrap.json /config/bootstrap.json
COPY my-opscotch.app /config/my-opscotch.app