Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hunvreus/heypi/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you from zero to a running Slack chat agent. You will install Heypi, write a minimal agent folder, connect a Slack adapter, and call runHeypi to bring everything online. The whole setup fits in one TypeScript file and a pair of Markdown files.
1
Install Heypi
2
Install the core package with your preferred package manager.
3
npm
npm install @hunvreus/heypi
yarn
yarn add @hunvreus/heypi
pnpm
pnpm add @hunvreus/heypi
4
Heypi requires Node.js 22 or newer. No other system dependencies are needed for a basic Slack setup.
5
Set Environment Variables
6
Heypi needs credentials for your chat platform and your AI model provider. For the Slack quickstart:
7
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-level-token
OPENAI_API_KEY=sk-your-openai-key
8
OPENAI_API_KEY is read directly by Pi through its normal provider auth path—Heypi does not read it itself. You can pass model explicitly to agentFrom() or set HEYPI_MODEL (e.g. openai/gpt-5-mini); Heypi does not pick a model implicitly.
9
To use a different model provider, set HEYPI_MODEL to any provider/model-name string that Pi supports, or pass model in code (shown in the next step).
10
Create the Agent Folder
11
The agent folder holds your agent’s identity and operating rules. Create a minimal one:
12
mkdir agent
13
You are a helpful DevOps assistant for the engineering team.
Answer concisely. Use plain language.
Prefer safe, auditable actions over shortcuts.
14
- Always confirm destructive operations before running them.
- Do not access resources outside the project workspace.
- If unsure, ask for clarification rather than guessing.
15
SOUL.md sets the agent’s identity and voice. AGENTS.md provides standing operating rules. Both are optional—Heypi falls back to a sensible default assistant identity if either file is missing. See Agent Folder for the full convention.
16
Create index.ts
17
Create your entry point with the following code. This is the complete minimal app:
18
import { agentFrom, createHeypi, runHeypi, slack, workspace } from "@hunvreus/heypi";

const app = createHeypi({
  state: { root: "./state" },
  adapters: [
    slack({
      botToken: process.env.SLACK_BOT_TOKEN!,
      appToken: process.env.SLACK_APP_TOKEN!,
    }),
  ],
  agent: agentFrom("./agent", { model: "openai/gpt-5-mini" }),
  runtime: { root: workspace("./workspace") },
});

await runHeypi(app);
19
What each part does:
20
Config keyPurposestate.rootDirectory for SQLite database, admin material, and session filesadaptersOne or more platform connectors—Slack here, but Discord/Telegram/webhook work the same wayagentLoads identity, rules, and model config from the agent folderruntime.rootSandboxed workspace root for file and shell tools
21
runHeypi(app) starts the app and installs SIGINT/SIGTERM handlers so the process drains in-flight turns and shuts down cleanly. Press Ctrl+C to stop it during development.
22
Run the Agent
23
Compile and run:
24
# If using tsx / ts-node
npx tsx index.ts

# If compiled to JavaScript
node index.js
25
Invite your Slack bot to a channel and send it a message. Heypi will create a thread, route your message to Pi, and stream the reply back. SQLite state is written to ./state/heypi.db and the sandboxed workspace lives in ./workspace.
26
Use heypi check to verify your Slack credentials and bot scopes before running the app for the first time. See CLI for the full command reference.
27
(Optional) Add Approval Flows
28
For any tool call that could be destructive—deploying code, paging a service, deleting files—add an approver list. When a tool with confirm defined is invoked, Heypi pauses the turn and posts an approval prompt with native Slack buttons. The turn resumes only after an approver clicks Approve.
29
const app = createHeypi({
  state: { root: "./state" },
  adapters: [
    slack({
      botToken: process.env.SLACK_BOT_TOKEN!,
      appToken: process.env.SLACK_APP_TOKEN!,
    }),
  ],
  agent: agentFrom("./agent", { model: "openai/gpt-5-mini" }),
  runtime: { root: workspace("./workspace") },
  approval: {
    approvers: ["U123456"], // Slack user IDs of people who can approve
  },
});

await runHeypi(app);
30
For production deployments, also configure allow on the adapter (to restrict which channels can trigger the agent), an explicit runtime.justBash.network policy, and a named approval.approvers list. Running without these in a public Slack workspace is not recommended.

​
What’s Next

You have a running Slack agent with a sandboxed workspace. From here:
  • Agent Folder — Add skills, extensions, and dynamic context providers to the agent folder.
  • Tools & Approvals — Write custom tools, configure commandConfirm allow/block rules, and test approval flows.
  • Adapters — Add Discord, Telegram, or webhook adapters alongside Slack.
  • Scope & Memory — Enable persistent model memory scoped to users or channels.

Build docs developers (and LLMs) love

Get started for freeTalk to us