Quickstart

This walkthrough takes you from a fresh platform install to a working department agent in your Brand's Teams workspace in about fifteen minutes. By the end you'll have a Brand row, a Tenant under that Brand, a Brand-Owner who can sign in via their own Microsoft Entra tenant, and a sales agent answering DMs.

Prerequisites. An Aroovo deployment that you can sign into as platform-superadmin (the Owner of the aroovo Brand). You'll also need an Entra tenant id + a Bot Framework app registration for the Brand we're onboarding — both can be paste-in from the customer once they exist.

1. Sign in to the operator console

Open https://agents.aroovo.tech/ (or your platform deployment's console URL). The MSAL flow takes you through the Aroovo Entra tenant; once authenticated you land on /agents as platform-superadmin.

If this is the very first sign-in on a fresh deployment, the boot hook will have created a single aroovo Brand and an appLockr Tenant under it. Both are sacred — leave them alone.

2. Create the Brand

Navigate to /admin/brands and click Create Brand. The form asks for:

  • slug — lowercase URL-safe identifier, e.g. acme-agency. Used in fallback sign-in URLs (/b/<slug>/sign-in) before DNS is wired.
  • name — display name, e.g. Acme Agency.
  • primaryDomain — optional. Set to the hostname the Brand will eventually live on (e.g. agents.acme.com); we DNS-verify it before the hostname-routing middleware activates.

Submit. You're back on the Brand list with the new row in active status. Behind the scenes the platform created a Brand-scoped row in the encrypted secrets vault and reserved the slug.

3. Configure the auth provider

Click into the new Brand and open the Auth provider tab. Aroovo ships four first-class OIDC providers — pick the one the Brand's customers use:

  • Microsoft Entra — paste entraTenantId + entraClientId. Required scopes: openid, profile, email.
  • Google Workspace — paste the OAuth client id and the hostedDomain (e.g. acme.com) so sign-ins from outside the domain reject.
  • Okta — paste the issuer URL + client id; we discover JWKS via .well-known/openid-configuration.
  • Auth0 — paste the tenant URL + client id + audience. Audience is enforced post-validate to keep tokens intended for other Auth0 APIs out.

See Concepts — BYO identity for the full provider matrix and How-tos — Set up BYO Entra for a click-through.

4. Invite the Brand-Owner

From the Brand detail page open Owners and click Invite. Type the Brand-Owner's email (it must be in the same identity-provider directory you just configured), submit, and the platform issues an invite. The Brand-Owner signs in via the Brand's own IdP and lands on /admin/tenants scoped to this Brand.

From this point onwards every step can be done by the Brand-Owner instead of you — the platform-superadmin role is no longer required.

5. Create the first Tenant

As the Brand-Owner, open /admin/tenants/new. The wizard is three steps:

  1. Identify the tenant. Pick a slug (e.g. acme-customer-1) and a display name. Tenant slugs are unique within a Brand, not across the platform.
  2. Pick a team preset. The platform ships five presets (marketing-agency, sales-b2b, tech-services, ops-coo, support-only) plus full-stack (all 28 agents). See ADR-006 for the preset taxonomy.
  3. Provision MCP. Paste the customer's Zapier MCP URL (Pro plan, ~£20/mo). The Aroovo runtime bootstraps the connection and probes the tool list.

Submit. The platform writes the Tenant row, seeds the agents for the chosen preset, writes the McpServer row, and HMAC-signs the first audit entry for the new tenant.

6. Onboard the agent into Teams

The Brand-Owner registers a Bot Framework app in their own Microsoft tenant (one per agent department — see ADR-003 §3) and pastes the appId + appPassword into the agent's settings. The platform side-loads the Teams manifest under /appPackage; the Brand-Owner uploads it to their Teams admin centre and the bot becomes available to their users.

Send a DM to the sales agent: “Hi, what can you do?” The agent loop dispatches to the configured provider (Anthropic by default), the response streams back through the Bot Framework, and a new audit entry is written into the chain.

Shipped 2026-05-25. Everything above is live on agents.aroovo.tech today. The roadmap (Slack ingress at public-beta parity, Discord ingress, the no-code visual builder, the external OpenClaw runtime) is in Changelog.

Next steps