Self-hosting — Agent Brief

1. Confirm the target: Self-Host kit (`NEXT_PUBLIC_DEPLOYMENT_MODE=oss`). If they want hosted Humaner Cloud, stop and use the Cloud agent brief.
2. Deploy or run the dashboard (Node 20+, pnpm, PostgreSQL 16+ with pgvector, SMTP or console OTP, Anthropic API key).
3. Sign up → verify email → OSS onboarding: account type → website → business → invite → **required Unique system prompt** → launch (Helpdesk on).
4. Copy the public Agent ID from Agents → Integrations → YOUR_AGENT_PUBLIC_ID.
5. Optional: add knowledge sources in the dashboard Knowledge tab, or drop markdown into `data/knowledge/` (or crawl with `@humaner/into-markdown`). Hybrid RAG uses pgvector when configured; files are the fallback.
6. Embed Widget or React with `data-agent` / `agentId` = YOUR_AGENT_PUBLIC_ID and `baseUrl` = their dashboard origin.
7. Allowlist the site hostname. Verify chat + a forced handoff ticket in Helpdesk.

Quickstart: https://docs.humaner.io/oss/quickstart · A→Z in repo: SELFHOST.md · Cloud brief: https://docs.humaner.io/agent-brief · Self-hosting vs Cloud: https://docs.humaner.io/contributing/open-source-vs-cloud

Self-Host is a free customer-support starter kit. Operators write their own agent prompt (same idea as Humaner Cloud Unique), bring an LLM key, and run Helpdesk on their infrastructure under the Humaner brand.

• Included: Humaner auth/dashboard, org/team, Unique system prompt agent, open Industry Skills, hybrid RAG (pgvector when configured, markdown files otherwise), Widget / React / REST, Helpdesk (async handoff), API keys.
• You own: LLM API key, knowledge sources / files, prompt content, hosting, SMTP for sign-up email.
• Not included (Cloud-only): Core Skills, session memory, Agent Desk, runbooks, loops, live chat, collaborative Inbox, Polar billing, Ask Humaner.

• Prerequisites: Node.js 20+, pnpm, PostgreSQL 16+ with pgvector, SMTP (or SELF_HOST_LOG_VERIFICATION for local OTP), LLM API key.
• Repo: https://github.com/Humaner-inc/humaner

git clone https://github.com/Humaner-inc/humaner.git
cd humaner
pnpm install
cp apps/dashboard/.env.example apps/dashboard/.env.local

• Set `NEXT_PUBLIC_DEPLOYMENT_MODE=oss` (required — unlocks Self-Host plan + starter agent path).
• Set DATABASE_URL / DIRECT_URL, AUTH_SECRET, NEXT_PUBLIC_APP_URL.
• Set EMAIL_* (SMTP or Resend) — required for email/password sign-up OTP.
• Set ANTHROPIC_API_KEY for widget chat streaming (OPENAI_API_KEY optional for Helpdesk handoff).

pnpm --filter @humaner/dashboard exec prisma migrate deploy
pnpm --filter @humaner/dashboard dev
# Local default: http://localhost:3001

OSS `/onboarding` is not the Humaner Cloud wizard. There is no Polar plan step. The agent step requires a Unique-style system prompt (same storage as Cloud Unique: `character=CUSTOM` + `customCharacterPrompt`).

1. 1

   Sign up and verify

   https://yourwebsite.com/auth/signup → OTP from email or server console → land on onboarding.

2. 2

   OSS onboarding

   Account type → Website → Business (industry) → Invite (optional) → **System prompt (required)** → Launch. Helpdesk is enabled by default.

3. 3

   Copy public Agent ID

   Agents → your agent → Integrations. That cuid is YOUR_AGENT_PUBLIC_ID — the only value end users paste into site embeds.

4. 4

   Allowlist domains

   Widget settings → Allowed domains. Add the customer site hostname. Leave empty only for local testing.

With `NEXT_PUBLIC_DEPLOYMENT_MODE=oss`, chat uses the starter agent path: your Unique prompt + Industry Skills + hybrid RAG + BYO LLM. You do not need to implement a separate bot for the happy path.

• POST /api/v1/chat on your origin streams SSE token deltas.
• Handoff when the model emits the kit handoff signal (or widget escalate path).
• Optional advanced: replace/point the chat handler at your own runtime — still create Helpdesk tickets with escalate + handoff payload.

{
  "delta": "",
  "done": true,
  "escalate": true,
  "handoff": {
    "humanDesk": true,
    "urgency": "high",
    "conversationSummary": "Customer cannot access account after password reset."
  }
}

curl -N -X POST https://yourwebsite.com/api/v1/chat \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "YOUR_AGENT_PUBLIC_ID",
    "message": "Where is my order?",
    "sessionId": "sess_abc123"
  }'

Widget

<script
  src="https://yourwebsite.com/widget.js"
  data-agent="YOUR_AGENT_PUBLIC_ID"
  data-color="#18181b"
  data-position="bottom-right"
  async
></script>

React

npm install @humaner/react

import { HumanerChat } from "@humaner/react";

export default function SupportPage() {
  return (
    <HumanerChat
      agentId="YOUR_AGENT_PUBLIC_ID"
      baseUrl="https://yourwebsite.com"
      position="bottom-right"
    />
  );
}

Hosted link on your origin

https://yourwebsite.com/widget/YOUR_AGENT_PUBLIC_ID?open=1

• Create an org API key in the dashboard. Keep it server-side.
• POST /api/v1/chat on your origin with agentId + message; consume SSE.
• On escalate, POST /api/v1/handoff/ticket or let the widget handoff UI run.
• Contract shapes match the API reference; host is your baseUrl.

Report vulnerabilities to dev@humaner.io. Do not file public issues for exploitable findings.

1. Login / sign-up show Humaner Self-Host branding (same cream/dark chrome as Cloud).
2. Onboarding has no Polar plan popup; Unique system prompt is required.
3. Dashboard nav is Helpdesk-centric (no Inbox / Agent Desk / Loops / Ask Humaner).
4. Chat returns a reply from your prompt (+ knowledge if present).
5. Forced handoff creates a Helpdesk ticket; teammate can reply.
6. widget.js loads from the same origin; Agent ID embedded with data-agent.