CanyonOS
When to use this skill
Use when deploying, instrumenting, observing, or scaling distributed multi-agent systems written in plain Python, LangChain, or LangGraph using CanyonOS v0.2.2. CanyonOS eliminates manual infrastructure setup by turning standard agent classes into containerized microservice topologies without altering existing source code.
Key scenarios include:
- Non-invasively converting an existing agent repository into a CanyonOS deployment using
prepare.py and .canyon.
- Defining agent adapter contracts, callable
functions, and the primary serving endpoint in workflow_config.yaml.
- Configuring stateful versus stateless replica boundaries, autoscaling rules in
scaling.yaml, and LLM cost caps in llms.yaml.
- Extracting hardcoded LLM system instructions into managed, versioned
prompts.yaml.
- Inspecting runtime health, logs, OpenTelemetry traces, and GPU utilization (
nvidia-smi / --gpus all).
- Running the
canyonos CLI lifecycle (doctor, new-app, validate, deploy, status, test, logs, stop, clean).
Route-outs
- For managing declarative Kubernetes agent CRDs, controller reconcile loops, or gRPC A2A sessions directly, use
kagent.
- For building, hosting, or consuming Model Context Protocol (MCP) servers and tools, use
fastmcp or mcp-builder.
- For authoring in-process LangGraph state graphs or checkpoint persistence without container orchestration, use
langgraph-fundamentals.
- For raw OpenTelemetry collector pipelines or Prometheus scrapers without CanyonOS, use
agent-observability.
- For measuring LLM output quality, hallucinations, or RAG Triad scores, use
trulens or agent-evaluation.
Instructions
1. Offline environment preflight
Before creating directories or invoking container commands, verify the local environment using the offline manifest helper:
python3 "$SKILL_DIR/scripts/preflight.py" --json
To compare an existing CanyonOS source checkout against the pinned 12-file manifest:
python3 "$SKILL_DIR/scripts/preflight.py" --json --repo /absolute/real/path/to/canyonos
The preflight script performs non-executing path discovery for python3, uv, docker, canyonos, and git, strictly validating source bytes without starting daemons or accessing the network.
2. Scaffold or convert an existing Python agent project
Scaffolding a new project
canyonos new-app my-agents
cd my-agents
This generates standard agent classes in agents/ and a central workflow.py.
Converting an existing repository
Run the upstream conversion helper to generate the isolated .canyon configuration directory:
python3 <skill_dir>/prepare.py <import-root> .canyon
- Preserves application code, dependencies, and environment files.
.env remains in the project root; credentials are never committed or copied to .canyon.
- Add required credential keys to
.canyon/.env.example as documentation.
3. Configure workflow, adapters, and entrypoints
Edit .canyon/config/workflow_config.yaml to define the runtime topology:
version: "1.0"
endpoint:
agent: WorkflowAgent
method: run
agents:
WorkflowAgent:
path: agents/workflow.py
class: WorkflowAgent
functions:
- name: run
args:
query: str
return_type: str
replicas: 1
stateful: false
ResearchAgent:
path: agents/researcher.py
class: ResearchAgent
functions:
- name: search
args:
topic: str
return_type: dict
replicas: 2
stateful: false
Record one representative test query in .canyon/config/test_query.txt (raw string, without Markdown fences).
4. Memory, scaling, and LLM cost governance
State Isolation:
- Single-request shared state: Set
stateful: true (routes requests to the same replica while allowing scale).
- Multi-request in-memory state: Set
stateful: true and replicas: 1 (unscalable).
- External database state: Set
stateful: false (freely scalable).
Autoscaling Policy (.canyon/config/scaling.yaml):
ResearchAgent:
min_replicas: 1
max_replicas: 5
cpu_threshold: 75%
LLM Access & Cost Limits (.canyon/config/llms.yaml):
limits:
monthly_budget_usd: 100.00
rate_limit_rpm: 60
Extracted Prompts (.canyon/config/prompts.yaml):
Extract hardcoded system instructions into named templates (<agent>.<function>) so prompts can be updated without rebuilding container images.
5. Static pre-deployment validation
Always run static validation from the application root before attempting any deployment:
canyonos validate
Validation verifies:
- Import graph and entrypoint reachability.
- Dependency compatibility via
uv pip compile.
- Schema alignment between
workflow_config.yaml, scaling.yaml, and prompts.yaml.
Validation exits 0 on success. Do not proceed to deployment if blockers or errors are reported.
6. Approval-gated deployment and testing
Deployment requires explicit user approval because it builds Docker images and spawns container replicas:
# 1. Deploy containers in background
canyonos deploy --serve false
# 2. Check deployment and replica status
canyonos status --json
# 3. Dispatch test query
canyonos test "$(cat .canyon/config/test_query.txt)"
# 4. Tail container logs
canyonos logs --no-follow
7. Observability, GPU monitoring, and cleanup
- Observability: CanyonOS natively captures OpenTelemetry metrics, logs, and traces. To connect an external collector, add an
otel: destination in workflow_config.yaml.
- GPU Acceleration: On hosts with the NVIDIA Container Toolkit, GPU replicas report metrics via
nvidia-smi and request hardware via --gpus all (or nvidia.com/gpu on Kubernetes).
- Cleanup:
canyonos stop: Halts running containers while preserving images and .canyon.
canyonos clean: Completely removes containers, images, and .canyon.
References
- Pinned Source & Manifest: CanyonOS v0.2.2 commit
49e9bd0 with SHA-256 hashes for 12 public source files.
- Upstream Architecture & Recipes: Command lifecycle, runtime contract, GPU metric polling, and Kubernetes deployment guides.
- Evaluation Scenarios: Five authored test scenarios covering conversion, scaling, validation, and routing.
1---2name: canyonos3description: >4 Deploy, observe, and scale multi-agent Python applications without decorators or SDK modifications using CanyonOS (v0.2.2). Use when converting plain Python, LangChain, or LangGraph projects into containerized agent replicas via .canyon and prepare.py; defining workflow topologies, entrypoints, and adapters; configuring state isolation, replicas, and autoscaling in scaling.yaml; managing LLM access and cost caps in llms.yaml; extracting versioned system prompts into prompts.yaml; generating OpenTelemetry metrics and traces; or running canyonos doctor, new-app, validate, deploy, status, test, logs, clean, and stop. Route Kubernetes-only CRD declarative cluster controllers to kagent, MCP application authoring to fastmcp, and LLM evaluation benchmarks to trulens or agent-evaluation.5allowed-tools: Bash Read Grep Glob Write Edit6metadata:7 version: 0.2.28 source: https://skillmd.com/skills/akillness/canyonos9 upstream: https://github.com/CanyonCodeCoreAI/canyonos10 upstream_commit: 49e9bd042735aa88e694c9e1fc5069223ba1982011---1213# CanyonOS1415## When to use this skill1617Use when deploying, instrumenting, observing, or scaling distributed multi-agent systems written in plain Python, LangChain, or LangGraph using CanyonOS v0.2.2. CanyonOS eliminates manual infrastructure setup by turning standard agent classes into containerized microservice topologies without altering existing source code.1819Key scenarios include:20- Non-invasively converting an existing agent repository into a CanyonOS deployment using `prepare.py` and `.canyon`.21- Defining agent adapter contracts, callable `functions`, and the primary serving `endpoint` in `workflow_config.yaml`.22- Configuring stateful versus stateless replica boundaries, autoscaling rules in `scaling.yaml`, and LLM cost caps in `llms.yaml`.23- Extracting hardcoded LLM system instructions into managed, versioned `prompts.yaml`.24- Inspecting runtime health, logs, OpenTelemetry traces, and GPU utilization (`nvidia-smi` / `--gpus all`).25- Running the `canyonos` CLI lifecycle (`doctor`, `new-app`, `validate`, `deploy`, `status`, `test`, `logs`, `stop`, `clean`).2627### Route-outs28- For managing declarative Kubernetes agent CRDs, controller reconcile loops, or gRPC A2A sessions directly, use `kagent`.29- For building, hosting, or consuming Model Context Protocol (MCP) servers and tools, use `fastmcp` or `mcp-builder`.30- For authoring in-process LangGraph state graphs or checkpoint persistence without container orchestration, use `langgraph-fundamentals`.31- For raw OpenTelemetry collector pipelines or Prometheus scrapers without CanyonOS, use `agent-observability`.32- For measuring LLM output quality, hallucinations, or RAG Triad scores, use `trulens` or `agent-evaluation`.3334---3536## Instructions3738### 1. Offline environment preflight3940Before creating directories or invoking container commands, verify the local environment using the offline manifest helper:4142```bash43python3 "$SKILL_DIR/scripts/preflight.py" --json44```4546To compare an existing CanyonOS source checkout against the pinned 12-file manifest:4748```bash49python3 "$SKILL_DIR/scripts/preflight.py" --json --repo /absolute/real/path/to/canyonos50```5152The preflight script performs non-executing path discovery for `python3`, `uv`, `docker`, `canyonos`, and `git`, strictly validating source bytes without starting daemons or accessing the network.5354### 2. Scaffold or convert an existing Python agent project5556#### Scaffolding a new project57```bash58canyonos new-app my-agents59cd my-agents60```61This generates standard agent classes in `agents/` and a central `workflow.py`.6263#### Converting an existing repository64Run the upstream conversion helper to generate the isolated `.canyon` configuration directory:6566```bash67python3 <skill_dir>/prepare.py <import-root> .canyon68```69- Preserves application code, dependencies, and environment files.70- `.env` remains in the project root; credentials are never committed or copied to `.canyon`.71- Add required credential keys to `.canyon/.env.example` as documentation.7273### 3. Configure workflow, adapters, and entrypoints7475Edit `.canyon/config/workflow_config.yaml` to define the runtime topology:7677```yaml78version: "1.0"79endpoint:80 agent: WorkflowAgent81 method: run8283agents:84 WorkflowAgent:85 path: agents/workflow.py86 class: WorkflowAgent87 functions:88 - name: run89 args:90 query: str91 return_type: str92 replicas: 193 stateful: false9495 ResearchAgent:96 path: agents/researcher.py97 class: ResearchAgent98 functions:99 - name: search100 args:101 topic: str102 return_type: dict103 replicas: 2104 stateful: false105```106107Record one representative test query in `.canyon/config/test_query.txt` (raw string, without Markdown fences).108109### 4. Memory, scaling, and LLM cost governance1101111. **State Isolation**:112 - Single-request shared state: Set `stateful: true` (routes requests to the same replica while allowing scale).113 - Multi-request in-memory state: Set `stateful: true` and `replicas: 1` (unscalable).114 - External database state: Set `stateful: false` (freely scalable).1151162. **Autoscaling Policy (`.canyon/config/scaling.yaml`)**:117 ```yaml118 ResearchAgent:119 min_replicas: 1120 max_replicas: 5121 cpu_threshold: 75%122 ```1231243. **LLM Access & Cost Limits (`.canyon/config/llms.yaml`)**:125 ```yaml126 limits:127 monthly_budget_usd: 100.00128 rate_limit_rpm: 60129 ```1301314. **Extracted Prompts (`.canyon/config/prompts.yaml`)**:132 Extract hardcoded system instructions into named templates (`<agent>.<function>`) so prompts can be updated without rebuilding container images.133134### 5. Static pre-deployment validation135136Always run static validation from the application root before attempting any deployment:137138```bash139canyonos validate140```141142Validation verifies:143- Import graph and entrypoint reachability.144- Dependency compatibility via `uv pip compile`.145- Schema alignment between `workflow_config.yaml`, `scaling.yaml`, and `prompts.yaml`.146147Validation exits 0 on success. Do not proceed to deployment if blockers or errors are reported.148149### 6. Approval-gated deployment and testing150151Deployment requires explicit user approval because it builds Docker images and spawns container replicas:152153```bash154# 1. Deploy containers in background155canyonos deploy --serve false156157# 2. Check deployment and replica status158canyonos status --json159160# 3. Dispatch test query161canyonos test "$(cat .canyon/config/test_query.txt)"162163# 4. Tail container logs164canyonos logs --no-follow165```166167### 7. Observability, GPU monitoring, and cleanup168169- **Observability**: CanyonOS natively captures OpenTelemetry metrics, logs, and traces. To connect an external collector, add an `otel:` destination in `workflow_config.yaml`.170- **GPU Acceleration**: On hosts with the NVIDIA Container Toolkit, GPU replicas report metrics via `nvidia-smi` and request hardware via `--gpus all` (or `nvidia.com/gpu` on Kubernetes).171- **Cleanup**:172 - `canyonos stop`: Halts running containers while preserving images and `.canyon`.173 - `canyonos clean`: Completely removes containers, images, and `.canyon`.174175---176177## References178179- [Pinned Source & Manifest](references/source.json): CanyonOS v0.2.2 commit `49e9bd0` with SHA-256 hashes for 12 public source files.180- [Upstream Architecture & Recipes](references/upstream.md): Command lifecycle, runtime contract, GPU metric polling, and Kubernetes deployment guides.181- [Evaluation Scenarios](evals/evals.json): Five authored test scenarios covering conversion, scaling, validation, and routing.