Concepts

The mental model behind Appstrate. Agents, runs, integrations, packages, spaces, and how they fit together.

Appstrate gives an AI agent a prompt, credentials and context, and lets the model decide how to accomplish the task. This page lays out the vocabulary. Each concept has a deeper page in Features.

Architecture at a glance

┌─ Organization ───────────────────────────────────────────────┐
│  Members and roles, models, proxies, package catalog         │
│                                                              │
│  ┌─ Space (team or personal) ─────────────────────────────┐  │
│  │  Active agents, skills, integrations                   │  │
│  │  Runs, schedules, files, chat, API keys, webhooks      │  │
│  │                                                        │  │
│  │  ┌─ Run ───────────────────────────────────────────┐   │  │
│  │  │                                                 │   │  │
│  │  │  ┌──────────┐   MCP    ┌──────────────────┐     │   │  │
│  │  │  │  Agent   │ ───────→ │     Sidecar      │     │   │  │
│  │  │  │  (Pi)    │          │ (credentials,    │     │   │  │
│  │  │  └──────────┘          │  LLM, tools)     │     │   │  │
│  │  │                        └────────┬─────────┘     │   │  │
│  │  │                                 │               │   │  │
│  │  │                     Models and external APIs    │   │  │
│  │  └─────────────────────────────────────────────────┘   │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌─ Another space ────────────────────────────────────────┐  │
│  │  (its own agents, runs, end-users and API keys)        │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘

Agents

An agent is the core unit of work. It is defined by a prompt that describes its mission, not by a graph of steps. The model reads the prompt and decides which tools to call, and in what order.

An agent package declares:

An input schema (JSON Schema) for the parameters a person or a schedule supplies at launch, and an optional output schema the result must satisfy. A space can store default input values and lock some of them.
Dependencies: the skills, MCP servers and integrations it uses.
Runtime tools: built-in tools such as output, log, note, pin and publish_file.

An agent also gets persistence across runs:

Memory. The note tool saves a memory that the recall_memory tool can search in later runs. The pin tool keeps an item under a named key that is shown to the agent at the start of every run. Memory belongs to a space and is partitioned by who the run acts for: a member, an end-user, or shared.
Files. Runs read uploaded files and publish deliverables with publish_file. Every file has a stable appfile:// URI, so the output of one run can be the input of another.

Deep-dive: Features / Agents and Features / Memory.

An integration is the definition of an external service (Gmail, Slack, GitHub, Jira, an internal API, any MCP server). Appstrate ships a catalog of system integrations, and you can author your own as a package. An integration declares:

Its source: a local MCP server that Appstrate runs in a runner container, a remote MCP endpoint, or a plain HTTP API called through the sidecar.
Its authentication methods: OAuth 2.0 (with discovery and PKCE), API key, basic auth, mTLS or custom credential fields.
How credentials are delivered to a call, and the authorized URIs the credential may be used against. The sidecar refuses any other target.

An agent lists the integrations it needs and which of their tools it may use. The OAuth scopes requested follow from that selection.

Connections

A connection is one authenticated account on an integration, owned by the person who connected it. A member can share a connection with the other users of a space. Credentials are encrypted at rest and handed to the sidecar for the run, never to the agent: the agent calls a tool, the sidecar adds the credential and relays the request.

A run that needs an integration without a usable connection is refused before it starts, and a connection whose OAuth grant expired is marked as needing reconnection. People connect accounts from the agent's Connections tab or from the integration's page, and manage them under Preferences → My connections, and the chat can offer a connect link when it needs one.

Deep-dive: Integrations.

Runs

A run is a single agent execution. Its lifecycle:

pending → running → success | failed | timeout | cancelled

A run starts from the dashboard, the chat, a schedule, the CLI, the API or an MCP client. Each run gets two cooperating parts:

Sidecar. Holds the run's credentials, proxies the model calls, and exposes the agent's tools over MCP: integration tools, api_call with credential injection, run_history and recall_memory. It checks every outbound target against the integration's allowed URIs.
Agent. The Pi Coding Agent process that receives the prompt and talks only to its sidecar. It never holds the credentials.

Where they run depends on the install. Docker tiers use one container pair per run on a private network, so concurrent runs of the same agent are isolated from each other. Tier 0 uses Bun subprocesses without container isolation. A Firecracker backend, opt-in, gives each run its own microVM.

Logs stream live over Server-Sent Events and are persisted for replay. Token usage is metered per run and priced in US dollars from the model's rate card. A model without a known price leaves the run marked unpriced (cost_pricing_status): its cost is null, which means not priced rather than free, and the dashboard does not show an amount for it.

Deep-dive: Features / Runs and Features / Sandbox and Sidecar.

Packages

Everything you author or install is a package in the open AFPS format (Agent Format Packaging Standard): a ZIP archive with a manifest.json at its root. There are four types:

Type	What it contains
`agent`	A prompt, input and output schemas, and its declared skills, MCP servers and integrations
`skill`	A `SKILL.md` file (YAML frontmatter plus Markdown) and optional scripts or references
`mcp-server`	A packaged MCP server (an MCP Bundle) that runs as a subprocess
`integration`	An external-service definition: source, authentication methods, credential delivery

Each package has an editable draft and immutable, semver versions you publish from it. Versions carry a SHA-256 integrity hash, and the latest tag points at the newest. The platform ships some packages itself (system packages), and you import the rest from a .afps or .afps-bundle file or from a GitHub URL. You can also edit a package in a local folder with the CLI (appstrate packages).

A package belongs to the organization and has a home space. It can be shared into other spaces, and a space decides which of its packages are active.

The AFPS specification lives in the afps-spec repository. Deep-dive: Features / Packages and Resources / AFPS Specification.

Organizations, spaces and roles

Organizations

The organization is the membership and administration boundary. It holds:

Members and their organization role: owner, admin, member (shown as Standard user) or guest.
The LLM models and model provider keys, and outbound proxies.
The package catalog, and organization-wide webhooks and OAuth clients.
Billing, when the optional billing module is enabled.

Spaces

A space is where work happens. It holds the active agents, skills and integrations, the runs and schedules, files, chat conversations, API keys, end-users and webhooks. An organization has one default space and any number of team spaces, and every member also gets a private personal space that only they can use.

Access is per space. A space is open (standard users enter with the default role), closed (they must be added) or private (visible only to those added). A member's role in a space is a preset (admin, builder, operator, runner, viewer) or a custom role your organization defines. Guests only see the spaces they were added to. Owners and admins reach every team space, but never someone's personal space.

Spaces replaced what were called applications. If you meet an app_ id or an applicationId in older material, the current equivalents are spc_ ids and spaceId.

Deep-dive: Features / Organizations and Features / Spaces. Internals: Spaces and RBAC.

End-users

End-users (eu_ prefix) are the users of your product, distinct from Appstrate members. You manage them through the API and run agents on their behalf with impersonation: an API key plus the Appstrate-User header. Each end-user has their own connections, memory and run history, without ever using the dashboard. End-users live in team spaces, not personal ones.

Deep-dive: Features / End-Users, Features / Multi-Tenancy.

Where to go next

Quickstart: install an instance and run an agent.
Using Appstrate: the webapp, the chat, the CLI, and connecting coding agents and MCP clients.
Features: one deep-dive per primitive.
Self-Hosting: infrastructure tiers and production operations.