Configuration

Configure your bot with a backend URL for short request/response APIs and a gateway URL for inbound websocket delivery.

Environment variables

Variable	Required	Default	Description
`BOT_TOKEN`	Yes	-	Bot authentication token
`BACKEND_URL`	No	`https://api.hazel.sh`	Backend API URL for message sends, command sync, and auth
`GATEWAY_URL`	No	`BACKEND_URL`	Bot gateway URL for inbound websocket delivery
`ACTORS_URL`	No	Hazel hosted default	Actors endpoint for AI and live-state streaming
`PORT`	No	`0`	Health server port

Example `.env`

BOT_TOKEN=your-bot-token-here
BACKEND_URL=http://localhost:3003
GATEWAY_URL=http://localhost:3034
ACTORS_URL=http://localhost:6420

`runHazelBot` options

runHazelBot reads environment variables by default and lets you override them in code.

interface RunBotConfig<Commands> {
	commands?: Commands
	mentionable?: boolean
	healthPort?: number | false
	layers?: readonly Layer[]
	setup: (bot: HazelBotClient) => Effect<void>
	config?: Partial<HazelBotConfig<Commands>>
	serviceName?: string
}

Example

runHazelBot({
	commands: myCommands,
	setup: (bot) =>
		Effect.gen(function* () {
			// Register handlers
		}),
	config: {
		backendUrl: "http://localhost:3003",
		gatewayUrl: "http://localhost:3034",
	},
	serviceName: "my-task-bot",
})

`createHazelBot` options

Use createHazelBot when you want to build and manage the runtime directly.

interface HazelBotConfig<Commands> {
	botToken: string
	backendUrl?: string
	gatewayUrl?: string
	actorsEndpoint?: string
	commands?: Commands
	mentionable?: boolean
	resumeOffset?: string
	sessionStore?: GatewaySessionStore
	stateStore?: BotStateStore
	maxConcurrentPartitions?: number
	heartbeatIntervalMs?: number
	serviceName?: string
	healthPort?: number | false
}

Example

const runtime = createHazelBot({
	botToken: process.env.BOT_TOKEN!,
	backendUrl: "http://localhost:3003",
	gatewayUrl: "http://localhost:3034",
	commands: myCommands,
	maxConcurrentPartitions: 8,
})

Resume and state

The websocket runtime uses two optional stores:

sessionStore persists the last acknowledged gateway offset.
stateStore persists small bot-local state, such as thread mappings.

If you do not provide either store, the SDK uses in-memory defaults.

Local development

For local development, point the bot at your local backend and gateway:

BOT_TOKEN=dev-bot-token
BACKEND_URL=http://localhost:3003
GATEWAY_URL=http://localhost:3034
ACTORS_URL=http://localhost:6420

Configuration

On this page