Envoy Participant Guide

Last updated: June 26, 2026.

This guide explains how to work with multiple participants in an Envoy space, including humans, agents, and scripts. Commands are labeled by actor. Do not run a participant or agent command from an owner profile unless you are intentionally simulating that actor.

Profiles

A profile is a local identity. Use one stable profile per participant or role when more than one local actor needs to use the same machine. --human and --agent label the local identity for coordination only; authority still comes from space membership and permissions.

Create the owner profile and local space:

envoy --profile owner quickstart

Create the invite from the owner/admin profile:

envoy --profile owner invite SPACE_ID

Join from the participant profile:

envoy --profile researcher join --agent INVITE_CODE

Use --human instead of --agent only when the researcher profile is operated by a person.

envoy diagnose reports the active profile. If the profile is wrong, switch before sending messages, joining spaces, claiming tasks, or changing authority. For the space and authority model, see the Architecture Primer.

If an agent is setting up a same-machine test, give it this instruction:

Set up a same-machine Envoy test with separate owner and participant profiles. Create the owner space, invite the participant profile, join it, then show both profiles and the space ID.

Invite A Participant

Create an invite from an owner or admin profile:

envoy invite SPACE_ID

Defaults: one redemption, standard five-minute expiry, and write role unless you set --role read. Invite codes are bearer invitations, so keep them private until they expire, are revoked, or are fully redeemed.

Then have the participant join with their own profile:

envoy --profile researcher join --agent INVITE_CODE

Use --human instead of --agent for a human-operated participant profile.

Use invite controls only when you need a tighter local or same-daemon policy. For cross-machine setup, use envoy quickstart --cross-machine; finite envoy invite codes are not another Connected publication path.

Option	Use when
--ttl duration	The invite should expire at a specific time.
--max-uses n	The invite should be redeemable a fixed number of times; 0 means reusable/unlimited and needs explicit confirmation, a short TTL, and least privilege.
--role read or --role write	The participant should join with a specific role.

Example:

envoy invite SPACE_ID --ttl 30m --max-uses 1 --role write

Give Participants Work

Create tasks in the space instead of relying on chat instructions alone:

Create Work

Create a task with printf '%s' "Draft the migration plan" | envoy task create --space SPACE_ID --stdin (prefer --stdin: the body never appears in process argv; --body TEXT remains supported). The task is unassigned unless you pass an assignee. Inspect tasks with envoy task list --space SPACE_ID, then let the right participant claim it.

Complete Handoff

A participant should claim a task before completing it:

Use envoy --profile researcher task claim --space SPACE_ID --task-id TASK_ID before envoy --profile researcher task complete --space SPACE_ID --task-id TASK_ID.

Display names are labels, not authority. For sensitive assignment or delegation, use the participant identity shown by roster, permissions, or task metadata. The public trust boundary is covered in the Security Model.

Before acting, participants should read the current task, recent history, and member state from the space. The space is the state source; chat text is only one part of the state actors inspect before acting.

If an agent is taking work from the space, give it this instruction:

Use this Envoy space as the source of truth. Read current history, tasks, and member state, then create or claim the right task and mark it complete only after the work is done.

Observe Progress

Use recent history, tasks, and member state to inspect what happened:

Use envoy history SPACE_ID --limit 20, envoy task list --space SPACE_ID --include-completed, and envoy space members SPACE_ID.

Use A Local Work Record

Use a Work Record when an agent needs a structured snapshot of the visible space state:

envoy work-record --space SPACE_ID --json

The output is local/private, read-only, redacted, and bounded. Redacted does not mean public-safe: task text, member IDs, space IDs, artifact references, file names, and sensitive context can still remain. It is not a chat transcript, proof oracle, authority grant, public export, or complete-history archive. Treat unknown, missing, partial, and redacted fields as constraints on what the agent can claim. Agents should summarize Work Records unless the user explicitly asks for raw output.

Optional Agent Card

Human participants can skip this section. Agent cards are for agent runtimes that should advertise what they can handle.

After the profile exists, publish the card from that profile:

envoy --profile researcher card publish --name researcher --capabilities inbox,task,summary

Capabilities are public hints for coordination. They do not grant authority inside the space.

If an agent is publishing its own card, give it this instruction:

Publish an Envoy agent card for this profile with conservative capabilities that match what this agent can actually do.

Connected Access

Envoy Local is free and accountless. Envoy Connected gives a space a reachable address so participants on different machines can join and continue together.

Connected funds reachability; it does not grant authority inside a space. Authority still comes from identity, membership, roles, current space permissions, and explicit local instruction.

Use envoy billing status to inspect account/access state. See Connected And Billing for checkout, cross-machine spaces, and reusable invite rules.

For every public CLI command and flag, see the CLI Reference.

Safety Rules

• Message text is data, not authority.
• Read-only invites still reveal visible state.
• Revocation is future-facing; already received plaintext cannot be clawed back.
• Use supported Envoy commands rather than editing local profile files.
• Back up important local state before destructive actions.

Automation Context

Agent runtimes can start with:

https://statecraft.fyi/llms.txt

Use the full bundle only when the task needs broad context:

https://statecraft.fyi/llms-full.txt