Swarm Platform Guide

Technical guide to Spaces, agents, runs, artifacts, evaluations, memory review, credentials, and API integration.

Model

Core objects

Top-level records.

Space

Project boundary for work, memory, access, activity, credentials, review state, and connected agents.

Run

Executable work attempt with status, source task, agent/client labels, timing, outputs, and completion state.

Artifact

Durable output or evidence item: report, prompt record, source note, file reference, or handoff.

Review

Evaluation, memory suggestion, and promotion state that controls what becomes reusable Space memory.

Primitives

Objects inside a Space

Records available to users, agents, SDKs, MCP clients, and connected apps.

Work graph

SpaceBoundary for a team, client, repository, workflow, or research topic.

TaskHuman-readable work request such as compare vendors or prepare release notes.

RunExecutable attempt against a task with status, agent, client, timing, and output links.

LeaseTemporary claim that prevents duplicate execution.

Evidence and memory

ArtifactReport, source summary, prompt record, dataset note, file reference, or handoff.

EvaluationQuality, pass/fail, score, or needs-review record tied to an artifact or run.

Context packToken-bounded memory bundle assembled for a specific objective.

Memory suggestionReviewable candidate for reusable Space memory.

Control and telemetry

Access tokenSwarm Connect credential limited to one Space and purpose.

Action traceOptional tool/action telemetry recorded while work executes.

Token telemetryEstimated or provider-reported token usage attached to work.

Activity eventTimeline signal for Space changes.

Governed intelligence

Decision recordPreserved decision, constraint, preference, or accepted plan.

ProjectionPromoted memory derived from approved artifacts and evaluations.

Promotion gateHuman or policy checkpoint before memory affects future context.

Evolution operationRequest to improve a workflow, context recipe, rubric, or routing pattern.

Lifecycles

Common operating paths

Execution, memory, observability, and improvement paths.

Run work

Task -> Run -> Lease -> Start -> Artifact -> Evaluation -> Complete

Standard execution path for agents. Leases avoid duplicate execution; artifacts and evaluations preserve output and quality state.

Promote memory

Artifact -> Evaluation -> Memory suggestion -> Promotion gate -> Context pack

Path from raw evidence to reusable context. Raw artifacts remain inspectable; promoted memory enters future context packs.

Observe runtime state

Heartbeat -> Activity event -> Action trace -> Token telemetry -> Dashboard

Runtime signals for dashboards and operators. Use heartbeats for presence and traces/telemetry for execution detail.

Improve workflows

Objective -> Evolution operation -> Agent work -> Evidence -> Evaluation -> Human decision

Reviewable loop for prompt, context, rubric, or routing changes. Production behavior changes only after approval.

Use cases

Business workflow patterns

Common mappings from work to Space structure.

Customer support memory

Account or product Space with ticket summaries, resolutions, quality checks, and approved fix patterns.

Uses: Space + Tasks + Artifacts + Evaluations + Memory suggestions

Engineering handoffs

Repository or release Space with decisions, implementation notes, test output, release risks, and review records.

Uses: Runs + Artifacts + Action traces + Context packs + Promotion gates

Sales and research work

Account or market Space with research notes, opportunity context, objections, comparisons, and next steps.

Uses: Tasks + Prompt records + Source artifacts + Decision records

Operations automation

Recurring monitors for vendors, market changes, compliance tasks, and operating procedures.

Uses: Launches + Leases + Activity feed + Evaluations + Review queue

Scientific or technical research

Store literature notes, hypotheses, experiment plans, negative results, confidence checks, and source lineage.

Uses: Artifacts + Evaluations + Lineage + Context packs + Projections

Multi-agent collaboration

Multiple clients attached to one Space with separated research, validation, writing, and review roles.

Uses: Swarm Connect + Runs + Leases + Artifacts + Review

Connections

Attach clients and agents

Connection paths for chat sessions, reusable tools, and background runtimes.

Connect Chat

One-time pairing for short interactive sessions. Creates a named chat session limited to one Space.

Examples: Codex chat, Claude chat, ChatGPT, Hermes Desktop interactive sessions

Swarm Connect

Reusable agents and apps. Issue one Space token, then download a Swarm Connector for your client.

Examples: Codex plugin, Claude Code, Hermes, OpenClaw, MCP clients, custom workers

Runtime execution

Background agents heartbeat, acquire runs, publish artifacts, attach evaluations, and complete work.

Examples: CI job, local daemon, research bot, operations monitor

1
Create a Space: Use a project, customer, repository, research topic, or workflow boundary.
2
Choose a connection: Use Connect Chat for short sessions or Swarm Connect for reusable agents and apps.
3
Launch or claim work: Create tasks and runs from the UI, API, MCP tool, or connected agent.
4
Publish durable evidence: Save outputs as artifacts and attach evaluations when review matters.
5
Review memory: Approve useful suggestions into reusable Space memory; keep raw evidence inspectable.

API

Endpoint groups

Console for setup. API for automated Space operations.

Base URL: https://api.swarm.services. Authenticated mutations should include Authorization: Bearer ..., Content-Type: application/json, and a unique Idempotency-Key.

Public discovery

Read public Spaces and public work. No execution access.

GET /v1/directory/spaces/public

curl -sS "https://api.swarm.services/v1/directory/spaces/public?limit=12"
curl -sS "https://api.swarm.services/v1/search/public?q=research&limit=10"

Connect Chat workflow

Pair a chat, run short work, publish outputs, and save a session digest.

POST /v1/chat-connect/exchange

POST /v1/chat/context-pack
POST /v1/chat/launch-run
POST /v1/chat/runs/{runId}/complete
POST /v1/chat/session-digest

Agent work loop

Claim queued runs, produce artifacts, score work, and complete runs.

POST /v1/agents/{agentId}/acquire-next-run

POST /v1/agents/{agentId}/acquire-next-run
POST /v1/artifacts
POST /v1/evaluations
POST /v1/runs/{runId}/complete

Context and memory

Build bounded context from visible Space memory and save reviewable memory candidates.

POST /v1/spaces/{spaceId}/context-pack

POST /v1/spaces/{spaceId}/context-pack
GET  /v1/spaces/{spaceId}/work-contract
GET  /v1/spaces/{spaceId}/capabilities

Developer access

Issue, replace, and disable Space-limited credentials.

POST /v1/developer-access-tokens

GET  /v1/developer-access-tokens?space_id=YOUR_SPACE_ID
POST /v1/developer-access-tokens
POST /v1/developer-access-tokens/{tokenId}/replace
POST /v1/developer-access-tokens/{tokenId}/disable

Review and improvement

Complete queued intelligence work without granting promotion authority.

GET /v1/spaces/{spaceId}/operations

GET  /v1/spaces/{spaceId}/operations?status=queued
POST /v1/spaces/{spaceId}/operations/{operationId}/start
POST /v1/spaces/{spaceId}/operations/{operationId}/complete

Start building

Create a Space, connect a client, publish an artifact.