Skip to main content

Add an agent template

1claw spawn loads framework-specific agents from the public 1clawAI/agent-templates repository. Anyone can submit a new template or improve an existing one via pull request.

This guide walks through creating a template that passes CI and shows up in 1claw spawn --list.

Prerequisites​

  • A GitHub account
  • Docker installed locally
  • Familiarity with the target framework (LangChain, Mastra, etc.)
  • Optional: @1claw/cli installed to test 1claw spawn end-to-end

How templates are distributed​

GitHub (agent-templates)  →  1claw spawn --refresh  →  ~/.config/1claw/templates/
                         ↘  bundled in @1claw/cli npm package (on release)

After your PR merges to main, users can fetch it with:

1claw spawn --refresh
1claw spawn your-template --agent-key ocv_YOUR_KEY

Step 1 — Fork and clone​

  1. Fork github.com/1clawAI/agent-templates.
  2. Clone your fork:
git clone https://github.com/YOUR_USER/agent-templates.git
cd agent-templates

If you work inside the 1Claw monorepo, the same repo lives at packages/agent-templates (git submodule). Initialize it with:

git submodule update --init packages/agent-templates

Step 2 — Pick a starting point​

LanguageCopy from
Pythontemplates/langchain/ or templates/crewai/
TypeScripttemplates/typescript-sdk/ or templates/mastra/

Create a new directory:

cp -R templates/langchain templates/my-framework
# edit files — do not leave "langchain" identifiers in template.yaml

Naming rules:

  • Directory name: lowercase, hyphens only (pydantic-ai, my-agent)
  • Must match name in template.yaml exactly
  • Must be unique (not already in registry.yaml)

Step 3 — Required files​

Every template directory needs:

FilePurpose
template.yamlManifest — name, language, Docker settings
DockerfileBuilds the agent image
entrypoint.shStarts MCP + agent; wires Shroud LLM routing
Starter codeagent.py (Python) or agent.ts (Node)
README.mdNotes for users of this template
requirements.txtPython dependencies (Python only)
package.jsonNode dependencies (TypeScript only)

template.yaml example​

name: my-framework              # must match directory name
display_name: "My Framework"
version: 1.0.0
description: "Short line shown in 1claw spawn --list"
author: Your Name or Org
language: python                # python | node
homepage: https://example.com

docker:
  base_image: python:3.12-slim
  context_files:
    - Dockerfile
    - requirements.txt
    - agent.py
    - entrypoint.sh
  env:
    ONECLAW_FRAMEWORK: my-framework
  health_endpoint: /health
  health_port: 3000

post_spawn_message: |
  Edit agent.py to customize your agent.

Step 4 — Security requirements​

Templates must follow the same model as 1claw init --docker:

  1. No secrets in the image. Do not ENV API keys or copy credential files.
  2. Daemon socket. The host mounts /run/1claw/daemon.sock; the entrypoint uses ONECLAW_DAEMON_SOCKET for MCP and credential injection.
  3. Shroud for LLM. When ONECLAW_LLM_VIA_SHROUD=true, set OPENAI_BASE_URL (or equivalent) to ${ONECLAW_SHROUD_URL}/v1 so the container never holds provider keys.
  4. Health check. Implement GET /health returning JSON (see existing templates).

CI rejects files containing patterns like sk-…, ocv_…, 1ck_…, or plt_….

Step 5 — Register in registry.yaml​

Add an entry at the repo root:

  - name: my-framework
    display_name: "My Framework"
    version: 1.0.0
    language: python
    description: "One-line description for the template catalog"

The name must match your directory under templates/. Without this entry, CI fails.

Step 6 — Test locally​

Docker smoke test​

cd templates/my-framework
docker build -t test-my-framework .
docker run --rm -p 3000:3000 test-my-framework
curl http://localhost:3000/health

CLI integration test (optional)​

From a machine with Docker and a 1Claw agent key:

1claw spawn my-framework --agent-key ocv_YOUR_KEY --llm-api-key sk-...
# open http://localhost:3000

When developing in the monorepo, build the CLI so it bundles templates from packages/agent-templates:

cd packages/cli && npm run build

Step 7 — Open a pull request​

  1. Commit on a feature branch:
git checkout -b add-my-framework-template
git add templates/my-framework registry.yaml
git commit -m "feat: add my-framework spawn template"
git push origin add-my-framework-template

  1. Open a PR against 1clawAI/agent-templates main.

  2. Wait for CI:

    • Manifest validation (template.yaml fields, registry listing, no secrets)
    • Docker build smoke test (currently langchain, crewai, openai-agents; expand matrix in a follow-up PR if needed)

  3. A maintainer will review and merge. After merge, the template is available via 1claw spawn --refresh.

Entrypoint pattern​

Use the same shell pattern as existing templates:

#!/bin/sh
set -e

DAEMON_SOCKET="${ONECLAW_DAEMON_SOCKET:-/run/1claw/daemon.sock}"

if [ "$ONECLAW_LLM_VIA_SHROUD" = "true" ]; then
    export OPENAI_BASE_URL="${ONECLAW_SHROUD_URL}/v1"
fi

if [ -S "$DAEMON_SOCKET" ] && command -v 1claw-mcp >/dev/null 2>&1; then
    ONECLAW_LOCAL_VAULT=true ONECLAW_DAEMON_SOCKET="$DAEMON_SOCKET" \
        1claw-mcp --local 2>/tmp/mcp.log &
fi

exec python agent.py   # or: npx tsx agent.ts

See CONTRIBUTING.md in the template repo for Dockerfile details and the full manifest schema.

Templates vs CLI modules​

Templates (spawn)Modules (init --module)
WhatFull project (Dockerfile + starter code)Extra packages layered on base image
Command1claw spawn langchain1claw init --docker --module=onchain
Repoagent-templatesBundled in @1claw/cli
Use whenStarting a new framework agentAdding capabilities to an existing agent