Core Concepts

SuperAgent is built around a small set of concepts that compose together. Understanding them will help you get the most out of the platform.

Agents

An agent is the central unit in SuperAgent. Each agent has a name, a description, and a set of instructions that define its behavior -- essentially a system prompt written in Markdown.

On disk, every agent is stored as a directory containing a CLAUDE.md file. This file holds YAML frontmatter (name, creation date, description) followed by the agent's instructions in the body. The agent learns and evolves over time by appending preferences and project notes to this file.

---
name: Email Assistant
description: Manages and summarizes my inbox
createdAt: 2025-03-15T10:00:00.000Z
---
 
# Agent Instructions
 
You are a helpful email assistant.
 
## Preferences
 
- Always summarize in bullet points
- Flag anything from my manager as high priority

Agents can be configured, exported, shared as templates, and installed from skillsets. For detailed guidance, see Creating and Configuring Agents.

Sessions

A session is a single conversation with an agent. Each session gets its own thread of messages and maintains context from start to finish. You can have many sessions with the same agent -- each one is independent.

Sessions are stored as JSONL (JSON Lines) files, where each line represents a message, tool invocation, or system event. Session metadata (name, starred status, creation date, model used) is tracked alongside the JSONL data.

Sessions can be created in several ways:

• Manually -- You type a message on the agent's home page.
• Scheduled -- A scheduled task fires and creates a session automatically.
• Webhook-triggered -- An external event triggers a new session.
• Agent-invoked -- Another agent invokes this one via multi-agent orchestration.

See Sessions for more detail.

Containers

Every agent runs inside an isolated container. SuperAgent manages the full container lifecycle -- building the image, starting and stopping containers, health-checking, and resource cleanup.

Supported container runtimes include:

• Docker (via Docker Desktop or standalone daemon)
• OrbStack (macOS)
• Podman
• Lima (lightweight Linux VMs on macOS)
• Apple Containers (macOS native)
• WSL2 (Windows)

Inside the container, the agent runs a Node.js server built on the Claude Agent SDK. This server manages Claude Code sessions, tool execution, file I/O, and communication with the SuperAgent host. Each container is wired up with:

• The agent's workspace directory (mounted from the host)
• Environment variables (API keys, secrets)
• A proxy token for calling connected account APIs
• Access to configured MCP servers

Containers are started on demand when you send a message and can be stopped manually or automatically when idle. The host monitors container health and recovers from crashes.

Connected accounts

Connected accounts let agents interact with external services like Gmail, Slack, GitHub, Google Calendar, Salesforce, and dozens more. SuperAgent brokers OAuth connections through Composio, so you authenticate once and then grant access to specific agents.

The key security property: agents never see your OAuth tokens. When an agent needs to call an external API, the request is proxied through the SuperAgent host, which injects the real credentials outside the container. This means a compromised or misbehaving agent cannot leak your tokens.

Each connected account can be mapped to one or more agents. You control which API scopes are allowed, reviewed, or blocked using scope policies. Every proxied API call is logged in an audit trail.

For setup details, see Connected Accounts and Mapping Accounts to Agents.

Tools

Tools are the actions an agent can take. SuperAgent provides a rich set of built-in tools, and you can extend agents with external tool servers.

Built-in tools

These are available to every agent out of the box:

MCP servers

Agents can also use tools exposed by MCP (Model Context Protocol) servers. You can connect remote MCP servers -- either community-hosted or self-hosted -- and configure per-tool policies for them. See Remote MCP Servers and MCP Tool Policies.

Policies

Policies give you fine-grained control over what agents are allowed to do. There are two main types:

Scope policies (connected accounts)

For each connected account, you can set a policy per API scope:

• Allow -- The agent can call this API scope without approval.
• Review -- The agent's request is paused and you are notified to approve or reject it.
• Block -- The agent is prevented from using this scope entirely.

This lets you grant broad read access while requiring approval for write operations, for example. See Scope Policies.

Tool policies (MCP servers)

Similarly, for each MCP server, you can set per-tool policies that allow, require review, or block specific tools. See MCP Tool Policies.

Cross-agent policies

When using multi-agent orchestration, you can control which agents are allowed to invoke which other agents. See X-Agent Policies.

Skillsets

Skillsets are reusable collections of agent capabilities backed by Git repositories. A skillset contains an index of skills -- each skill is essentially a directory of files (instructions, scripts, templates) that gets installed into an agent's workspace.

Skillsets enable:

• Sharing -- Package what an agent has learned and share it with your team.
• Templates -- Create new agents from a skillset template, complete with pre-configured instructions and onboarding flows.
• Version tracking -- Skills track which version they were installed from and can be updated when the upstream skillset changes.

SuperAgent supports skillsets hosted on GitHub (cloned via Git) and on public URLs. See Skillsets for the full guide.