PinataCloud · iammatthias · Mar 24, 2026
diff --git a/agents.mdx b/agents.mdx
diff --git a/agents/channels.mdx b/agents/channels.mdx
@@ -0,0 +1,61 @@
+---
+title: "Channels"
+description: "Connect your agent to messaging platforms"
+icon: "comments"
+---
+
+Channels connect your agent to external messaging platforms. Configure during agent creation or from the **Channels** section in your agent's detail page.
+
+| Channel | Status |
+| ------- | ------ |
+| Telegram | Available |
+| Slack | Available |
+| Discord | Available |
+| WhatsApp | Coming Soon |
+
+## Telegram
+
+1. Create a bot through [@BotFather](https://t.me/botfather)
+2. Copy the bot token
+3. Configure in Pinata
+
+| Option | Description |
+| ------ | ----------- |
+| **Bot Token** | Token from BotFather |
+| **DM Policy** | `open` (anyone) or `pairing` (approval required) |
+| **Allow From** | Allowed user IDs |
+
+## Slack
+
+1. Create a Slack App at [api.slack.com/apps](https://api.slack.com/apps)
+2. Enable **Socket Mode**
+3. Generate an **App-Level Token** with `connections:write` scope
+4. Add Bot Token Scopes: `chat:write`, `im:write`, `im:history`, `im:read`, `users:read`, `app_mentions:read`
+5. Install to your workspace
+
+| Option | Description |
+| ------ | ----------- |
+| **Bot Token** | Bot User OAuth Token |
+| **App Token** | App-Level Token |
+
+## Discord
+
+1. Create an application at [discord.com/developers](https://discord.com/developers/applications)
+2. Create a Bot and copy the token
+3. Invite the bot to your server
+
+| Option | Description |
+| ------ | ----------- |
+| **Bot Token** | Discord bot token |
+
+## Managing Channels
+
+Configured channels show an **ENABLED** badge. Click **RECONFIGURE** to update settings.
+
+- Enable/disable channels without removing configuration
+- Token fields are optional when reconfiguring
+- Changes take effect after gateway restart
+
+<Warning>
+  Keep bot tokens secure. Store them as [secrets](/agents/secrets) and never commit to version control.
+</Warning>
diff --git a/agents/overview.mdx b/agents/overview.mdx
@@ -0,0 +1,76 @@
+---
+title: "Overview"
+description: "Deploy hosted OpenClaw agents through Pinata"
+icon: "lobster"
+---
+
+Pinata Agents are hosted [OpenClaw](https://openclaw.org) instances. Each agent runs in an isolated container with its own workspace, skills, and secrets.
+
+<Note>
+  Agents require a paid Pinata plan. [Upgrade here](https://app.pinata.cloud/billing).
+</Note>
+
+## Quick Start
+
+### 1. Add an LLM Provider Key
+
+Your agent needs an LLM provider to run. Add one of these as a [secret](/agents/secrets) first:
+
+- `ANTHROPIC_API_KEY`
+- `OPENAI_API_KEY`
+- `OPENROUTER_API_KEY`
+
+### 2. Create an Agent
+
+Open [agents.pinata.cloud](https://agents.pinata.cloud) and click **Create Agent**.
+
+**Step 1: Identity** — Choose a personality preset (Atlas, Nova, Sage) or create a custom one. Enter a name and optional description.
+
+**Step 2: Workspace** — The default Pinata workspace includes Node.js, Python, and common tools. Optionally add [skills](/agents/skills/overview).
+
+**Step 3: Connect** — Select your LLM provider (shows "Available" when the key exists). Add any additional secrets your agent needs. Optionally configure [channels](/agents/channels).
+
+**Step 4: Deploy** — Click **Deploy Agent**. Once provisioning completes, you're redirected to your agent's detail page.
+
+## Agent Detail Page
+
+The sidebar provides access to all agent features:
+
+| Section | Purpose |
+| ------- | ------- |
+| **Chat** | Conversation interface |
+| **Channels** | Messaging platform connections |
+| **Snapshots** | Workspace versions and git access |
+| **Skills** | Attached skill packages |
+| **Secrets** | Environment variables |
+| **Routes** | Port forwarding and domains |
+| **Tasks** | Scheduled jobs |
+
+**Dev Tools:** Console (terminal access), Logs, and Danger (delete agent).
+
+### Git Access
+
+Clone and edit your agent's workspace directly:
+
+```bash
+git clone https://agents.pinata.cloud/v0/agents/{agentId}/git {name}
+```
+
+Click **Copy with Token** in the Snapshots section to include authentication.
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="Routes" icon="network-wired" href="/agents/routes">
+    Expose services to the internet
+  </Card>
+  <Card title="Channels" icon="comments" href="/agents/channels">
+    Connect messaging platforms
+  </Card>
+  <Card title="Skills" icon="wand-magic-sparkles" href="/agents/skills/overview">
+    Extend agent capabilities
+  </Card>
+  <Card title="Secrets" icon="key" href="/agents/secrets">
+    Manage credentials
+  </Card>
+</CardGroup>
diff --git a/agents/routes.mdx b/agents/routes.mdx
@@ -0,0 +1,92 @@
+---
+title: "Routes"
+description: "Expose agent services to the internet"
+icon: "network-wired"
+---
+
+Routes expose services running inside your agent container to the internet. Open the **Routes** section from your agent's detail page.
+
+Click **ADD** to create a new route:
+
+| Option | Description |
+| ------ | ----------- |
+| **Path Route** | Map a URL path prefix to a container port |
+| **Custom Domain** | Route a hostname to a container port |
+
+## Path Routes
+
+Path routes forward traffic from a URL path to an internal port. The path prefix is stripped before reaching your service.
+
+Example: A request to `/app/api/users` with path prefix `/app` arrives at your service as `/api/users`.
+
+### Adding a Path Route
+
+| Field | Description |
+| ----- | ----------- |
+| **Path Prefix** | URL path (e.g., `/app`) |
+| **Port** | Container port (1025–65535) |
+| **Protected** | Require gateway token authentication |
+
+### Path Format
+
+- Must start with `/`
+- Letters, numbers, hyphens, underscores only
+- Cannot overlap with reserved paths (`/v0`, `/chat`, `/config`)
+
+## Custom Domains
+
+<Note>
+  Custom Domains is currently in beta.
+</Note>
+
+Custom domains route traffic from a dedicated hostname to a container port. Unlike path routes, the full request path is forwarded as-is.
+
+### Pinata Subdomains
+
+Get a random platform-assigned subdomain on `*.apps.pinata.cloud`.
+
+| Field | Description |
+| ----- | ----------- |
+| **Port** | Container port (1025–65535) |
+| **Protected** | Require gateway token authentication |
+
+Result: `https://swift-fox-347.apps.pinata.cloud` → your port
+
+### Bring Your Own Domain
+
+Use your own domain (e.g., `app.example.com`).
+
+| Field | Description |
+| ----- | ----------- |
+| **Domain** | Your domain |
+| **Port** | Container port |
+| **Protected** | Require gateway token authentication |
+
+#### DNS Setup
+
+After registering, configure these DNS records:
+
+1. **TXT record** — Verify domain ownership
+2. **CNAME record** — Point to the Pinata proxy
+
+Domain status progresses: `pending` → `pending_ssl` → `active`
+
+## Public vs Protected
+
+| Mode | Behavior |
+| ---- | -------- |
+| **Protected** | Requests require a gateway token |
+| **Public** | Open to the internet |
+
+<Warning>
+  Public routes expose your service without authentication. Only use for services that handle their own auth.
+</Warning>
+
+## Constraints
+
+| Limit | Value |
+| ----- | ----- |
+| Path routes per agent | 10 |
+| Custom domains per agent | 5 |
+| Port range | 1025–65535 |
+| Reserved port | 18789 (gateway) |