Skip to main content
Version: Next

Downloading Opscotch

Opscotch is distributed as downloadable ZIP files and as Docker images. This page covers installation options, verification, and configuration.

ZIP File Downloads​

Downloads are available from the Opscotch GitHub releases.

Available Distributions​

Each release includes three ZIP files for various operating systems:

ComponentDescription
AgentThe runtime executable
Test RunnerThe test execution tool

Extract each ZIP to your preferred location. After extraction, review the legal acceptance instructions before starting the runtime.

Docker Images​

Opscotch publishes Docker images to GitHub Container Registry.

Available Images​

ImageDescription
ghcr.io/opscotch/opscotch-agentProduction runtime
ghcr.io/opscotch/opscotch-packager-standaloneStandalone packager
ghcr.io/opscotch/opscotch-agent-betaBeta channel images

Image Tags​

The agent image uses these primary tags:

  • latest - Latest production runtime
  • latest-dev - Latest non-production (development) runtime
  • <version> - Specific version (e.g., 3.1.1)
  • <version>-dev - Specific version in development mode (e.g., 3.1.1-dev)

Running Docker​

Basic usage:

docker run ghcr.io/opscotch/opscotch-agent:latest-dev

With local configuration:

docker run -v .:/config ghcr.io/opscotch/opscotch-agent:latest-dev

Custom image with packaged app:

FROM ghcr.io/opscotch/opscotch-agent:latest
COPY my-opscotch.bootstrap.json /config/bootstrap.json
COPY my-opscotch.app /config/my-opscotch.app

Docker Configuration Options​

Environment VariableDefaultDescription
CONFIG_DIR/configWorking directory and config location
BOOTSTRAP_FILE${CONFIG_DIR}/bootstrap.jsonBootstrap file name
BOOTSTRAP_B64(none)Bootstrap as base64 string (takes precedence)
RESOURCE_DIR(none)Resource directories (semicolon-separated)
OPSCOTCH_OPTS(none)Additional CLI arguments

Example with custom paths:

docker run \
  -v ./app-config:/config \
  -v ./resources:/resources \
  -e RESOURCE_DIR=/resources \
  ghcr.io/opscotch/opscotch-agent:latest-dev

Verifying Downloads​

All Opscotch distributions are cryptographically signed using Sigstore and Cosign keyless signing.

Verify ZIP Downloads​

Each ZIP release includes:

  • <artifact>.zip - The distribution
  • <artifact>.zip.sig - Detached signature
  • <artifact>.zip.pem - Signing certificate

Before extracting, verify with Cosign:

cosign verify-blob \
  <artifact>.zip \
  --signature <artifact>.zip.sig \
  --certificate <artifact>.zip.pem \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/opscotch/builder/.github/workflows/release.yml@.*$'

Verify Docker Images​

Docker images should be verified by digest for immutability.

1. Pull and get digest:

docker pull ghcr.io/opscotch/opscotch-agent:latest
docker inspect --format='{{index .RepoDigests 0}}' ghcr.io/opscotch/opscotch-agent:latest

This returns a reference like ghcr.io/opscotch/opscotch-agent@sha256:...

2. Verify the signature:

cosign verify \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/opscotch/builder/.github/workflows/docker-publish.yml@.*$' \
  ghcr.io/opscotch/opscotch-agent@sha256:<digest>

Successful verification confirms the image was signed by the expected Opscotch workflow.

Version Selection for Production​

Recommendation: Pin to Specific Versions​

Using latest or latest-dev in production is not recommended because:

  • No reproducibility - The image can change without notice
  • No rollback - Cannot revert to a known good version if issues arise
  • No audit trail - Cannot determine what version was deployed

Version Scheme​

Opscotch versions follow semantic versioning:

  • <major>.<minor>.<patch> (e.g., 3.1.1)
  • -dev suffix indicates development-mode binaries (text logging, ASCII art, version string includes -dev)

Production Best Practice​

  1. Pin to exact versions in production (e.g., 3.1.1)
  2. Test with the same version in CI before promoting
  3. Use -dev variants for development and testing
  4. Maintain a version inventory of what's deployed where

Next Steps​

After installation, review: