Dashboard Setup

The Setup page at /dashboard/setup is the starting point for configuring a new CodeSpar deployment. It is organized into two tabs: Channels and Projects.

When no project has been linked yet, the Overview page displays a setup banner that links directly here.

Channels Tab

The Channels tab provides a guided interface for connecting each messaging platform to your CodeSpar deployment.

Global Channel Configuration

At the top of the tab, the current state of all channels is summarized:

┌─────────────────────────────────────────────────────────┐
│ Channel Status                                           │
│                                                          │
│ Slack      ● Connected     WhatsApp   ○ Not configured  │
│ Discord    ● Connected     Telegram   ○ Not configured  │
└─────────────────────────────────────────────────────────┘

Below the summary, each channel has its own configuration section.

WhatsApp Setup

WhatsApp uses QR code authentication. The setup flow:

1. Click "Connect WhatsApp"
2. A QR code is displayed inline on the page, generated by the backend's WhatsApp bridge
3. Open WhatsApp on your phone
4. Go to Settings > Linked Devices > Link a Device
5. Scan the QR code displayed on the dashboard
6. Wait for the connection to establish (typically 5-10 seconds)
7. The status changes to "Connected" and the QR code disappears

┌──────────────────────────────────────┐
│ WhatsApp                             │
│                                      │
│ Scan this QR code with WhatsApp:     │
│                                      │
│   ┌──────────────────────┐           │
│   │                      │           │
│   │   [QR Code Image]    │           │
│   │                      │           │
│   └──────────────────────┘           │
│                                      │
│ Waiting for scan...                  │
└──────────────────────────────────────┘

The QR code refreshes automatically if it expires (typically after 60 seconds).

Environment variables required:

No additional tokens are needed — WhatsApp authentication is handled via the QR code scan.

Slack Setup

Slack requires a bot token and signing secret from the Slack API:

1. Create a Slack App at api.slack.com/apps
2. Under OAuth & Permissions, add these scopes: chat:write, app_mentions:read, channels:read, users:read
3. Install the app to your workspace
4. Copy the Bot User OAuth Token (starts with xoxb-)
5. Copy the Signing Secret from Basic Information
6. Enter both values in the dashboard setup form

┌──────────────────────────────────────┐
│ Slack                                │
│                                      │
│ Bot Token:                           │
│ ┌──────────────────────────────────┐ │
│ │ xoxb-****************************│ │
│ └──────────────────────────────────┘ │
│                                      │
│ Signing Secret:                      │
│ ┌──────────────────────────────────┐ │
│ │ ******************************** │ │
│ └──────────────────────────────────┘ │
│                                      │
│ [Test Connection]  [Save]            │
└──────────────────────────────────────┘

Environment variables required:

Discord Setup

Discord requires a bot token from the Discord Developer Portal:

1. Create an application at discord.com/developers
2. Go to Bot and click "Add Bot"
3. Copy the Bot Token
4. Under Privileged Gateway Intents, enable: Message Content Intent, Server Members Intent
5. Generate an invite link with bot and applications.commands scopes
6. Invite the bot to your server
7. Enter the bot token in the dashboard setup form

Environment variables required:

Telegram Setup

Telegram requires a bot token from BotFather:

1. Message @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Copy the HTTP API token
4. Enter it in the dashboard setup form

Environment variables required:

Testing Connections

Each channel card has a "Test Connection" button that sends a test message through the channel to verify the configuration is working. On success, a green confirmation appears. On failure, the error message is displayed inline.

Projects Tab

The Projects tab manages the repositories linked to your CodeSpar deployment.

Add Repository

A form at the top of the tab lets you link a new repository:

┌──────────────────────────────────────────────────────────┐
│ Link a Repository                                         │
│                                                           │
│ Repository (owner/repo):                                  │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ codespar/codespar                                     │ │
│ └───────────────────────────────────────────────────────┘ │
│                                                           │
│ [Link Repository]                                         │
└──────────────────────────────────────────────────────────┘

When you submit the form:

1. The backend validates the repository exists and is accessible via GITHUB_TOKEN
2. A Project Agent is created for the repository
3. If WEBHOOK_BASE_URL is configured and the token has admin:repo_hook scope, a GitHub webhook is automatically created
4. The project card appears below the form

Auto-Webhook Status

After linking a repository, the webhook status is shown:

Project Cards

Each linked project is displayed as a card:

┌──────────────────────────────────────────────────────────┐
│ codespar/codespar                          ● Linked      │
│ Branch: main                                              │
│ Webhook: ● Active                                         │
│ Agents: 1 (Project Agent)                                 │
│ Linked: 14 days ago                                       │
│                                                           │
│ [View Dashboard]  [Unlink]                                │
└──────────────────────────────────────────────────────────┘

Managing Projects

Workflow

A typical setup workflow for a new CodeSpar deployment:

1. Configure at least one channel (Slack is recommended for the richest experience)
2. Test the connection using the "Test Connection" button
3. Link a repository using the owner/repo format
4. Verify the webhook was auto-configured (or set it up manually)
5. Navigate to the Overview to see your agents and start interacting

After completing setup, you can start sending commands via your configured channel:

@codespar status
@codespar instruct add a health check endpoint
@codespar review PR #42

Next Steps

• Dashboard Overview — monitor your agents after setup
• Configure a Project — detailed end-to-end setup guide
• Channel Configuration — in-depth channel documentation
• Link a Repository — repository linking via chat commands