> ## Documentation Index > Fetch the complete documentation index at: https://docs.pinata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Concepts > Terms, file layout, and how the pieces fit together The agent platform has a handful of moving parts, and they don't always have obvious names. This page is your reference: every term, every standard file path, every reserved port. Skim it now to get the lay of the land; come back later when something in the docs reads like jargon. ## The shape of things ```text theme={null} Workspace (your team) ──► Agent (container) ──► Channels / Routes / Tasks │ │ │ ├─ Skills (capabilities) │ ├─ Secrets (env vars) │ ├─ Models (LLMs it can call) │ └─ Workspace files + snapshots ▼ Pinata IPFS + R2 (storage) ``` A **workspace** is a Pinata team. Inside it you create one or more **agents** — each is an isolated container running an agent engine, with its own files, gateway, and per-agent subdomain. ## Glossary ### Agent A single isolated container with a persistent workspace, gateway, and `{agentId}.agents.pinata.cloud` subdomain. Created via `POST /v0/agents` or the Create Agent button. Identified by `agentId` (a short slug like `x0i33jye`). ### Engine The runtime that powers the agent. Engines are enabled per deployment: | Engine | Tagline | When to pick it | | ---------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `openclaw` (default) | Configurable agent for custom workflows and power users | You want full control over manifest fields, scripts, routes, and skills | | `hermes` | Opinionated agent with a smoother out-of-the-box experience | You want fewer knobs and first-run channel setup to feel more direct | | `super-builder` (beta) | Headless coding agent optimized for issue-board work | You're assigning work through [Issues & Boards](/agents/issues) and want longer runs (200-turn default cap) over chat features. Chat-first surfaces like Channels aren't available. | Pick the engine when creating the agent — either in the **Agent Engine** card on the Create Agent wizard, or by passing `engine` in `POST /v0/agents`, or by setting `engine` in [`manifest.json`](/agents/manifest) for a template. Available engines per deployment are listed at `GET /v0/agents/engines`. ### Gateway The long-running process inside each agent container that: * Terminates WebSocket connections from the dashboard, channels, and CLI * Routes path/domain traffic to user-defined ports * Brokers HTTP API calls for the per-agent subdomain * Restarts on **Restart Gateway** in the [Danger](/agents/devtools) tab Listens on the reserved port `18789`. ### Gateway token Per-agent credential used to authenticate against the agent's own subdomain (`{agentId}.agents.pinata.cloud/...`). See [API → Gateway token](/agents/api#gateway-token). Distinct from the **Pinata JWT** (workspace-wide API key) and from the **platform JWT** (1h token an agent gets from itself via `POST /v0/platform/token`). | Token | Where it works | What it's for | | ------------- | ------------------------------- | ------------------------------------------------------------------------------------------------- | | Pinata JWT | `agents.pinata.cloud` | Workspace-wide management - create/list/delete agents, manage secrets, browse templates | | Gateway token | `{agentId}.agents.pinata.cloud` | Talk to one specific agent (chat, files, routes, console, git) | | Platform JWT | `agents.pinata.cloud` | A short-lived JWT the agent gets *for itself* - lets the agent self-modify via `@pinata/platform` | ### Workspace Two meanings - context disambiguates: 1. **Team workspace** - your Pinata account or shared team. Switch under **Account → Workspaces**. 2. **Agent workspace** - the per-agent file tree inside the container. OpenClaw agents use `/home/node/clawd/workspace/`; Hermes agents use `/home/hermes/data/workspace/`. The workspace includes [`manifest.json`](/agents/manifest), `SOUL.md`, attached skills under `skills/`, file uploads under `uploads/`, and anything else your agent has written. ### Workspace anatomy The default file layout inside `workspace/`: | File | Purpose | | ---------------- | ---------------------------------------------------------------------------------------------------------- | | `manifest.json` | Agent configuration - identity, secrets, skills, scripts, routes, channels, tasks. Single source of truth. | | `SOUL.md` | Agent personality and principles - customize freely | | `AGENTS.md` | Conventions the agent follows when working in the repo (memory system, safety rules, file layout) | | `IDENTITY.md` | Name, vibe, emoji, owner identity - written at deploy time | | `USER.md` | Notes about the human user, learned over time | | `TOOLS.md` | Environment notes (what tools exist in the container) | | `BOOTSTRAP.md` | First-run conversation guide. Self-deletes after setup. | | `HEARTBEAT.md` | Periodic-task notes (empty by default) | | `skills//` | Files for each attached skill | | `uploads/` | Files uploaded via the chat attachment button or `POST /v0/agents/{agentId}/files/upload` | You can commit and push anything else (`projects/`, `scripts/`, etc.) - the agent treats the whole tree as fair game. ### `manifest.json` vs runtime config These are different files. They live in different places and have different schemas. | File | Path | Schema | Edited by | | ----------------------- | ------------------------------------ | -------------------------------------- | ------------------------------------------------------------------------------- | | `manifest.json` | `/manifest.json` | [`manifest.v1.json`](/agents/manifest) | You (committed to git, validated via `POST /v0/templates/validate`) | | OpenClaw runtime config | `/home/node/.openclaw/openclaw.json` | OpenClaw runtime schema | OpenClaw at runtime (validated via `POST /v0/agents/{agentId}/config/validate`) | | Hermes runtime config | `/home/hermes/data/config.yaml` | Hermes runtime schema | Hermes at runtime (edited from the Danger tab's Config row) | Day-to-day, edit `manifest.json`. Runtime config is the engine's own view of that configuration and is usually only touched from the [Danger](/agents/devtools) tab when you're debugging the engine itself. ### Skill A reusable package of files and instructions that extends an agent's capabilities. Pinned to IPFS, addressed by **slug** (`@pinata/api`) or **CID**. Installed into your Skills Library, then attached per-agent. Up to 10 attached per agent. See [Skills](/agents/skills). The platform ships with `@pinata/platform` bundled - it lets the agent perform self-service operations (install skills, set secrets, manage tasks). ### Secret vs variable Both are environment variables injected at container start. The difference: | Kind | Storage | Visible in API? | Use for | | ------------ | ------------------------------------- | -------------------- | --------------------------- | | **Secret** | AES-GCM encrypted with a per-user key | Never returned | API keys, tokens, passwords | | **Variable** | Plaintext | Returned in listings | Public URLs, feature flags | See [Secrets](/agents/secrets). ### Channel A messaging surface the agent can be reached on - Telegram, Slack, Discord (WhatsApp coming). Configured per-agent. See [Channels](/agents/channels). ### Route A mapping from an external URL prefix or domain to a container port. Lets you expose web apps and APIs running inside the agent. See [Routes & Domains](/agents/routes). ### Task A scheduled prompt or system event. Three schedule kinds: `at` (one-shot), `every` (interval), `cron`. See [Tasks](/agents/tasks). ### Lifecycle script Shell commands run by the agent runner at well-defined points: | Script | When | Working dir | Log file | Timeout | | ------- | ----------------------------------------------------- | ------------------ | --------------------- | --------------- | | `build` | After deploy, after each `git push`, on Retry Scripts | `/home/node/clawd` | `/tmp/user-build.log` | 5 min | | `start` | After successful `build`, on agent boot | `/home/node/clawd` | `/tmp/user-start.log` | None (detached) | Defined in `scripts` in [`manifest.json`](/agents/manifest#scripts). ### Snapshot A capture of the agent's workspace pinned to IPFS as a single CID. Created automatically every minute when changes are detected, plus on demand via `POST /v0/agents/{agentId}/snapshots/sync`. Reset to any historical snapshot via `POST /v0/agents/{agentId}/snapshots/reset`. See [Files & Snapshots](/agents/snapshots). ### Device A client paired with an agent (CLI, mobile, browser session) - approval-gated for security. Listed at `GET /v0/agents/{agentId}/devices`. See [Danger → Devices](/agents/devtools#device-pairing). ### Template A pre-configured agent (manifest + workspace files + skill list) packaged for one-click deployment. Published on the [Marketplace](https://agents.pinata.cloud/marketplace) or kept private in [My Templates](https://agents.pinata.cloud/templates). See [Templates](/agents/templates/overview). ### Issue Kanban-style work item assigned to an agent - title + prompt + optional repo. The agent runs it in an isolated `/runs//` directory (its own git history; ignored by snapshots), you review the diff, then accept, revise, or open a PR. Boards carry per-board instructions, model overrides, and turn/cost caps. See [Issues & Boards](/agents/issues). ## Filesystem reference Paths agents and developers reach for most often inside the container: | Path | What's there | | --------------------------------------- | ----------------------------------------------------------------------------------------------- | | `/home/node/clawd/` | OpenClaw runner root - where `build`/`start` execute | | `/home/node/clawd/workspace/` | OpenClaw workspace | | `/home/hermes/data/workspace/` | Hermes workspace | | `/skills//` | Attached skill files | | `/uploads/` | Uploaded files | | `/runs//` | Isolated working dir for each [issue](/agents/issues) run (gitignored, excluded from snapshots) | | `/home/node/.openclaw/openclaw.json` | OpenClaw runtime config | | `/home/hermes/data/config.yaml` | Hermes runtime config | | `/tmp/openclaw/openclaw-YYYY-MM-DD.log` | Daily OpenClaw log file | | `/tmp/user-build.log` | `build` script output | | `/tmp/user-start.log` | `start` script output | ## Reserved ports & names | Reserved | Why | | --------------------------------- | ---------------------------- | | Port `18789` | Gateway listens here | | Subdomains containing `pinata` | Reserved for first-party use | | Specific reserved domain suffixes | Reserved for the platform | Path routes must use ports between `1025` and `65535`, excluding `18789`. See [Routes](/agents/routes). ## Identifier formats Quick reference for the IDs you'll see in URLs and API responses: | Identifier | Format | Example | | ---------------- | -------------------------------------- | -------------------------------------- | | Agent ID | Random short slug | `x0i33jye` | | Snapshot CID | IPFS CIDv1, `bafy...` or `Qm...` | `QmUMfo19uXMdBSXLiZAz7w...` | | Skill CID | IPFS CIDv1, `bafy...` | `bafybeicglyjdb6w...` | | Skill slug | `@/` (lowercase, hyphens) | `@pinata/api` | | Custom domain ID | UUID | `2fcd2a0b-aa70-432d-a310-678e01570e65` | | Secret ID | Random opaque string | (server-assigned) | ## Where to go next Every field in `manifest.json` Auth, endpoints, and examples Debug a stuck agent Look up an API error