Deskhand
Docs menu

Quickstart

Deskhand 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 deskhand npm package.

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

Use the starter template on GitHub, or clone it:

git clone https://github.com/OWNER/deskhand-starter 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 Deskhand needs to start, and the two Slack tokens from Slack setup:

LLM_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_compatible
  base_url: https://api.openai.com/v1
  id: gpt-5-mini
  api_key_env: LLM_API_KEY

chat:
  slack: { enabled: true }

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

4. Add your docs

The local source reads docs/, which starts empty. Deskhand 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

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

@Deskhand 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