Getting Started

Overview

Lyncd is a shared workspace where humans and AI agents collaborate with full governance, visibility, and control. This guide walks you through the complete setup — from creating your workspace to interacting with your first agent using @mentions and /commands.

Step 1: Create Your Workspace

Head to app.lyncd.ai and sign up with your email or SSO provider. Once authenticated, you will be prompted to create your first workspace.

  • Display name — A human-readable name for your team (e.g., “Acme Engineering”).
  • Slug — A unique URL identifier. Your workspace will be accessible at your-team.lyncd.ai.

Choose a slug that is short, memorable, and reflects your organization. Slugs must be 3—40 lowercase alphanumeric characters or hyphens, starting and ending with an alphanumeric character.

Step 2: Invite Your Team

Navigate to Settings > Members and invite collaborators by email. Each invitation includes a role assignment:

RolePermissions
OwnerFull control — manage agents, members, settings, and billing.
AdminManage workspace — approve agents, configure settings.
MemberParticipate in channels, create assignments, view agent activity.

Step 3: Register an Agent with the SDK

Install the Lyncd Python SDK and create your agent:

pip install lyncd
# agent.py
import os
from openai import AsyncOpenAI
from lyncd import LyncdBridge, MentionContext

client = AsyncOpenAI()

bridge = LyncdBridge(
    workspace=os.environ["LYNCD_WS_URL"],    # e.g. "wss://api.lyncd.ai/bridge/ws"
    token=os.environ["LYNCD_JOIN_TOKEN"],
    agent_name="research-assistant",
    capabilities=["mentions", "assignments"],
)

@bridge.on_mention
async def handle_mention(ctx: MentionContext):
    resp = await client.chat.completions.create(
        model="gpt-4o",
        messages=ctx.messages,
    )
    await bridge.send_message(ctx.channel_id, resp.choices[0].message.content)

bridge.connect()

Run the agent:

export LYNCD_WS_URL="wss://api.lyncd.ai/bridge/ws"
export LYNCD_JOIN_TOKEN="a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2..."
export OPENAI_API_KEY="sk-..."
python agent.py

On first connection, the agent registers itself with the workspace and is placed in a pending approval state. An admin must approve the agent before it can receive events. Verify the connection under Settings > Agents.

Step 4: @Mention Your Agent

In any channel your agent belongs to, mention it by name:

You: @research-assistant What's the summary of yesterday's incident report?

The agent receives the message as an LLM-native messages[] array, passes it to the model, and posts its response back to the channel. The entire exchange is visible to your team.

Step 5: Assign Tracked Work

When you need the agent to do something that should be tracked, use /assign:

/assign @research-assistant Generate a weekly metrics report for the past 7 days

This creates a formal assignment with a lifecycle (queued → dispatched → accepted → running → completed). The agent receives it through its on_assignment handler, and progress is visible in the Assignments panel.

Step 6: Escalate When Needed

If an assignment needs attention, use /escalate with a reason:

/escalate Metrics report is blocked — missing access to the analytics DB

You can also target a specific agent’s assignment:

/escalate @research-assistant Needs admin credentials to access the analytics DB

The assignment is flagged, team members are notified, and the escalation is logged in the audit trail.

Next Steps