Get started on Node

Run Chickpea on your own Node host, connect a Slack app you own, and get a first reply from an Agent.

By the end of this page Chickpea is running on your own Node host, installed in your Slack workspace through a Slack app you own, and has answered a message in a thread.

Prerequisites

Node 24.x, minimum 24.20.0. The package engine range is >=24.20.0 <25; .nvmrc pins 24.20.0 for development, builds, and verification. Run nvm install && nvm use. Later Node 24 updates are supported; other majors are outside the support policy.
An HTTPS address Slack can reach. Chickpea builds the Slack app manifest from the origin you open Admin on, and that origin must use HTTPS. Slack posts events to <origin>/channels/slack/events.
A Slack workspace where Slack lets you install apps. Slack’s own app policy decides who may install. Chickpea does not require you to hold Slack’s Owner or Admin role.

Agent handles (@support and the like) need a paid Slack plan and a workspace policy that lets members create user groups. You do not need either for the first reply; the Agent that answers first is @Chickpea, the app itself.

Steps

Clone and install

git clone https://github.com/pejmanjohn/chickpea && cd chickpea
npm ci

Generate the signing secret once

export CHICKPEA_AUTH_SECRET=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')

That is 32 random bytes, the deployment’s stable internal signing authority. Preserve the value across restarts and never regenerate it on each start.

Mint the private setup link

Pass the URL your deployment answers on.

npm run setup:link -- https://your-chickpea.example

It prints two non-secret verifier values and the link itself:

CHICKPEA_SETUP_CAPABILITY_DIGEST=<digest>
CHICKPEA_SETUP_CAPABILITY_ISSUED_AT=<milliseconds>

https://your-chickpea.example/admin/setup#setup=<capability>

Export both variables. The link expires 24 hours after minting; run the command again for a fresh pair. Keep the link out of logs and source control.

Start the server

export CHICKPEA_SETUP_CAPABILITY_DIGEST=<digest>
export CHICKPEA_SETUP_CAPABILITY_ISSUED_AT=<milliseconds>

npm run dev

State defaults to SQLite files. npm run dev is the development server; production runs the built dist/server.mjs entry point under a supervisor.

Open the link and use your own Slack app

Open the private link in one tab, on that HTTPS origin. The setup page offers Add to Slack first. On Node, open Use your own Slack app instead and take that lane: the shared gateway path does not yet have the durable event admission Cloudflare deployments give it.

Generate a Slack App Configuration token, paste it, and choose Create my Slack app. Chickpea creates one app from its reviewed manifest and does not store the token. Choose the workspace in Slack, review the requested bot permissions, and select Allow. Back on the setup page, verify the Events URL, then select Become the first Owner with Slack. There is no password.

Choose a provider and a model, then try it

A fresh Node install seeds no Agent of your own and has no keyless model, so the model step decides what answers you. Anthropic, OpenAI, and OpenRouter take an API key here. Workers AI needs CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID, because the keyless binding exists only inside a Worker.

Then, in Slack, open a direct message with Chickpea and ask it for a first teammate, for example Hi Chickpea. I'm on the marketing team. What's a good first teammate for us? with your own team in place of marketing. A message that mentions @Chickpea in a channel it has joined counts as well. The setup page waits for the reply.

You should see

A reply from Chickpea, posted under its own name and avatar, in the DM or in a thread under your channel message. Setup is complete only after a real delivered reply; nothing earlier counts.

Limits

No scheduler. Node keeps inspection and shutdown controls for schedules but runs no timers, and rejects create, edit, resume, and run now as unsupported.
No coding sandbox. Node installations always use the standard in-memory bash sandbox and never touch the host filesystem or host git and SSH.
Single-host SQLite. Run one process per state directory. Multi-instance Node needs a shared state service.

Next steps

Node: state paths, supervision, backups, and upgrades for a production Node server.
How Chickpea works: what happened between the mention and the reply, and the layers underneath.
Handles and channel grants: handles, channel grants, and what publishing an Agent hands a channel.