Skip to main content
Version: 3.1.x

Downloading Opscotch

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

Platform Support​

Opscotch provides platform portability at the runtime layer and deployment convenience through container images.

Native Runtime Binaries​

Opscotch publishes native runtime binaries for:

  • Linux x86_64
  • Linux arm64 (RaspberryPi64 etc)
  • Windows amd64
  • macOS Apple Silicon arm64 (M1/M2/M3 and later)

These binaries define the primary portability contract for the platform, and native binaries on these platforms are fully supported.

Compatibility Matrix​

Platform / ArtifactLinux x86_64Linux arm64Windows amd64macOS Apple Silicon arm64
Native runtime binarySupportedSupportedSupportedSupported
Standard Linux container runtime imageSupportedSupportedSupported via Linux containers (Docker Desktop/WSL2)Supported via Linux containers (Docker Desktop)
OS-native container imageNot targetedNot targetedNot a primary deployment targetNot a macOS container target
Package image (FROM scratch, .oapp only)Supported (content identical)Supported (content identical)Supported via Linux container toolingSupported via Linux container tooling

Container Strategy​

Opscotch standardizes on Linux containers across host operating systems. This is an intentional product strategy focused on consistent operations, ecosystem alignment, and predictable runtime behavior.

What This Means Operationally for Docker Use​

  • Linux container deployment is the default model for production and development.
  • For Docker on Windows hosts, running Linux containers through Docker Desktop / WSL2 is the standard industry operating model.
  • For Docker on macOS Apple Silicon hosts, running Linux arm64 containers through Docker Desktop is the supported container model.
  • Linux amd64 and arm64 container workflows are first-class and operationally straightforward.
  • Windows-native and macOS-native containers are intentionally not primary deployment targets.

Runtime Portability vs Container Packaging​

  • Runtime binaries are the core portability mechanism, and native runtime binaries are fully supported on the published platforms.
  • Container images are deployment convenience artifacts.
  • Convenience and composite images may not be published for every architecture unless customer demand justifies it.
  • Native runtime binaries may support a wider platform set than convenience container artifacts.

Package Image Behavior​

Some Opscotch images are package images that:

  • are built FROM scratch
  • contain only a packaged .oapp artifact
  • include no executables
  • act as architecture-neutral data containers

These images may publish multi-architecture manifests for tooling compatibility, while carrying identical package content across architectures.

Release notes​

Read the release notes for changes to each release.

ZIP File Downloads​

Downloads are available from the Opscotch GitHub releases.

Available Distributions​

Each release includes ZIP distributions for the supported runtime platforms listed above.

ComponentDescription
AgentThe runtime executable
Test RunnerThe test execution tool

Release ZIP names include the operating system and platform identifier. Typical examples are:

  • linux-opscotch-agent-linux-x86_64-<version>.zip
  • linux-opscotch-agent-linux-arm64-<version>.zip
  • windows-opscotch-agent-windows-x86_64-<version>.zip
  • macos-opscotch-agent-macos-arm64-<version>.zip
  • macos-opscotch-testrunner-macos-arm64-<version>.zip

Extract each ZIP to your preferred location. After extraction, review the legal acceptance instructions before starting the runtime. The acceptance process is described on the Opscotch legal site when acceptance is performed.

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

Package images are also published through ghcr.io/opscotch/opscotch-agent. Use the package image tag or digest supplied for the package you are deploying.

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)

Container Scope Notes​

  • Linux-based images are the standard deployment path on all host OSes.
  • On Apple Silicon Macs, Docker Desktop uses the Linux arm64 image variant. This is separate from the native macOS arm64 ZIP runtime.
  • Not every convenience image is guaranteed on every architecture.
  • If you need a specific image/architecture combination for production, treat it as an explicit support requirement.

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.

Install Cosign before running the verification commands below. See the Cosign installation documentation for the current official instructions.

Common install options:

# macOS or Linux with Homebrew
brew install cosign
# Linux with Go installed
go install github.com/sigstore/cosign/v2/cmd/cosign@latest

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

FAQ​

Does Opscotch support Windows?​

Yes. Native Windows amd64 runtime binaries are fully supported. For Docker deployments on Windows hosts, Linux containers via Docker Desktop / WSL2 are the standard operating model and are fully supported.

Is ARM supported?​

Yes. Opscotch publishes native Linux arm64 and macOS Apple Silicon arm64 runtime binaries. Opscotch also supports Linux arm64 container deployment, including Docker Desktop on Apple Silicon Macs.

Does Opscotch support macOS Apple Silicon?​

Yes. Native macOS Apple Silicon arm64 runtime binaries are published for M1/M2/M3 and later Macs. For Docker usage on those Macs, use the standard Linux container images through Docker Desktop; macOS-native container images are not a target.

Is 32-bit supported?​

No. Opscotch does not support 32-bit runtimes or 32-bit container targets. Supported platforms are 64-bit only.

Why use Linux containers on Windows hosts?​

For Docker usage on Windows, Linux containers are standard practice across the ecosystem. Standardizing on Linux containers reduces deployment variance and keeps behavior consistent across Windows and Linux host fleets.

What are architecture-neutral package images?​

Package images are FROM scratch images that contain only .oapp package data and no executables. They may be published as multi-architecture manifests for tooling compatibility, but the package payload is identical across architectures.

Next Steps​

After installation, review: