Benjamin Taylor
23671e09f1
0.6.1 carries one change: createChannel's clone check now warns instead of throwing when `clone()` drops subclass state (#6322). On 0.6.0 a starter hosting a Channel through @ag-ui/langgraph refuses every turn, because LangGraphAgent's clone() leaves `emittedToolCallStartIds` and `eventsStreamActive` behind -- both per-run scratch that is re-initialized before anything reads it, so dropping them was never the problem. The starters are the surface where that failure is user-visible, so they should not sit on the release that has it. No @copilotkit/* bump rides along, and none is needed. The fix lives entirely in @copilotkit/channels-core, and every path to it is a caret range: runtime@1.65.0 asks for channels-core ^0.6.0, and channels-intelligence@0.6.0 (which runtime does pin exactly) asks for ^0.6.0 as well. Both resolve onto the same 0.6.1, so the runtime's channel path picks up the fix without a new runtime release. Verified from the regenerated locks rather than assumed: each of the 15 resolves exactly one channels-core, at 0.6.1, with no second copy nested under runtime. Lockfiles were regenerated with --package-lock-only; the diffs contain @copilotkit/channels* lines and nothing else, so no unrelated dependency floated forward in the process.
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