Run your first Bot in 10 minutes

This page delivers one result: send /hello to a new Bot in the browser Sandbox and receive a reply from the real Runtime. No platform account or model key is required.

Before you start

• Scaffolded TypeScript projects on this page require Node.js >=22.12.0; >=22.18 is recommended. The compiled IM library still supports ^20.19.0 || >=22.12.0.
• pnpm 9 or newer.
• Access to Remote Console.

1. Create and start

npm create zhin-app my-bot -y
cd my-bot
pnpm dev

-y creates the IM golden path with HTTP Host, Sandbox, Remote Console, and a /hello example. Remove -y when you want the wizard to configure a real platform, database, or AI.

2. Verify in Console

The startup output prints the API Base. New projects currently use http://127.0.0.1:8068; always trust the terminal or http.port in zhin.config.yml.

1. Open console.zhin.dev.
2. Enter the API Base printed by the Host.
3. Use HTTP_TOKEN from the project .env file.
4. Open Sandbox under Conversations & Channels and send /hello.

A reply proves the Console authentication, HTTP Host, Sandbox Endpoint, command discovery, and outbound reply path all work.

3. Know the generated project

my-bot/
├── package.json          # Runtime topology: entry, features, plugins
├── zhin.config.yml       # Host and plugin configuration values
├── .env                  # token, platform credentials, model keys
├── plugin.ts             # root plugin entry
├── commands/             # file paths define command routes
├── components/           # reusable message components
└── pages/                # Console pages contributed by the plugin

package.json#zhin is the topology source of truth. zhin.config.yml stores values only. Convention files and capabilities registered in setup() enter the same generation projection.

4. Observe hot reload

Change the reply in commands/hello.ts, save it, and send /hello again. New requests use the new generation; an in-flight request keeps its original snapshot.

Troubleshooting

npx zhin doctor

Doctor checks Node, pnpm, ports, HTTP_TOKEN, CORS, and the project manifest. When Console cannot connect, check the API Base printed by this project instead of assuming a default port.

Choose the next outcome

Need	Shape	Continue with
Validate an idea	one bot.ts file	Examples
Build commands and components	plugin + convention directories	IM Bot path
Add models and tools	Agent Features	AI Agent path
Operate multiple accounts	HTTP Host + Remote Console	Console path

Install tiers

Tier	Install	~production size	Capabilities
IM	pnpm add zhin.js + an adapter (for example, @zhin.js/adapter-sandbox); dev: @zhin.js/cli	<10MB (library)	Plugin Runtime; command / component / adapter convention directories (Stable Features inherited via @zhin.js/core zhin.features; Host is an optional peer + zhin.plugins, see Plugin model)
AI	+ @zhin.js/agent zod ai	+~12–15MB	ZhinAgent, sessions, tools, compaction
Provider	+ @ai-sdk/openai etc.	per vendor	LLM calls
MCP	+ @modelcontextprotocol/sdk	+ a few MB	MCP client
Rich media	+ @zhin.js/html-renderer	+ a few MB	outbound html / markdown to PNG (falls back to text if missing)
Speech	+ @zhin.js/speech	+ a few MB	inbound STT, outbound TTS, segment.tts (warns and degrades if missing)

Prefer an outcome over learning the package graph first: Choose a solution.