Benjamin Taylor
e1f88ebc12
Addresses review feedback that channel-host.mts is doing too much.
Two changes, both scoped to the starters:
1. Channel construction moves to a new `channels.mts` beside `agent.ts` —
name resolution, `createChannel`, and the `onMessage` handler. That is
also the file to edit to customise a Channel (commands, reactions,
onMention), which previously meant editing the host.
The per-framework agent import moves with it, so `channel-host.mts` is now
byte-identical in all 15 starters rather than 13 + 2.
2. The host no longer stands up an HTTP server. Its comment claimed the
server was what "keeps the lifecycle-owning process alive"; that is false.
An open undici WebSocket holds the event loop on its own — verified with a
standalone repro where a process with no HTTP server and no timers of its
own stayed up indefinitely on a single WebSocket connection. The server was
therefore serving a second, uncalled copy of the runtime API on port 8300
for no reason.
With the server gone, `createCopilotNodeListener` was the wrong factory —
it builds a request listener purely for its activation side effect. The
host now uses `createCopilotRuntimeHandler` + `ready()`, which is the
documented long-running-host pattern (see fetch-handler.ts). This also
drops `node:http`, `basePath`, and the CHANNEL_PORT env var.
Behaviour is unchanged: same Channel, same agent, same status reporting, and
the same non-zero exit on activation failure.
Verified: 14/14 starters with a `typecheck:channel` script pass; mastra has no
such script by design (166dc94691) and its pre-existing Mastra `Memory` type
error is byte-identical before and after. `npm run channel` exercised on both
failure paths — missing channels.json, and missing INTELLIGENCE_API_KEY with a
name supplied — confirming the new `./channels.mjs` specifier resolves under
tsx as well as tsc. `parity:check` output identical to the pre-change baseline.
Refs #6315
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
5.3 KiB
CopilotKit <> Mastra Starter
This is a starter template for building AI agents using Mastra and CopilotKit. It provides a modern Next.js application with integrated AI capabilities and a beautiful UI.
Prerequisites
Getting Started
- Add your OpenAI API key
# you can use whatever model Mastra supports
echo "OPENAI_API_KEY=your-key-here" >> .env
- Install dependencies using your preferred package manager:
# Using npm (default)
npm install
# Using pnpm
pnpm install
# Using yarn
yarn install
# Using bun
bun install
- Start the development server:
# Using npm (default)
npm run dev
# Using pnpm
pnpm dev
# Using yarn
yarn dev
# Using bun
bun run dev
This will start both the UI and agent servers concurrently.
Running a Channel
channel-host.mts mounts the same agent as an Intelligence Channel
(Slack, Teams). It requires INTELLIGENCE_API_KEY and a declared Channel in
.copilotkit/channels.json — set both up with copilotkit init or
copilotkit channels add, which write that file and the credentials your
.env needs, then:
npm run channel
The host reads which Channel to hold from .copilotkit/channels.json. If a
project declares more than one, set INTELLIGENCE_CHANNEL_NAME to pick one.
The host holds no provider credentials and exposes no provider endpoint — Intelligence owns the provider edge — so the same file works for every provider.
The Channel itself is declared in channels.mts — that is where to add commands,
reactions, or an onMention handler. channel-host.mts only owns the process
lifetime, and is byte-identical in every starter.
Once startup finishes, the log reports the truth per Channel:
Channel "<name>" is online.— the session is up and can send.Channel "<name>" is declared but no provider is attached yet.— a normal waiting state, not a failure. Runcopilotkit channels statusto see what setup remains.
Neither message proves the provider app is installed, reachable, or that anyone can message it — verify that separately (invite the bot, then message it) before treating the Channel as working.
Unlike the other starters, this one has no typecheck:channel script: the
host's import chain reaches src/mastra/**, which carries a pre-existing
type error unrelated to the Channel host (see the comment in
tsconfig.channel.json).
Available Scripts
The following scripts can also be run using your preferred package manager:
dev- Starts both UI and agent servers in development modedev:ui- Starts only the Next.js UI serverdev:agent- Starts only the Mastra agent serverdev:debug- Starts development servers with debug logging enabledbuild- Builds the application for productionstart- Starts the production serverchannel- Holds an Intelligence Channel open (see "Running a Channel" above)
Documentation
- Mastra Documentation - Learn more about Mastra and its features
- CopilotKit Documentation - Explore CopilotKit's capabilities
- Next.js Documentation - Learn about Next.js features and API
Contributing
Feel free to submit issues and enhancement requests!
License
This project is licensed under the MIT License - see the LICENSE file for details.
CopilotKit Intelligence & Threads (Optional)
CopilotKit Intelligence adds durable thread history and cross-session memory to
your agent. It requires a COPILOTKIT_LICENSE_TOKEN and a running local
Intelligence stack (Docker Desktop + a local Intelligence repo checkout).
Prerequisites
- Docker Desktop running
- A
COPILOTKIT_LICENSE_TOKEN(obtain from CopilotKit Cloud) - The Intelligence repo cloned
locally. The
docker-compose.intelligence.ymldefaults to a sibling directory at../../../Intelligencerelative to this starter; override with theINTELLIGENCE_REPOenv var if your checkout is elsewhere.
Start the intelligence stack
# From inside this starter directory:
docker compose -f docker-compose.intelligence.yml up -d --wait
First run builds the intelligence image from source (may take several minutes).
Verify the stack is healthy
docker compose -f docker-compose.intelligence.yml ps
All three services (postgres, redis, intelligence) should show healthy.
Set environment variables
Add the following to your .env file:
COPILOTKIT_LICENSE_TOKEN=your-license-token-here
INTELLIGENCE_API_URL=http://localhost:4204
INTELLIGENCE_GATEWAY_WS_URL=ws://localhost:4404
Then start the dev server as usual (npm run dev). Thread history and memory
features are activated automatically when COPILOTKIT_LICENSE_TOKEN is set.
Stop / reset
# Stop without removing data:
docker compose -f docker-compose.intelligence.yml down
# Full reset (removes postgres + redis volumes):
docker compose -f docker-compose.intelligence.yml down -v