Skip to main content
HUMΛN

Deploying your first Companion instance

Goal: Go from zero to a live, embeddable Companion widget on any website — with server-side token management, org-scoped KB, and a ready-to-paste embed snippet.

Overview

Each Companion deployment is a record in companion_deployments. It carries:

  • A unique stable deployment ID (dep_…)
  • A surface label (e.g. customer-support)
  • A scoped delegation token minted on creation (never sent to the browser in proxy mode)
  • An allowed origins list for CORS

The proxy pattern keeps the token server-side. The widget uses agentsCallUrl to route through your backend, which looks up the token and forwards the call to HumanOS.

1. Create a deployment

CP UI

Go to Command Plane → Admin → Companion Deploys → New deployment. Fill in name, surface label, allowed origins, and optional prompt.

CLI

human companion deployment create \
  --name customer-portal \
  --surface-label customer-support \
  --display-name "HUMΛN Support" \
  --allowed-origins "https://portal.yoursite.com"

API

curl -X POST https://api.haio.run/v1/companion/deployments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"customer-portal","surface_label":"customer-support","allowed_origins":["https://portal.yoursite.com"]}'

2. Get the embed snippet

human companion deployment snippet customer-portal
# or:
curl https://api.haio.run/v1/companion/deployments/dep_abc123/snippet \
  -H "Authorization: Bearer $TOKEN"

Snippet output:

<script src="https://api.haio.run/cdn/companion-widget.js"></script>
<script>
  HUMAN.Companion.init({
    agentsCallUrl: window.location.origin + '/api/companion/ask',
    buildAgentInput: () => ({
      deployment_id: 'dep_abc123',
      surface_context: {
        surface: 'customer-support',
        page: window.location.pathname,
        page_title: document.title,
      },
    }),
    ui: { theme: 'auto', position: 'bottom-right' },
  });
</script>

3. Add the proxy endpoint to your host app

The widget POSTs to /api/companion/ask. Your server:

  1. Reads deployment_id from the body
  2. Looks up the companion_deployments record
  3. Validates the Origin header against allowed_origins
  4. Forwards to HumanOS with Authorization: Bearer {delegation_token}

See apps/website/app/api/companion/ask/route.ts for the reference Next.js implementation.

Set these env vars on your host:

COMPANION_DEPLOYMENT_ID=dep_abc123
HUMAN_API_URL=https://api.haio.run
INTERNAL_API_TOKEN=your_internal_token  # for fetching deployment records

4. Paste the snippet and verify

Paste the snippet before </body>. The Companion mote appears bottom-right. Click it — the chat panel opens. The Companion knows the current page (via surface_context) and your org's KB scope.

5. Rotate the token (optional)

human companion deployment rotate customer-portal

The old token is revoked in delegation_grants. The new token is stored server-side. The snippet URL is unchanged.

Next steps

← All guides