​

Integrations

​

The Integration Inversion

​

How Integrations Work

1. Author creates a pawz-skill.toml manifest declaring what the integration does, what credentials it needs, and how the agent should use it
2. Install via PawzHub (in-app browser) or manually into ~/.paw/skills/{id}/
3. Configure credentials in the Skills tab — Pawz generates the input form automatically from the manifest
4. Assign to agents — open the Agents tab, select an agent, and enable the integration in their Skills sub-tab
5. Use — the agent receives decrypted credentials and instructions in its system prompt, then calls APIs via fetch or CLI tools via exec

​

The Manifest Format

[skill]
id = "notion"
name = "Notion"
version = "1.0.0"
author = "yourname"
category = "productivity"
icon = "edit_note"
description = "Read and write Notion pages, databases, and blocks via the API"
install_hint = "Get your API key at https://www.notion.so/my-integrations"

[[credentials]]
key = "NOTION_API_KEY"
label = "Integration Token"
description = "Your Notion internal integration token"
required = true
placeholder = "secret_..."

[instructions]
text = """
You have access to the Notion API via the user's integration token.

## Reading pages
Use `fetch` with:
- URL: `https://api.notion.so/v1/pages/{page_id}`
- Headers: `Authorization: Bearer {NOTION_API_KEY}`, `Notion-Version: 2022-06-28`

## Searching
Use `fetch` with POST to `https://api.notion.so/v1/search`
Body: {"query": "search term"}
"""

[widget]
type = "table"
title = "Recent Pages"
refresh = "10m"

[[widget.fields]]
key = "title"
label = "Page"
type = "text"

[[widget.fields]]
key = "updated"
label = "Last Updated"
type = "datetime"

[[widget.fields]]
key = "status"
label = "Status"
type = "badge"

​

Manifest Fields

​

[skill] — Required

​

[[credentials]] — Optional, repeatable

​

[instructions] — Required

Credentials (use these values directly — do NOT ask the user for them):
- NOTION_API_KEY = secret_abc123...

​

[widget] — Optional

​

Widget Types

​

Status

[widget]
type = "status"
title = "Server Status"

[[widget.fields]]
key = "status"
label = "State"
type = "badge"

[[widget.fields]]
key = "uptime"
label = "Uptime"
type = "percentage"

​

Metric

[widget]
type = "metric"
title = "Monthly Revenue"

[[widget.fields]]
key = "value"
label = "MRR"
type = "currency"

[[widget.fields]]
key = "change"
label = "vs Last Month"
type = "percentage"

​

Table

[widget]
type = "table"
title = "Active Issues"

[[widget.fields]]
key = "title"
label = "Issue"
type = "text"

[[widget.fields]]
key = "priority"
label = "Priority"
type = "badge"

​

Log

[widget]
type = "log"
title = "Recent Incidents"

[[widget.fields]]
key = "message"
label = "Event"
type = "text"

[[widget.fields]]
key = "severity"
label = "Level"
type = "badge"

​

Key-Value (KV)

[widget]
type = "kv"
title = "Project Stats"

[[widget.fields]]
key = "total_records"
label = "Records"
type = "number"

[[widget.fields]]
key = "storage_used"
label = "Storage"
type = "text"

​

Field Types

​

Built-in Integrations

​

Per-Agent Scoping

• A Marketing Agent might have Notion, SendGrid, and X/Twitter integrations enabled
• A DevOps Agent might have GitHub, Vercel, and Cloudflare enabled
• A Trading Agent might have Coinbase and DEX Trading enabled

​

Assigning integrations to agents

1. Open the Agents tab in the sidebar
2. Select an agent (e.g. your Marketing Agent)
3. Go to the agent’s Skills sub-tab
4. Enable or disable individual skills and integrations for that agent
5. Only enabled items are injected into that agent’s prompt

​

Installing Integrations

​

From PawzHub (In-App)

1. Open the Skills tab in the sidebar
2. Search or browse the PawzHub catalog
3. Click Install on any integration (look for the 🟣 purple badge)
4. Configure credentials in the auto-generated form
5. Assign to agents via Agents → [agent] → Skills

​

Manual Install

~/.paw/skills/{skill-id}/pawz-skill.toml

~/.paw/skills/notion/pawz-skill.toml
~/.paw/skills/linear/pawz-skill.toml
~/.paw/skills/stripe/pawz-skill.toml

​

Uninstalling

​

Creating Integrations

​

In-App Wizard

1. Basic Info — name, category, icon, description
2. Credentials — add API key fields with labels and placeholders
3. Instructions — write or paste agent instructions (templates available for REST APIs, CLI tools, and web scrapers)
4. Widget — optionally declare dashboard output
5. Test — enable the integration and verify it works with a live agent
6. Publish — save locally, export TOML, or publish directly to PawzHub

​

AI-Assisted Creation

“Create an integration for the Linear API”

​

Template Starters

• REST API — fetch calls with auth headers, JSON parsing
• CLI Tool — exec commands with flag reference and binary detection
• Web Scraper — fetch + HTML parsing instructions

​

Publishing to PawzHub

1. Fork the OpenPawz/pawzhub repository
2. Create skills/{your-skill-id}/pawz-skill.toml
3. Open a Pull Request — CI validates your manifest automatically
4. Maintainer reviews and merges
5. Your integration appears in the in-app PawzHub browser

​

CI Validation

​

Security

​

What integrations can do

• Inject instructions into the agent’s system prompt
• Declare credential fields (encrypted by the engine)
• Declare widget schemas (rendered by the app)

​

What integrations cannot do

• Execute arbitrary Rust code
• Bypass domain allowlist/blocklist
• Access the OS keychain directly
• Read engine source code
• Install blocked packages
• Run unsandboxed commands when Docker sandbox is enabled

​

Runtime protections

​

Readiness Check