Skip to main content
Formation starts with no agents. Create one in the dashboard, give it a model and a profile, then connect the places where people will talk to it. Agents and their settings live in PostgreSQL and can also be managed through the Operator API. Your operator login and the agent’s identity are separate. An operator manages Formation; an agent participates in conversations using its own accounts.

​
Before you start

  • Run Formation with a working database and MESH_AGENT_MASTER_KEY. Keep the master key outside the database and back it up securely; see Secrets and recovery.
  • Set PUBLIC_URL to the stable HTTPS address people and providers will use. Slack, Telegram and phone webhooks need a reachable deployment. Configure DNS and TLS before registering their webhooks.
  • Have access to a model provider, or ask an owner to configure Instance model defaults. Supported providers are OpenRouter, Ramp Router, and OpenAI or an OpenAI-compatible server. Model providers explains the choices.

​
Set up the first agent

  1. Sign in as an operator. A fresh installation using local authentication asks you to create the first administrator. That account is an owner. Owners can invite other owners or give an agent operator access to selected agents. Deployments using external authentication use their configured sign-in flow instead.
  2. Create and name the agent. Enter a display name and slug. Formation saves a draft so you can resume setup after a reload.
  3. Connect a model. If instance defaults are configured, the wizard uses their provider, billing credential and model assignments. Choose Customize models for a different provider or an agent-specific key. Otherwise connect a provider and select a primary model. Fast and heartbeat are optional roles; heartbeat falls back to fast, and fast to primary.
  4. Describe its job. Draft and review a profile or write one yourself. Guided setup prepares memory defaults from the selected provider without a separate configuration step. Picture customization is optional. Use Advanced setup for explicit memory, tools and external chat setup.
  5. Try a first task inside Formation. The native conversation needs no Slack or Telegram account. Send a message, confirm the delivered reply, and try one tool action. The first-task checklist reads actual runtime results; a healthy instance or a saved connection is not a completed task.
  6. Add tools and external chat when needed. The agent overview opens native Chat. Tools connects this agent’s own service accounts. Connections adds Slack, Telegram or phone. Neither is required to start a conversation in Formation. For Slack, invite the agent to a channel before mentioning it there.
Native chat is an operator conversation, scoped to that operator and agent. It is retained in the normal conversation graph and a durable delivery mailbox. Operators who already have inspection access to the agent can inspect its history. It does not create or inherit an external acting identity. Accepted messages and replies survive refresh; uncertain sends reuse their request ID. The chat view shows the latest 100 entries; captured earlier history remains available in Conversations. Repeat this flow for additional agents. Each has its own perspective, profile, connections, memory and work. You can add more connector installations to an existing agent.

​
Choose where people can reach the agent

​
Add tools during or after setup

An agent’s Tools page manages native integrations, remote MCP accounts, web access and coding tools. Follow Tool setup. Model billing and execution-provider credentials may be inherited infrastructure; external acting accounts belong to the agent. A second token for the same external account does not create a distinct acting identity. Then configure optional features as needed: automatic model selection (on by default for new agents), Dreaming, commitments, and the agent vault.

​
Change a hostname or repair a connection

Changing PUBLIC_URL does not update webhook addresses already stored at a provider. For a managed Slack app, use Update Slack configuration on each connection. For a manual Slack app, update its Event Subscriptions request URL and reverify it; the dashboard shows the expected URL. Other connectors must also have their provider-side webhook registration updated. A manual Slack URL challenge can return 401 before its connector credentials have been saved. Save the connector and retry verification. For missing Slack permissions, use Check permissions and Update Slack permissions on a managed app; manual apps require a scope update and reinstall in Slack. Runtime registry reload applies to the process handling the change. Database persistence and durable work queues alone do not establish multi-replica configuration propagation; operate within your deployment’s supported topology.