Starting 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 (see Legal Acceptance):

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.

Legal acceptance

Before the runtime can start, Opscotch legal terms must be accepted.

Dev mode acceptance

In dev mode, you can acknowledge legal terms with:

opscotch-agent --accept-legal=yes <bootstrap>

This shortcut is not valid in prod mode.

Prod mode acceptance

In prod mode, you must formally accept the terms by:

Reviewing the current terms at:

• https://www.opscotch.co/legal

That page shows the current:

• legal_version
• current legal archive sha256

It also generates the legal acceptance JSON for you after you enter your full name and organisation, and lets you copy an OPSCOTCH_LEGAL_ACCEPTED=... form for runtime startup.

Supplying legal acceptance on startup

After acceptance has been generated on /legal, provide it to the runtime through:

• OPSCOTCH_LEGAL_ACCEPTED with either the full acceptance blob as raw JSON, the base64 encoded form shown by the website, the older base64-gzipped encoded form, or a path to a file containing the full acceptance JSON

The acceptance blob contains these fields:

• accepted_at
• accepted_by
• accepted_organisation
• legal_version
• legal_version_hash
• legal_zip_hash
• legal_download_url
• hash

Example using OPSCOTCH_LEGAL_ACCEPTED

OPSCOTCH_LEGAL_ACCEPTED='<base64-acceptance-blob>' opscotch-agent /path/to/bootstrap.json

Reusing legal acceptance across startups

If you start the runtime regularly, it is usually more convenient to set OPSCOTCH_LEGAL_ACCEPTED once in your shell environment and reuse it for future CLI and Docker commands.

Linux/macOS example:

export OPSCOTCH_LEGAL_ACCEPTED='<base64-acceptance-blob>'

Then you can start the agnet without explicitly declaring the OPSCOTCH_LEGAL_ACCEPTED:

opscotch-agent /path/to/bootstrap.json

and in docker note: -e OPSCOTCH_LEGAL_ACCEPTED

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

Persist the variable using your normal shell or system environment configuration if you want it available in future sessions.

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
OPSCOTCH_LEGAL_ACCEPTED	empty	Legal acceptance token for runtime startup; may be a raw JSON blob, base64 JSON blob, legacy base64-gzipped blob, or a path to a saved acceptance JSON file
OPSCOTCH_ACCEPT_LEGAL	empty	Dev-only shortcut. Set to yes to pass --accept-legal=yes to the runtime
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 advanced 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.

In production, set OPSCOTCH_LEGAL_ACCEPTED explicitly. Do not rely on OPSCOTCH_OPTS for legal acceptance.

In dev images, you can use either:

• -e OPSCOTCH_ACCEPT_LEGAL=yes
• -e OPSCOTCH_LEGAL_ACCEPTED=...

Docker using a mounted config directory

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

Docker in dev mode using explicit legal acceptance

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

Docker in prod mode using explicit legal acceptance

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

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