Helpin
Dark mode
AI providers & knowledge search

AI providers & knowledge search

Self-hosted Helpin always uses your own AI provider keys. Requests go straight from your server to the provider you choose, and Helpin never sees or bills that usage.

There are two separate things to set up:

What

Powers

Where you configure it

AI connections

Agents: Ask Agent, the support agent, planners, coding and review agents, and custom agents

Each workspace's Settings → AI

Knowledge embeddings

Semantic search across help articles, docs, and knowledge sources

A server key, or a workspace's OpenAI or OpenRouter connection

Supported providers

Provider

Agents

Embeddings

OpenAI

Yes

Yes

OpenRouter

Yes

Yes

Anthropic

Yes

No, because Anthropic has no embeddings API

OpenAI-compatible endpoints (self-hosted or private models)

Yes, once approved in the agent runtime configuration

No

Quick setup with the CLI

The install wizard can add one provider key for you:

helpin configure --dir /srv/helpin
# Choose: openrouter, openai, or anthropic, then paste the key (it isn't echoed)

A server key becomes a shared AI connection in every workspace, including new ones, so agents work immediately. Settings → AI shows it as untested until someone runs a test.

Tip: OpenRouter or OpenAI is the easiest single choice. One key covers both agents and knowledge embeddings.

Configure AI connections in a workspace

  1. Open Settings → AI.

  2. Add a connection for OpenAI, Anthropic, OpenRouter, or an approved compatible endpoint, and paste its API key.

  3. Create a shared AI profile that picks the model for each kind of work.

  4. Choose the profile as the workspace default.

  5. Select Test to confirm the connection.

People can also add personal connections in their own AI settings. A profile name on its own doesn't supply credentials: agents need a connected provider behind the profile.

Stored API keys are encrypted with AI_CONNECTION_ENCRYPTION_KEY. Keep that key backed up with your data.

Knowledge embeddings

Helpin looks for an embeddings source in this order:

  1. Server OPENAI_API_KEY, with optional OPENAI_BASE_URL and OPENAI_EMBEDDING_MODEL

  2. Server OPENROUTER_API_KEY, using openai/text-embedding-3-small

  3. The workspace's own shared connection: OpenAI first, then OpenRouter

The model must return 1,536-dimension vectors. The default, text-embedding-3-small, does. Because OpenAI and OpenRouter serve the same model, a workspace can switch between them without re-indexing.

When a workspace connects OpenAI or OpenRouter, Helpin indexes existing knowledge in the background. Without any embeddings source, search falls back to keyword matching.

Settings → AI shows which source is in use, for example "Using the server's OpenAI key".

Optional: ChatGPT connections

To let people connect with a ChatGPT sign-in instead of an API key, enable both settings and restart:

CHATGPT_CONNECTIONS_ENABLED=true
AGENT_RUNTIME_CHATGPT_ENABLED=true

Optional: external tools for agents (MCP)

Agents can use tools from external MCP servers you connect in Settings → External tools (MCP). For safety, servers must use HTTPS on public addresses. To allow an internal server, opt in explicitly:

AGENT_RUNTIME_MCP_ALLOWED_HOSTS=tools.internal.example.com
AGENT_RUNTIME_MCP_ALLOW_PRIVATE_NETWORKS=true   # only if the server is on a private network
AGENT_RUNTIME_MCP_ALLOW_HTTP=false              # keep HTTPS unless you have no alternative

Troubleshooting

Problem

Check

An agent doesn't respond

The workspace has a default profile with a connected provider. Then check the agent-runtime and agent-runtime-worker logs

"Semantic search unavailable"

No embeddings source is configured. Add an OpenAI or OpenRouter key

Embedding errors about dimensions

Your model doesn't return 1,536 dimensions. Use text-embedding-3-small

A compatible endpoint is rejected

The endpoint must be approved in the agent runtime's app configuration

Was this article helpful?