Skip to main content
Version: Next

Opscotch Operations Skill

Operations-focused guidance for engineers and operators who need to start, run, or execute common Opscotch runtime components.

This skill complements docs/docs/llm/opscotch-llm-skill.md and docs/docs/llm/opscotch-architect-skill.md. Use this file for runbook-style questions such as how to start the runtime, run the packager, launch the test harness, or run resource unit tests.

Scope And Boundary​

Use this skill to:

  • identify the right executable or container image
  • state the minimum documented startup command
  • name the required files, mounts, environment variables, and working-directory assumptions
  • explain the next step after startup when startup alone is not enough

Do not use this skill to:

  • write the full implementation design
  • make architectural suitability decisions in detail
  • restate the complete API reference corpus
  • invent installer steps, flags, process managers, or orchestration wrappers

When answering an operations question:

  1. Determine whether the user wants Docker or non-Docker instructions.
  2. Give the shortest documented path that matches that preference.
  3. Separate prerequisites, command, and follow-up steps.
  4. State any documented caveat or unspecified detail explicitly.

Primary provenance:

  • docs/src/llm/processed/administrating/agent.md -> https://docs.opscotch.co/docs/current/administrating/agent
  • docs/src/llm/processed/administrating/packaging.md -> https://docs.opscotch.co/docs/current/administrating/packaging
  • docs/src/llm/processed/administrating/testing.md -> https://docs.opscotch.co/docs/current/administrating/testing
  • docs/src/llm/processed/administrating/downloads.md -> https://docs.opscotch.co/docs/current/administrating/downloads
  • docs/src/llm/operations/context/prompt-imperatives.md
  • docs/src/llm/operations/context/processing-rules.md

Canonical MCP Use​

The canonical Opscotch Coder MCP endpoint is:

https://mcp.opscotch.ai/mcp

When MCP is available:

  • call get_guidance(role=system) first
  • call get_guidance(role=engineer) before drafting detailed operational instructions
  • read the MCP resource list and tool list before making MCP-derived claims
  • use MCP validation tools before claiming a schema-governed example is valid
  • use resolve_operational_context, list_context, get_context, and get_context_function before asserting processor-context behavior

Primary provenance:

  • docs/docs/llm/opscotch-llm-skill.md -> https://docs.opscotch.co/docs/current/llm/opscotch-llm-skill
  • docs/docs/llm/opscotch-architect-skill.md -> https://docs.opscotch.co/docs/current/llm/opscotch-architect-skill
  • docs/src/llm/operations/context/prompt-imperatives.md

Non-Negotiable Rules​

  • Do not invent commands, flags, file paths, startup defaults, or service wrappers.
  • Do not assume undocumented systemd, Homebrew services, Kubernetes procedures, or shell wrappers.
  • Do not turn schema validity into a claim that runtime behavior is proven.
  • If the docs do not define a startup detail, say it is unspecified.
  • Prefer documented working-directory rules over guessed relative-path behavior.
  • Prefer concrete command sequences over generic summaries.
  • Keep internal processing mechanics out of public guidance.

Primary provenance:

  • docs/src/llm/processed/administrating/agent.md -> https://docs.opscotch.co/docs/current/administrating/agent
  • docs/src/llm/processed/administrating/packaging.md -> https://docs.opscotch.co/docs/current/administrating/packaging
  • docs/src/llm/processed/administrating/testing.md -> https://docs.opscotch.co/docs/current/administrating/testing
  • docs/src/llm/operations/context/processing-rules.md
  • docs/src/llm/operations/context/prompt-imperatives.md

Runtime Startup​

Answer pattern:

  • first ask whether the user wants CLI startup or Docker startup
  • then give the matching documented path

Start the runtime from the executable​

Documented executable names:

  • Linux or macOS: opscotch-agent
  • Windows: opscotch-agent.exe

Required inputs:

  • a bootstrap supplied either as the first positional argument or through OPSCOTCH_BOOTSTRAP
  • legal acceptance through OPSCOTCH_LEGAL_ACCEPTED, unless the documented dev-only shortcut is acceptable
  • OPSCOTCH_BOOTSTRAP_SECRETKEY when the bootstrap is encrypted

Accepted bootstrap forms:

  • bootstrap file path
  • base64-encoded bootstrap string
  • encrypted bootstrap

Minimum documented commands:

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

Encrypted bootstrap example:

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

Documented follow-up and caveats:

  • if both the positional bootstrap argument and OPSCOTCH_BOOTSTRAP are present, the positional argument wins
  • --accept-legal=yes is documented only as a dev-mode shortcut
  • the docs do not define a discovery procedure when the installed executable name differs from opscotch-agent
  • the docs distinguish dev mode from prod mode but do not fully define how mode is determined for direct executable startup

Start the runtime in Docker​

Documented image:

  • ghcr.io/opscotch/opscotch-agent

Documented tag patterns:

  • latest
  • latest-dev
  • exact versions such as 3.1.1
  • exact dev versions such as 3.1.1-dev

Documented container environment variables:

  • CONFIG_DIR
  • BOOTSTRAP_FILE
  • BOOTSTRAP_B64
  • OPSCOTCH_LEGAL_ACCEPTED
  • OPSCOTCH_ACCEPT_LEGAL
  • RESOURCE_DIR
  • XMX
  • OPSCOTCH_OPTS

Documented defaults and behavior:

  • CONFIG_DIR defaults to /config
  • BOOTSTRAP_FILE defaults to bootstrap.json
  • the container looks for that file in /config
  • BOOTSTRAP_B64 takes precedence over BOOTSTRAP_FILE
  • RESOURCE_DIR can contain one path or ;-separated paths
  • OPSCOTCH_ACCEPT_LEGAL=yes is the documented dev-image legal shortcut

Minimum documented dev-container command:

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

Dev-container command with explicit legal shortcut:

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

Resource directory example:

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

Production guidance and caveats:

  • in production, provide OPSCOTCH_LEGAL_ACCEPTED explicitly
  • do not use OPSCOTCH_OPTS as the legal-acceptance mechanism
  • prefer exact version tags in production instead of latest or latest-dev
  • when persistence matters, back containerized workflow persistence with operator-managed storage

Primary provenance:

  • docs/src/llm/processed/administrating/agent.md -> https://docs.opscotch.co/docs/current/administrating/agent
  • docs/src/llm/processed/administrating/downloads.md -> https://docs.opscotch.co/docs/current/administrating/downloads

Packager Startup​

The packager is documented as an HTTP API surface, not as a CLI packaging flow.

Supported runtime surfaces described by the docs:

  • the standalone image ghcr.io/opscotch/opscotch-packager-standalone:latest
  • the packager application running inside an Opscotch runtime

Use the standalone image when the user asks how to start the packager, because it is the most concrete documented startup path.

Required prerequisites:

  • legal acceptance before starting the Docker image
  • resource directories mounted or otherwise exposed when packaging references resource files
  • appropriate keys when signing or encrypting packages

Documented standalone startup command:

docker run \
    -e OPSCOTCH_LEGAL_ACCEPTED \
    -v "/local/opscotch-community/resources:/opscotch-community-resources" \
    -v "/local-app-resources:/local-resources1" \
    -p "39575:39575" \
    ghcr.io/opscotch/opscotch-packager-standalone:latest

Next step after startup:

  • use HTTP API calls against the packager

Documented packaging example:

curl "localhost:39575/workflow-package" \
    -H "Accept: application/octet-stream" \
    -F 'body={ "packageId": "my-package" }' \
    -F 'stream=@my-app.config.json;type=application/octet-stream' \
    -v --output my.oapp

Other documented operational endpoints:

  • /workflow-inspect
  • /workflow-compile
  • /workflow-hash
  • /package-envelope
  • bootstrap-encryption and host-string-encryption endpoints
  • /build-workflows

Operational caveats:

  • the docs say the packager can run inside an Opscotch runtime, but they do not give an equally concrete startup command for that path
  • packaging security is not one thing; the docs distinguish runtime-internal default package encryption from explicit authenticated encryption
  • if the user needs strong cryptographic assurance, do not answer with the minimal quickstart alone
  • resource lookup order matters during packaging and stops at the first matching mapped directory

Primary provenance:

  • docs/src/llm/processed/administrating/packaging.md -> https://docs.opscotch.co/docs/current/administrating/packaging
  • docs/src/llm/processed/administrating/downloads.md -> https://docs.opscotch.co/docs/current/administrating/downloads

Test Harness Startup​

Local harness plus runtime​

Documented executable names:

  • Linux or macOS: opscotch-testrunner
  • Windows: opscotch-testrunner.exe

Required inputs:

  • a testrunner.config.json
  • a license file referenced by that config
  • resource directories
  • test directories

Minimum documented config:

{
  "license": "license.txt",
  "resourceDirs": ["resources"],
  "testDirs": ["tests"]
}

Documented startup commands:

opscotch-testrunner testrunner.config.json
opscotch-testrunner.exe testrunner.jar testrunner.config.json

Required follow-up sequence:

  1. Start opscotch-testrunner.
  2. Wait for it to print Start the opscotch agent with this argument: <your working directory>/test.bootstrap.json.
  3. Start the runtime with that generated bootstrap path.
  4. Let the runtime execute while the harness observes requests, metrics, and logs.

Documented runtime follow-up command:

opscotch-agent <your working directory>/test.bootstrap.json

Working-directory rule:

  • resourceDirs and testDirs are resolved relative to the working directory where opscotch-testrunner is started
  • they are not resolved relative to the config-file path or the executable path

Recommended local environment pattern:

  • clone the Opscotch community repository
  • place license.txt in the community root
  • start opscotch-testrunner from the directory that should resolve resources and tests
  • set OPSCOTCH_COMMUNITY_ROOT
  • in another terminal, set OPSCOTCH_COMMUNITY_ROOT for the runtime and start opscotch-agent with the printed bootstrap path

Operational caveats:

  • the docs do not define the exact lifecycle mapping from a .test.json definition to the generated runtime artifacts in detail
  • the docs do not define execution ordering, recursion, concurrency, or stop-on-failure behavior for multiple discovered tests
  • the Windows-only testrunner.jar argument is shown but not explained

Single-container integration test​

Use this when the user wants one documented containerized integration-test path.

Required inputs:

  • OPSCOTCH_LEGAL_ACCEPTED
  • a mounted /license/license.txt
  • a mounted /tests
  • TEST_PATH

Documented command:

docker run --rm \
  -e OPSCOTCH_LEGAL_ACCEPTED \
  -e TEST_PATH=/tests/general/httpserver.test.json \
  -v /path/to/tests:/tests:ro \
  -v /path/to/license.txt:/license/license.txt:ro \
  ghcr.io/opscotch/opscotch-testrunner-single:latest

Optional mounts documented by the page:

  • /local-resources1
  • /local-resources2

Rules and caveats:

  • this container runs one test only
  • preserve the fromDirectory structure under /tests
  • the container waits for the generated bootstrap and exits with the test runner status code

Log triage pattern for opscotch-testrunner-single​

If the user asks how to inspect failures efficiently, use the documented summary-first flow:

docker run --rm \
  -e OPSCOTCH_LEGAL_ACCEPTED \
  -e TEST_PATH=/tests/general/httpserver.test.json \
  -v /path/to/tests:/tests:ro \
  -v /path/to/license.txt:/license/license.txt:ro \
  ghcr.io/opscotch/opscotch-testrunner-single:latest \
  > testrunner-single.log 2>&1

Then inspect the summary before the full trace:

grep -q "1 succeeded" testrunner-single.log && echo "success"
grep -q "1 failed" testrunner-single.log && echo "failure"

Primary provenance:

  • docs/src/llm/processed/administrating/testing.md -> https://docs.opscotch.co/docs/current/administrating/testing

Resource Unit Test Startup​

Use opscotch-resource-testkit for JavaScript resource unit tests, not full workflow integration tests.

Run unit tests in the published container​

Required input:

  • a repository mounted at /workspace

Documented command:

docker run --rm -v /path/to/opscotch-community:/workspace:ro ghcr.io/opscotch/opscotch-resource-testkit:latest

Documented default behavior:

  • runs tests from /workspace/unit-tests

Documented narrowing options:

  • set UNIT_TEST_PATH=/workspace/unit-tests/general/standard-clear-body.test.ts for a single file
  • set UNIT_TEST_PATH=/workspace/unit-tests/general for a folder
  • pass Vitest arguments after the image name, for example --testNamePattern="clears the current body"

Run unit tests locally with npm​

Documented commands:

cd /path/to/opscotch-community/unit-tests
npm install
npm test

Single-file example:

cd /path/to/opscotch-community/unit-tests
npx vitest run general/standard-clear-body.test.ts

Folder example:

cd /path/to/opscotch-community/unit-tests
npx vitest run httpserver

Operational caveat:

  • the docs name both the container image and the npm package route, but they do not explain release-line alignment between them

Primary provenance:

  • docs/src/llm/processed/administrating/testing.md -> https://docs.opscotch.co/docs/current/administrating/testing

Operational Answer Patterns And Caveats​

When the docs are thin:

  • answer with the most concrete documented path
  • identify what is explicitly required
  • state what is left unspecified instead of filling the gap

Preferred defaults for common questions:

  • "How do I start the runtime?" Answer with CLI or Docker based on user preference; otherwise ask which they want.
  • "How do I start the packager?" Answer with the standalone Docker image unless the user explicitly asks about embedding it in a runtime.
  • "How do I run tests?" Distinguish between local harness plus runtime, single-container integration test, and resource unit tests.
  • "How do I run one unit test?" Use either UNIT_TEST_PATH in the container or npx vitest run <path> in the local unit-tests directory.

Never imply these are documented when they are not:

  • executable-name discovery when the installed runtime binary differs from opscotch-agent
  • direct startup steps for the embedded-runtime packager path
  • recursive discovery, ordering, or parallelism semantics for multiple .test.json files
  • the exact meaning of the Windows testrunner.jar argument

Primary provenance:

  • docs/src/llm/processed/administrating/agent.md -> https://docs.opscotch.co/docs/current/administrating/agent
  • docs/src/llm/processed/administrating/packaging.md -> https://docs.opscotch.co/docs/current/administrating/packaging
  • docs/src/llm/processed/administrating/testing.md -> https://docs.opscotch.co/docs/current/administrating/testing