Runtime Operations

---
name: runtime-operations
description: "Run SAM applications, inspect docs/tools, submit tasks through Web
  UI or REST gateways, and use the SAM REST client safely."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# runtime-operations

Use this sub-skill when a user needs to operate an existing Solace Agent Mesh (SAM) project: start configured apps, inspect available runtime docs or built-in tools, submit tasks through the Web UI gateway CLI, diagnose gateway reachability, or integrate through the REST gateway and `sam-rest-client`.

## Route first

- Project creation, `sam init`, `sam add`, GUI scaffolding, generated config layout, model-provider setup, artifact/session defaults: route to `../project-bootstrap/SKILL.md`.
- Workflow YAML schema, node wiring, template resolution, DAG validation, branch/map/loop behavior: route to `../workflow-authoring/SKILL.md`.
- `sam eval`, evaluation configs, suites, local/remote evaluation runs: route to `../evaluation/SKILL.md`.
- Plugin creation, install, catalog, and packaging lifecycle: route to `../plugin-lifecycle/SKILL.md`.

## Safe operating stance

Before running anything, decide whether the user asked for a dry inspection or a live runtime action:

- Dry/help/config checks: CLI `--help`, reading generated project files, `sam tools list --json`, and `scripts/check_gateway.py` are safe by default.
- Live execution: `sam run`, `sam task run`, `sam task send`, `sam-rest-cli`, direct REST `POST /api/v2/tasks`, and browser Web UI use may contact brokers, models, gateways, databases, auth services, and user data. Only do these when the user actually asked to run or submit.
- Gateway inspection must not submit real tasks unless the user explicitly asks for a task invocation. The bundled gateway checker only performs GET probes.

## Reference map

- Running projects and Web UI task CLI: `references/running-and-tasks.md`.
- REST gateway client library and CLI: `references/rest-client.md`.
- Built-in docs and tools command family: `references/tool-and-docs-commands.md`.
- Runtime troubleshooting decision tree: `references/troubleshooting.md`.
- Safe gateway checker: `scripts/check_gateway.py`.

## Quick workflows

1. **Start an existing project**: use `references/running-and-tasks.md#run-an-existing-sam-project`; verify config selection and environment loading before live startup.
2. **Send a task to a running Web UI gateway**: use `references/running-and-tasks.md#send-a-task-to-an-already-running-web-ui-gateway`; check agent discovery and session/file options.
3. **One-shot task run**: use `references/running-and-tasks.md#start-sam-send-one-task-and-stop`; distinguish startup timeout from task timeout.
4. **Inspect a gateway without submitting**: run `python scripts/check_gateway.py --url http://localhost:8000 --expect-agent orchestrator` from any directory.
5. **Use REST programmatic access**: use `references/rest-client.md`; install `sam-rest-client` in a separate environment when dependency pins conflict with the main SAM package.
6. **List built-in tools or serve docs**: use `references/tool-and-docs-commands.md`.

## Provenance note

This sub-skill distills behavior from SAM package docs, CLI command source, task/gateway source, REST client source, and unit/integration tests. It is self-contained for runtime use; future agents should not need the original repository checkout to follow these instructions.