@housecall Get started
Docs menu

Quickstart

@housecall is one container that connects to your chat platform, indexes your how-to docs, and answers questions with links to the page it used. You start from a small starter project; the engine comes from the @ithousecall/chat npm package.

A coding agent can do this setup for you: clone the starter, open it in Claude Code, Codex or Cursor, and ask it to follow how-to/SETUP.md. The steps below do it by hand.

You need:

  • Docker with Compose, and Node 24
  • An API key for an OpenAI-compatible model, OpenAI, or Anthropic
  • Your IT how-to docs as Markdown or text files, or a Google Drive folder or Confluence space
  • A Slack workspace where you can install apps, or just a terminal to try the console first

1. Create your project

Clone the starter:

git clone https://github.com/IT-Housecall/it-housecall-chat-agent.git my-it-agent
cd my-it-agent
npm install

Commit package-lock.json; the Docker build installs from it.

my-it-agent/
  config/config.yaml
  deploy/
  docs/
  src/main.ts
  .env.example

config/config.yaml holds your settings, docs/ your runbooks, and src/ the entry point and your code extensions. deploy/ has the Docker files and the Slack and Teams app manifests.

2. Add your secrets

cp .env.example .env

.env holds secrets only. Add your model key, which @housecall needs to start, and the two Slack tokens from Slack setup:

OPENAI_API_KEY=sk-...
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

3. Configure

In config/config.yaml, check the model block and keep Slack enabled. This file has no secrets, so commit it.

model:
  provider: openai
  id: gpt-6.1-sol

chat:
  slack: { enabled: true }

docs:
  sources:
    - type: local
      name: runbooks
      path: ./docs

4. Add your docs

The local source reads docs/, which starts empty. @housecall answers only from the docs you give it, so copy yours in, or set up Google Drive or Confluence instead:

cp -r /path/to/your/runbooks/. docs/

5. Start it

docker compose -f deploy/docker-compose.yml up -d --build
docker compose -f deploy/docker-compose.yml logs -f

@housecall indexes your docs in the background and connects to Slack. DM the app, or invite it to a channel and mention it:

@housecall How do I connect to the VPN?

Try it in your terminal

The console reads messages from your terminal and answers with the model in config/config.yaml. It needs the model key in .env, and no chat platform.

npm run console

The console ignores the chat: section. Each line you type is a message. When a tool asks for approval, type approve <id> or deny <id>.

Next steps