# First setup

From an empty server to a working AI team. The steps follow the screens in order.

## 1. The first account (setup token)

The person who installs Lumate makes the first account. From 2.16.0 each person signs in with their **email**
(accounts made before keep their username).

1. **The server edition:** open the **link the installer printed** at its end. It carries the setup token, so you
   type only your name, your email and a password (at least 10 characters). Lost the link? The installer printed the
   token too, and `sudo grep SETUP_TOKEN /opt/agentx/.env` shows it: open the address and type it.
   **Lumate Local:** there is no token: the first-run window makes the first account.
2. **Activation:** an install given a licence key at install (`--key`) is already activated: nothing is asked. Without
   one, the same form asks the company's name once, and your OXS account opens with **the same email and password**:
   you only type the six-digit code OXS emails (a new account starts a 14-day trial). A licence key or an offline file
   work too; see [Licensing](/docs/licensing#activating). If the email already has an OXS account with another password,
   Lumate says so and asks for that one.
3. **Who will set up the company?**
   - **I will:** you go on to the company's set-up below.
   - **Someone else:** type the manager's email. Lumate makes a link for them (7 days, once); copy it and send it. The
     manager makes their account with it and sets up the company. You are **not** a member of that company: Lumate
     does not show you its customers, messages or calls (the server's backups still hold them, so keep those, and who
     can reach the server, safe). Your place is the **Server page** (status, diagnostics, updates, backups, the licence
     and that link; see [The Server page](/docs/agents#the-server-page-from-2160)).

The token works only until the first account exists. This first person is the **instance admin**.

## 2. The company (onboarding)

The company's set-up has three steps, and asks each thing once:

| Step | What you enter |
|---|---|
| **Company** | Its name (filled in from your licence's account), its website (Lumate reads it to learn what the company does; optional) and time zone (for example `Asia/Dubai`: every schedule, call hour and report uses it). The task prefix (2–6 letters, used in task references such as `RIC-12`) is suggested from the name. |
| **Departments** | What the company does: its departments (**Real estate**, **Any business**, **Recruiting**, as many as it has teams; the first is the primary) bring their teams, contacts and pages, and its country (the United Arab Emirates, Türkiye or another country) the calling rules. **Create company** makes it. Both can be changed later in Settings → Departments (see [Departments and countries](/docs/tour#departments-and-countries)). |
| **Connections** | Claude and the OpenAI key on one screen, each saying whether it works. On the server edition, the company's Claude key or token (or `sudo agentx claude-login` on the server); on a server built from source, a runner key is made here. The OpenAI key is what calls need. You can skip both: the dashboard keeps saying what is missing until they are there. |

Then the set-up interview opens once Claude answers: Lumate asks about the company and proposes its departments,
agents and apps (see [Setting up with Lumate](/docs/tour#setting-up-with-lumate-from-2110)). It already knows
the departments and the website you gave, and does not ask them again. Lumate Local's first-run window asks for
departments only when you press **Choose departments yourself** (or a bundled team package names them).

## 3. Connect Claude (the runner)

The runner uses the company's own Claude: an Anthropic API key, or a Claude account's login token.

- **An Anthropic API key (recommended for businesses):** commercial terms, and the data is not used for training. Make
  one in the Anthropic Console.
- **The company's Claude account:** on the server edition, `sudo agentx claude-login` signs it in on the server (see
  [The server edition](/docs/install-server#what-runs)). A Claude account's long-lived token works too: on any computer
  with Claude Code, sign in with the **company's** Claude account and run `claude setup-token`; it prints
  `sk-ant-oat01-…`.

Where it goes:

- **The server edition:** Settings → Runners → **Claude for the runners** (owners and admins; kept sealed, never shown
  back), or `sudo agentx claude-login`. The runner sets itself up once the first company exists.
- **Lumate Local:** the first-run window's Claude step, later Settings → General → Claude. The runner is part of the
  app.

Settings → **Runners** shows the runner as online within a few seconds. You can make more keys there, for example for a runner on another PC, and revoke them.

Test it: open **Chats → Lumate** and write "Hello, what can you do?". A reply in a few seconds means the runner works.

## 4. Invite people

**Settings → Members:**
1. Choose a role (**admin** or **member**) and type the person's **email**. Each link is for that person only, works
   once and expires after 7 days. With Settings → Email set up, Lumate emails it (you can copy it too); otherwise copy
   the link and send it. The person confirms their email once (their first page offers it, or Settings → Your account
   → Email), so **Forgot password?** works for them.
2. The person opens it, gives their name and a password, and signs in with that email from then on. If the email
   already has an account here, they sign in and join with it: nobody gets a second account. They then see a short
   hello with what is theirs (their desk phone's extension), never the company's interview.
3. Change roles or remove people on the same page. At least one owner always remains.

| Role | Can |
|---|---|
| Owner / Admin | Everything in the company: settings, secrets, numbers, members, WhatsApp, the browser rules, agent permissions |
| Member | Daily work: chats, tasks, customers, appointments, messages, listings |

## 5. Voice (OpenAI)

1. **Settings → Secrets** → add `OPENAI_API_KEY`: the company's OpenAI key. Its value is encrypted, never shown again, and never given to agents.
2. **Settings → Voice:**

   | Setting | Meaning |
   |---|---|
   | Voice model | The real-time voice model |
   | Backend model | The model behind the voice's tools |
   | Thinking | How much the voice reasons |
   | Talks with you in | The language the voice uses with your team |
   | Calls in | The language it uses on customer calls |

3. Each agent has a **Voice** tab: its voice and how it speaks.

Test it: open an agent's chat and press the microphone, or go to the **Playground**.

## 6. Phone numbers (optional)

Follow [Phone and Asterisk](/docs/phone):
- the OpenAI project id;
- the webhook secret (`OPENAI_WEBHOOK_SECRET`);
- the numbers, and which agent answers each;
- the transfer number;
- for outbound calls, the trunk and `SIP_TRUNK_PASSWORD`.

## 7. The customer board

**Settings → Board:**

| Setting | Default | Meaning |
|---|---|---|
| Hand to the manager after this many unanswered calls | 2 | The card moves to "For the manager" |
| Minutes before calling again | 120 | When a "No answer" card is due again |
| Daily report time (company time) | 19:30 | When the coordinator writes the day's report |
| Who takes appointments by default | — | The person new appointment requests go to |

To try the board right away: **Customers → ⋯ → Add sample customers** adds 25 sample customers. Remove them later from the same menu.

## 8. Your notification phone

**Settings → Your account** → "Your phone for notifications". While WhatsApp is linked, these notifications also arrive on WhatsApp:
- hand-offs ("Raj needs you");
- appointment requests;
- the daily report;
- new WhatsApp messages (at most one every 30 minutes per customer).

## 9. WhatsApp (optional)

Settings → **WhatsApp** → Link with a QR code (or a pairing code). Use a dedicated number. See [WhatsApp](/docs/whatsapp).

## 10. Office browser (optional)

1. Settings → **Browser** → download the extension and install it on the office PC.
2. Add the CRM to the allowed sites.
3. Switch on **Can use the office browser** for the agents that need it, in each agent's Settings tab. Agents made from the real-estate template (Lumate and the Researcher) have it already; agents you made earlier need it switched on.

See [Office browser and listings](/docs/office-browser).

## 11. Skills and knowledge

- **Skills:** the built-in catalog by category. Add skills to the company and give them to agents. Importing from GitHub is also possible.
- **Knowledge:** what the agents learn shows up here, with its source.

To teach an agent, just tell it ("Our office closes at 6 on Fridays") or share a file (price list, brochure). It remembers.

## Checklist

- [ ] HTTPS works and `SESSION_SECRET`, `SECRETS_KEY` are set
- [ ] First account and the company exist; the template's agents are there
- [ ] The runner is online and Lumate answers in a chat
- [ ] Members are invited with the right roles
- [ ] `OPENAI_API_KEY` is saved; a talk with an agent works
- [ ] Board settings and the default appointment owner are set
- [ ] Optional: numbers, WhatsApp, the office browser