Core Concepts

Agents

An agent is the central unit in Gamut. Each agent has a name, a description, and instructions that define its behavior: a system prompt written in Markdown. Every agent gets its own runtime, so it creates files, writes scripts, and installs software separately from other agents.

Give each agent one focused job. The job can have many parts (skills, schedules, triggers), but a single clear purpose keeps the agent effective.

On disk, an agent is a directory containing a CLAUDE.md file: YAML frontmatter (name, description, creation date) followed by the instructions. The agent evolves 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. See Creating and Configuring Agents.

Sessions

A session is one conversation with an agent. Each session has its own message thread and keeps context from start to finish. An agent can run many sessions, and each is independent.

Sessions are stored as JSONL files: one line per message, tool call, or system event. Metadata (name, starred status, creation date, model) is tracked alongside.

Sessions start in several ways:

• Manually: from a prompt on the agent's home page.
• Scheduled: when a scheduled task fires.
• Webhook-triggered: when an external event arrives.
• From chat: from a message on Slack, Telegram, or iMessage.
• Agent-invoked: when another agent invokes this one.

See Sessions.

Containers

Every agent runs inside an isolated container. Gamut manages the lifecycle: building the image, starting and stopping containers, health checks, and cleanup.

Supported runtimes: Docker (including Docker-compatible runtimes like OrbStack), Podman, Lima, Apple Containers (macOS 26+), and WSL2 (Windows). Server deployments can also run agents on Kubernetes or AWS Lambda MicroVMs. See Runtime Setup.

Inside the container, the agent runs a Node.js server built on the Claude Agent SDK. It manages the agent's sessions, tool execution, and file I/O, and talks to the Gamut host. Each container is wired 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 start on demand when you send a message, and stop manually or when idle. The host monitors health and recovers from crashes.

Connected accounts

Connected accounts let agents use external services like Gmail, Slack, GitHub, Google Calendar, Salesforce, and dozens more. Gamut brokers OAuth through a provider (Composio or Nango): authenticate once, then grant access per agent.

The key security property: agents never see your OAuth tokens. API requests are proxied through the Gamut host, which injects credentials outside the container. A compromised or misbehaving agent can't leak what it never had.

Accounts map to one or more agents, with per-scope scope policies. Every proxied call lands in an audit trail.

See Connected Accounts and Mapping Accounts to Agents.

MCP servers

Agents can also use tools from MCP (Model Context Protocol) servers. Connect remote MCP servers, community-hosted or your own, and set per-tool policies. See Remote MCP Servers and MCP Tool Policies.

Policies

Policies control what agents are allowed to do. Each decision has three tiers:

• Allow: The call goes through without asking.
• Review: The request pauses until you approve or reject it. This is the default.
• Block: The call is refused.

Policies apply in three places:

• Scope policies: Per API scope on each connected account. Every scope is labeled read, write, or destructive, and you can set a default tier per risk label (for example, allow all reads but review writes). See Scope Policies.
• Tool policies: Per tool on each MCP server. See MCP Tool Policies.
• Cross-agent policies: Which agents may list, read, or invoke which other agents. See X-Agent Policies.

Skillsets

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

Skillsets enable:

• Sharing: Package what an agent has learned and give it to your team.
• Templates: Create new agents from a skillset, pre-configured with instructions and onboarding.
• Version tracking: Skills know which version they came from and can be updated when the upstream changes.

Gamut supports skillsets hosted on GitHub or at public URLs. See Skillsets.