SimpleTwo

Language
Appearance
Version
Documentationdocs.simpletwo.ru

First-run setup

Paste the one-time bootstrap token from the server logs (or /data/bootstrap-token), then choose an admin password.

Data encryption key

One key decrypts this installation's message bodies. It is generated here, stored on this server outside the database's own volume, and printed on a sheet you keep — because a key that exists only on the server dies with the server.

Enter an existing key is for a reinstall onto a new server with the old database — that is what the printed sheet is for. Postpone leaves message bodies stored as plain text, which is a legitimate choice; the Settings page keeps saying so.
copied
The key is no longer on this page. Read the two groups off the sheet you just made.

Sign in

Break-glass sign-in

The coordinator's one local emergency account, for the day identity cannot sign anybody in. Every use is recorded in the audit trail and every administrator is told. The session lasts one hour and opens this console only.
Gateways
–
healthy / total
Active connections
–
client sessions
GEO zones
–
configured
TLS
–
Host load
–
1 min avg

Fleet

Every host and what is wrong with it. Counts of things that exist answer a question nobody has at 3am; this answers the one they do.
HostAddressRoleVersionsStatusReportedNote

Gateways

IDGEOGroupAddressLoadStatus

Click a gateway for load & connection history.

Create GEO

Server provisioning (gateways, messaging, Postgres) now lives on the Servers & deploys tab.

Gateway groups

Recorder classes for gateways. Mark those that reach the corporate network as corporate; then simply don't add them to guest/partner profiles' allowed gateways. A corporate group with a served whitelist below becomes a DMZ — its gateways forward ONLY these internal destinations and drop the rest (ADR-0006). Leave blank for an open corporate recorder.
GroupTypeDescription

GEOs

CodeNameCountryGroup

Gateways

IPv6 marks a gateway whose host can recorder IPv6. Clients capture IPv6 into the tunnel either way — leaving it outside was a leak — and drop it unless a gateway they selected is marked here, so a v6-only destination fails at once instead of stalling.
IDGEOGroupAddressLoadIPv6TransportsStatusActions

Rule lists

IDKindEntriesVer
New list

Profile

nameonactionmatch byvalue→ GEO

Preview routing

Version history

VersionDefaultRules

Groups / roles → profile

Maps a user role/group to a routing profile and the gateway groups it may use. Corporate recorder is separated simply by NOT ticking corporate gateway groups for guest/partner.
Group / rolePriorityProfileAllowed gateway groups

Installed servers

What is actually running, one row per host, grouped by role — click a role to fold it. Hosts install their own software and update themselves; Settings changes what a host should be and reaches it on its next poll, and the ⋯ menu holds its log, the configuration it wrote, and decommissioning.
Host nameAddressGEOLoad / RAM / diskTLSStatusActions

Add a host

How to lay this out

One private network, and every rule is explicit. All the hosts share it: postgres, messaging and calendar on one side of it, redis and the sfu nodes on the other, and nothing between them but rules this control plane writes. The database accepts only the messaging and calendar hosts, each as a /32 in pg_hba; the bus accepts only the services that dial it — the SFU nodes, the SIP bridge, the recorder — as a firewall rule on its own host. Both are re-applied on every state poll, so neither is a rule somebody has to remember to keep true.

HostPublic PrivateWhy
postgres— yes only the messaging and calendar hosts connect, each allowed as a /32; nothing reaches it from outside
messagingyes yes clients talk to it, it talks to the database
s3— yes object storage for attachments, avatars and recordings (ADR-0043): only the messaging and recorder hosts connect, each allowed as a /32 on 9000. Optional — without it attachments live on the messaging host's own disk, which means one host, one backup and no second messaging replica. Give the host a second, EMPTY disk and name it when you add the host: the platform makes it a ZFS pool for the objects, which is what makes a snapshot the backup. The alternative to the role is an endpoint the organisation already runs, in Settings → External stores
calendaryes yes calendars, their entries and the ways in (ADR-0038). Public because the readers that matter are not our client: Outlook refreshes an ICS subscription and a CalDAV client polls, both from outside and both by name. Beside messaging rather than inside it for the same reason — those reads must not share a process with the chat fan-out. It keeps its own database on the same postgres, with its own login, created for it automatically, and obtains its own certificate for the name you give it
redis— yes the coordination bus; no client ever touches it, and 6379 is open only to the services that dial it — the SFU nodes, the MCU and the recorder. That rule is its whole boundary, so a host with no ufw and no firewalld is refused rather than left reachable from the network
sfu ×2yes yes media and signalling are public; the bus is reached privately
turnyes — a relay talks to clients and to nothing of ours
gatewayyes DMZ only for corp recorder see ADR-0006; a geo gateway needs no private leg
support— DMZ, beside the coordinator the support bot's daemon (ADR-0031/0034): inbound only from the messaging host (signed webhooks on :8087), recorder to messaging, to GitLab and to the model provider; no client and nothing public ever reaches it. It holds its own provider key — the bot's webhook points at it, and it calls the model itself — so there may be several such hosts, one per case: different jobs, different knowledge bases, different keys. Each is bound to its case when it is enrolled. It also keeps the bot's knowledge base: it reads the product's repository and issues from GitLab (one archive request on first sync, then only what changed) so the bot can answer instead of only filing bugs — so its GitLab token needs read_api on that project, not just issue creation

The one rule that silently breaks calls. A private address must never be advertised to clients. “Private address” goes in the host’s private address field; the address clients use goes in node IP for an SFU. Put a private address in the second one and every call connects, carries no media and times out with nothing in any log.

Order. 1) postgres → 2) messaging → 3) calendar (then redeploy postgres once: the access rules are narrowed to those hosts’ /32 and cannot be written before the hosts exist — one redeploy covers both) → 4) redis → 5) sfu node A → 6) sfu node B → 7) turn. Calendar is optional and can wait; until a calendar host exists the clients hide their calendar screens rather than offering buttons that fail, which is the honest answer for a deployment that has not stood one up. A second SFU node without redis is refused: two nodes without the bus each keep their own room table, so two people “in the same room” on different nodes cannot see each other and nothing reports a problem.

Sizing to start. postgres 2 vCPU / 4 GB / 40 GB SSD · messaging 2 vCPU / 4 GB (attachments live on its own disk unless an object store is configured) · s3 2 vCPU / 4 GB and a second, empty disk sized from the media rather than from the people — about 1 TB per 1000 people per year of chat files, doubling if meetings are recorded routinely; it is disk-bound, and neither CPU nor network is the limit at that size · redis 1 vCPU / 1 GB (it holds room routing, not data) · each sfu 4 vCPU / 8 GB and real bandwidth — an SFU forwards every stream to every participant, so the uplink is the limit long before CPU · turn 2 vCPU / 2 GB, bandwidth-bound for the same reason · recorder 4 vCPU / 4 GB per concurrent recording plus scratch disk — the one media role limited by CPU rather than bandwidth, since it records by driving a headless Chrome. It scales with recordings, not participants, and takes its jobs from the bus, so one worker serves the whole pool: put it on an SFU host for a small install and on its own machine once recording is routine · calendar 2 vCPU / 4 GB — it holds no files, and its whole working set is rows in postgres; sized for the polling rather than for the people, since a subscribed Outlook and a CalDAV client come back on their own schedule whether anybody is looking or not · support 1 vCPU / 2 GB / 10 GB — two small Go daemons plus the knowledge base, which is held in memory (a repository the size of this one is ~6k chunks ≈ 100 MB with embeddings, and its file on disk is the same order); searches are index-backed and answer in under a millisecond, so the single core is the model provider's problem, not ours. The thinking happens provider-side, so nothing here grows with chat load the way media hosts do. Deploy it last: it needs messaging live and the Support provisioning (Settings) run, in either order.

Ports the deploy opens for you (host firewall, when ufw or firewalld is present): sfu 7880/tcp, 7881/tcp, 50000-60000/udp · turn 3478/udp+tcp and 49152-65535/udp · messaging its listen port, plus 443 when it terminates its own TLS · calendar its listen port (:8085 by default). Redis is the exception: 6379 is opened only to the addresses that dial the bus — the SFU nodes, the MCU, the recorder — never to the world, and on a host with no firewall tooling the deploy fails rather than leave a database reachable. With one private network that rule is the only boundary the bus has, so it fails whatever address the bus listens on.

Certificates. messaging obtains its own (autocert) for the hostname you set under Settings. Calendar does the same, and for the same reason it is allowed to: it is our own Go service, so it can run ACME itself. An SFU cannot — that is the whole reason edge exists — and the difference is worth knowing when a role seems to be missing a certificate button. Subscription links are built from the calendar's name, so it must already resolve to the host before the certificate can be issued. An SFU needs TLS in front of 7880 for iOS to connect at all, and an enrolled host no longer needs you to arrange that: the coordinator runs the ACME order and the host serves the one challenge file, because the name points at the host while the account key stays here. The edge front then terminates 443 and proxies every path to 7880 — every path, since moderation arrives on the same host and port as the client’s WebSocket, and a front that forwards only the socket breaks mute and remove while calls still look fine.

Add a host

The host joins by running one command on itself (ADR-0025) — no SSH key here, no inbound reachability needed, so a machine in a private network works the same as a public one. The invitation is single-use and expires in an hour; the host exchanges it for its own credential and then pulls what its role needs. Guide: deployment
SSH key (only needed for "run it for me")
Used once and forgotten — it is never stored. Leave empty to use the coordinator's own key.
The token is not stored — only its hash — so this command cannot be shown again. Generate another if it is lost.

Provisioning log

One row per host, newest attempt first; a +N marks how many earlier attempts that host had, whose history is in this row’s log. Hosts that pull their state show Settings instead of a redeploy, because there is nothing to push to them.
RoleIDHostGEOVersionStatusAgent seen

Active sessions

UserDeviceGatewayExpires
CPU load
–
Memory
–
Disk
–
Uptime
–

Host logs

Asks a host for the last lines of one of the units it installed. Pulled on request rather than streamed, so an idle fleet costs nothing; the host caps the size and removes secrets before sending. The answer arrives on its next poll — usually within a minute.
pick a host and a unit

Coordinator logs

Client sessions

Per-client monitoring — SW version, live per-location quality (traffic light), error count and online status. Aggregated from client telemetry + active sessions.
UserDeviceVersionQuality (per location)ErrorsLast seen

Client diagnostics

Recent client-reported events (connect lifecycle, errors, connection metrics). Newest first.
TimeUserLvlEventMessageGEO/GWApp/OS

Extended client debug

Remotely turn on verbose xray logging and log streaming for a specific device or employee — no app update needed. Takes effect on the client's next connect. Use the device id / username shown in Client diagnostics above.
Global (all clients): ·

Monitoring

Metrics, logs and traces of every host, in Grafana on the monitoring host (ADR-0048). The console only lets you in: the button hands your browser a one-time pass, and the interface itself runs there.

Your own receiver

Send telemetry to a system you already run, over OTLP/HTTP (ADR-0048 §3a): Prometheus 3 takes metrics at /api/v1/otlp/v1/metrics (start it with --web.enable-otlp-receiver), Loki 3 takes logs, Tempo or Jaeger traces. Leave a field empty and that signal is not sent. With a monitoring host its gateway sends the copy; without one, every host with a private address sends directly.

    

    
Audit log

      

      

      
TimeActorActionDetail

    

  


  
  
  

    

      
Users

        

      

        
        
        
        
        
        
        
        
        
      

      

        
        
        

          Username
          Number
          Name
          Email
          Source
          Roles
          Groups
          Invited by
          Expires
          Status
          Actions
        

      
    

    
    

      
Rooms & devices

        

      
Bookable resources (ADR-0036 phase 5, ADR-0038 §1): a meeting room or a shared device is an account that never signs in, and it owns a calendar the same way a person does — which is what makes it bookable and what a free/busy grid reads. A panel is the screen on its wall: it authenticates to the calendar service with a credential of its own, polls that room's schedule, and holds no session — so a corridor full of panels keeps working through a coordinator outage. Issue one per screen and give it the wall's name: the label is what rotation replaces, so re-issuing under the same label kills the credential that screen was using. The address is shown once — only a hash is stored, and a lost panel is re-issued, never looked up. Guide: meeting rooms

      
      

        
        
        

          NameLoginNumberKindSeatsLocation
          PanelsSIPLast callActions
        

    

    
    

      
Roles

        
RolePermissionsDirectory

        

      

      
Single sign-on (OIDC)

        
        

        

      

    

    

      
Groups → roles

      
Groups and their membership are identity's (ADR-0047 §8a): they are created, deleted and filled in identity's console. What stays here is the platform's access control — which roles a group's members get (user → groups → roles → permissions). A group's routing profile is in Routing → Groups.

      

      
GroupKindRolesActions

    

  


  
  

      
Numbering & routing (telephony)

        
Which trunk a dialled number leaves through, what is presented as the caller, and what is refused (ADR-0007 §C). Written here, stored as one versioned document, and pushed to the comms plane as a snapshot — never asked per call, because a control plane in the path of every telephone call is what service-roles.md §7 forbids.  Guide: telephony

        
Two things here are the opposite of what you may expect, and both are deliberate.

        Order is declared twice. Rules are read top to bottom and the first one that matches wins — the rest are never looked at. The trunks inside a rule are tried in the order written. Teams randomises the gateways inside a route and documents that primary and backup therefore cannot be expressed at all; a cost difference between two trunks is the whole reason this feature exists, so ours is ordered.

        Unknown denies. An account with no office is a third state, not a default one: a rule locked to a site refuses that caller rather than treating them as head office. The fix is to give the account an office, not to loosen the rule.

        
Internal numbers

        
The range new people and rooms are numbered from, and the leading digits no person may have (ADR-0007 §2). The default is 2000–7999 with 8 for services, 9 for an outside line and 0 for the operator. An organisation migrating from Skype for Business may adopt its own plan here before its people arrive. A plan that would reserve a number somebody already holds is refused, with the holders named.

        

          

          

          

        

        


        

          

          
One control that stops outbound telephony for the whole organisation, audited, reachable by whoever is on call. It exists for the person looking at a graph at three in the morning who has to stop the bleeding before understanding it. Saving the tables below never lifts it.

        


        
Countries

        
The dialling context a number is read in, and the place one decision lives: outgoing dialling exists in a country only after somebody has answered for that country in writing. Where refusing an emergency call is not permitted, we do not offer outgoing telephony there at all — so this is a deployment answer, not a per-user permission, and an unanswered country simply has no dialler.

        
ISOCodeTrunk pfxIntl pfxNumber lenDiallingWritten answer

        


        
Sites

        
An office, as an administrative fact about an account — never derived from the network. This product ships a VPN client, so a client's network position is a statement about a tunnel exit and not about a person; Webex says the same from the other side. The main number is what somebody with no direct number of their own presents.

        
IdNameCountryMain numberTimezone

        


        
Trunks

        
The peers. Digits is a property of the peer, not of the number: normalise to +E.164 once, then hand each trunk the shape it asks for. Numbers is the registry of what may be presented on this trunk, one per line as +7495… | evidence — the carrier's assignment or the letter of authority. A carrier that catches you presenting anything else rewrites it at best and refuses at worst. Calibrated means this carrier's SIP codes have been measured: until they are, the interface shows five call states instead of nine, because a carrier that answers "nobody picked up" with 486 would make it say «Занято», and a person who reads «Занято» stops trying.

        
IdNameSiteDigitsPrefixNumbersMaxState

        


        
Dial rules

        
Match is a regular expression over the normalised number and must be anchored — an unanchored pattern matching in the middle of a number is a bill nobody can explain, so it is refused when you save. From is which offices this rule is for, empty for any. Trunks are tried in the order written, comma separated. Caller ID is ddi, main, withheld or literal:+7495…. Lock means the rule may only use trunks belonging to the caller's own office and may not fail over out of it; hatch is the named exception that lets an account with no office use it anyway. Failover is allowed only before the callee's network has told us anything about the callee — once their phone has rung, another carrier only rings it a second time.

        
OnIdMatchFromTrunksCaller IDLockHatchFailover

        


        
Emergency numbers

        
A separate plane, not a rule. These are matched first, on the digits exactly as typed, before any normalisation — and they are refused, never routed. An emergency call is only useful if it reaches the service for the place the caller physically is, carrying an address a dispatcher can act on; we cannot establish that address, so a 112 dialled in one city and leaving through a trunk in another sends an ambulance to the wrong building. A half-working 112 is worse than an absent one. Emptying this table does not enable emergency calls — it lets those numbers fall through to ordinary routing, which is the one outcome this refuses.

        
DigitsNote

        


        
Spending limits

        
The attack this exists for is a revenue-share fraud: an attacker with a deal on a premium international range pushes as many minutes through your account as it will take, at night and at weekends, and the bill arrives a month later. Destinations are an allowlist by country code, never a blocklist — there are more premium ranges than anyone maintains — and an empty allowlist permits nothing. The counters live in the comms plane and are checked before any call is placed; the numbers are set here. A requested callback counts against all of this: it is an outgoing call at the organisation's expense to a number the caller chose, and a convenient option cannot be a way around a spend limit.

        

          

        

          

          

          

        

          


        

        

          
          
          
        


        
Test box

        
Type a number and an account, and see which rule matches, which trunks would be tried in which order, what would be presented as the caller, and the exact digits the first trunk would receive. Nothing is dialled. This exists because a dial plan is the one piece of configuration where trying it costs money and wakes a customer up — an administrator who has to place a real call to find out what their own rule does will not check, and the rule they did not check is the one that routes payroll's calls through the wrong country. Ask about an account rather than an office where you can: an account whose office was never set is exactly the fault this finds.

        

          

          

          

        

        

      


      
      
MCU: mixing & keypad (SIP endpoints)

        
A room telephone has one video window and no interface of ours in it — so which participant it shows, how long the picture waits before following a new speaker, and what its keypad does are the whole product on that device. Saved here, carried to the MCU with the desired state the host already polls, and applied without restarting it: an edit made while a room is in a meeting lands a minute later instead of ending the call. Guide: meeting rooms

        


        
        

        

        
default applies to every endpoint; by_device overrides it for one, keyed by the device's id in the registry of who may call (not the room's name, and not what the endpoint says about itself). Known settings: layout (speaker|grid), floor_ms, linger_ms, mix_voices, max_height, max_fps, content, allow_pin, allow_layout, keys. Keypad defaults: *1 mute, *2 hand, *3 pin, *4 layout, *0 help, ## leave — an empty value removes a key, and a key bound to an action the device is not allowed (allow_pin, allow_layout) is not bound at all rather than pressed and refused.

        Out-of-range values are clamped, not refused: the MCU applies what it can and reports what it changed in its own health, because a room that mixes slightly differently is better than a room that does not answer. A key this build does not know is named there too — the one failure a settings file must never have is doing nothing in silence.

        
        

        

          

          

          

        

        
Calls right now

        
Every call on every MCU host, as the host itself last described it: which room is calling into which meeting, who is on its screen, who holds the content floor, and every sentence about what the call is doing differently from what was asked. It is the answer to «why does this room never see Ivan» without a packet capture. Refreshed every few seconds while this tab is open.

        

      

  


  

    
    

      
Federation policy

        
Who this installation is on the wire, and which organizations it exchanges messages with. Federation is a contract between two administrators: each side lists the other, and a one-sided setup is refused by the other side — which is correct behaviour, not a misconfiguration. There are no shared secrets to exchange: each installation signs with its own key and publishes the public half, so parting company is a line removed from a list. Guide: federation

        
        
        
        
        

          

          

          

        

        
How the door is held. Today it is held by this list and nothing else — a message is accepted when the sending domain is on it, its signature verifies, and we have not seen that message before.

        

          
By this listin force

          
By approvala partner asks, you approve — designed, not built (it needs a pending state and an audited approve/deny, not a checkbox)

          
Open to anyonerefused until per-peer rate limits and an abuse rota exist — a flag that turns this into an open relay is a one-line change with a company-sized consequence

        

        

        

        

      

      
Offline depth

        
ADR-0020. How much history a client puts on the device at its FIRST sync, so it opens without a connection. The people list, the conversation list and the calendar list are synced whole and need no number — their size is bounded by the organization. Message history is not, so it is fetched by a stated depth: the newest N conversations, M messages each. Bigger means more works offline and a longer first sign-in; the clients cap it at 200 × 500 whatever is set here. Leave both blank and every client uses its own documented default (20 × 50) — which is a different thing from setting 0, and the storage screen on the device says which of the two it is. Applies at the next sign-in or fresh install; devices already warmed keep what they hold.

        
        

        
        

        

        

        
 

      

    

  

  

    
    

      
Bots

        

      
Non-human identities (ADR-0014/0021), authenticating to messaging with a scoped bot token. A service bot belongs to the tenant. A personal bot belongs to one user and is one of two things: an assistant — a session of that person, which reads what they read and writes in their name — or a worker, which acts under its own name and sees only the conversations it was added to. The owner is shown beside every personal bot, which is what makes free naming safe. Bots hold no admin role — a bot cannot sign in, so a role would be enforced nowhere; scopes and the conversation allowlist are what grant one anything. Rotating a token keeps the owner, the entity and the fence. Whether an assistant may act for its owner at all is a tenant-wide switch, in Settings → Acting on behalf of a user; with it off the tenant has no assistants, only workers.

      
      

      
UsernameNameKindGrantsWebhookStatusActivityLast seenCreatedActions

      
    

    

      

        
Automations

          

        
Server-side rules (ADR-0014): a trigger (bot mention / keyword / schedule / webhook) runs linear steps; a step with an approve gate pauses until an allowed human reacts ✅ in the chat. Every rule speaks as a bot (as) and posts only into rooms that bot is a MEMBER of — so the member list answers "who can write here", and removing the bot from a room revokes it.

        

          
          
          
NameSpeaks asTriggerStepsEnabledActions

        
Recent runs

        
        

          
          
AutomationStateStepUpdatedError

      

      

        
Agent activity

        
Everything non-humans did — bot mutations, automation runs, approvals — merged from the coordinator and messaging audit trails.

        
TimeActorActionDetail

      

    

    

      
Acting on behalf of a user

        
ADR-0021 §2. An assistant is a virtual session of one person — it reads everything they can read and posts in their name. This switch decides whether this organization may have them at all. The messaging service checks it on every request, not only when an assistant is created, so turning it off stops the ones already running rather than waiting for their tokens to expire. Worker bots — which act under their own names and see only the conversations they were added to — are not governed by it.

        
Loading…

        

        
 

      

      
AI lane (model provider)

        
The tenant's model-provider key behind the /ai/v1/* proxy (ADR-0030 §2). Bots never see it — each holds its own ai_… token, issued per bot in the Bots table with a model allowlist and a daily budget. Same rule as push keys: saving is enough, the messaging host's agent applies it within a minute. Check ai in the messaging /healthz.  Guide: the AI lane

        
        
        
        
        
        
        

        
Personal quotas (token API). An assistant spends its owner's own quota at the gateway and never this tenant key — with no quota it is created without a brain, deliberately. Give the installation address and an Admin-role token, and each person's key is issued when they create their assistant and revoked with their account. The management routes live outside /v1. 

        
        
        
        
        

        

      

      
Welcome flow

        
One button stands the whole thing up, idempotently (ADR-0023 Part 3): the Welcome Bot with a system badge, the welcome channel, the bot's membership in it, and the rule that greets whoever appears. Everything it creates stays an ordinary object afterwards — the bot on the Bots page, the room in the client, the rules in Automations — so an administrator edits the greeting there and re-running converges the rest around it. 

        
The trigger is user_created, which the coordinator reports for an admin-created account and for a first SSO login. It greets people only — meeting rooms and bots are accounts too, and they used to be welcomed to the company alongside them. Membership is by invitation — the bot adds people as they appear — so anyone who joined the company before this was switched on is missing until you fill the room below.

        

          

          

        

        

          

          

          

        

        
The greeting is your text, not a product string: it lives in the rule and is never translated for you. Placeholders: {{display_name}}, {{user}}, {{company}}, {{department}}, {{title}}.

        

          

        

        

          

          

          

        

        

        

          
          

      

      
Support case (@librarian)

        
One button stands the whole ADR-0031 case up, idempotently: the bot (system badge, @librarian), its AI token, the «SimpleTwo Support» channel and «SimpleTwo Dev» room, the gated automation and the webhook secrets. Re-running converges rooms/automation and rotates both bot tokens — the support node picks them up on its next convergence. Then: enroll a support role host (Servers), add people to «SimpleTwo Dev», grant them the dev role. Requires the AI lane above. 

        
There may be several such servers — different jobs, different knowledge bases, each with its own bot and its own provider key (ADR-0031 §5). Each is a case: pick one to edit it, or name a new one to stand another up. A support host is bound to its case when it is enrolled.

        

          

          

        

        

          

          

        

        

          

          

          

        

        

          

          

          

          

        

        
Names are per-install; blank keeps the current ones (defaults on first run). Rooms are tracked by id once created — room titles here only matter at first creation, and renaming a room later in the client is free.

        

          

          

          

        

        

          

          

          

        

        
This server's OWN provider credential (ADR-0031): the intermediary the bot's webhook points at calls the model itself, with a key limited upstream. Several such servers — different jobs, different knowledge bases — never share one. Leave the key blank to keep the stored one, or leave it unset to fall back to the platform lane.

        

          

          

          

        

        
Knowledge base (ADR-0034): the bot learns the product from GitLab — code, docs and issue history — so it can answer instead of only filing bugs. Blank fields keep the current settings; the embedding model must also be in the bot's AI allowlist, and needs an OpenAI-compatible provider (without one the base still searches lexically).

        

          

          

          

          

        

        

        

      

    

  

  

    
    

      
Mail DNS

        
The records each mail domain must publish for the edge (mx) to receive and send its mail: MX, SPF, DMARC, the DKIM keys this coordinator generated for the edge, and the submission and JMAP discovery records. Each is looked up; a record marked missing is one the world cannot see yet. Click a value to copy it.

        

        

        

        

        

          
          
           
        

        
Rotating a DKIM key
          
Three steps, and a new domain's first pair takes the same two. New DKIM key makes a new pair: publish its two records. Activate the new key becomes available once DNS answers with them; the edge then signs with the new pair and the old one is retired. Keep the retired records published until the date shown: mail signed with them is still being verified. The private keys are sealed with the master key when encryption at rest is on.

        

      

      
Service addresses

        
The addresses every mail domain must answer at: postmaster@ (required by RFC 5321), abuse@ (complaints about mail from here), and dmarc@ and tls-reports@, where the domain's DNS records ask others to send their reports. Missing ones are made as identity groups that cannot be deleted by accident and that anyone may write to, with you as the first member; add the people who answer them in Users → Groups.

        
AddressWhat it is forHeld by

          

        

        

        

      

      
Mail devices

        
Machines on the internal network that cannot sign in with a password — scanners, an ERP, monitoring. They connect to the mail edge (mx) on port 25 from the networks listed here and may write only as the senders listed, in this installation's mail domains. Everything else stays with app passwords. The internal network must be able to reach the edge's port 25.

        
NameNetworksSendersRecipientsPer minuteMax size, MBTLS

          

        
Networks and senders: several, separated by commas. A sender is an address or a whole domain as @corp.example. The narrowest network decides which connector a machine belongs to.

        

        

        
 

      

      
Quarantine

        
Mail the anti-virus or a content filter held on the way in. The sender was told it was delivered; each recipient got a notice from the postmaster instead of the message. Only here can it be released to its recipients or deleted; what nobody decides on is deleted after 30 days (MAIL_QUARANTINE_DAYS).

        
Held atSenderRecipientsSubjectHeld becauseMessage size

          

        

        

        

      

      
Group members outside

        
Partners and other outside addresses in groups whose mail comes back. After five bounces in a row, each within a week of the last, a member is disabled: its copies stop until you enable it again here — do that once the address works again.

        
GroupMemberBouncesLast bounceState

          

        

        

      

      
      
Mailboxes

        
Every mailbox the mail role holds: people's, made from the directory; shared ones, made here; rooms and resources. A shared mailbox has a responsible person and the people or groups who may open it, each with what they may do and whether they may send as it. A legal hold stops retention and any cleanup from destroying the mailbox's mail, whoever it belongs to.

        

          
          
          
          
          
        

        
AddressDisplay nameKindResponsible personMailbox sizeMailbox stateLegal hold

          

        

        
New shared mailbox
          

            
            
            
            
          

        

        

        

      

      
Sending as a group

        
Who may write to a group is identity's rule (the group's writers). Here is who may send AS the group, from the group's own address: as — the message is the group's alone; on behalf — it names the person in Sender. Every message sent as a group is written to the access audit.

        
GroupAddressMay write to itMay send as it

          

        

          
          
          
          
        

        

        

      

      
Message trace

        
The path of a message, from the edge that took it to a mailbox or a remote server: search by an address, or by the queue id either side gave (a bounce and the sender's server name it). Who wrote to whom is personal data, so this card needs the audit:read permission.

        

          
          
          
          
        

        
TimeEventWhere it happenedSenderRecipientNext hopServer replyDetails of the event

          

        

      

      
Mailbox access audit

        
Who opened which mailbox and did what: access to shared mailboxes and through delegation, and always what changes who can reach a mailbox or where its mail goes — a recall, an import or export, sending as somebody, an app password, a release from quarantine. It holds no subject and no body. Needs the audit:read permission; the export is JSON lines for a SIEM.

        

          
          
          
          
          
          
        

        
TimeWho actedMailboxActionClient and methodDetails of the access

          

        

      

      
Disclaimer

        
A text added to every message a person sends from the domain, to every recipient, before the edge signs it. The marker is how a reply that already carries it is recognised, so it is not added twice.

        
        
        
        
        
 

        

        

      

      
Leavers' mailboxes

        
A person's mailbox outlives their account: kept indefinitely unless a policy is set. With one, it is archived — accepts no mail and stays readable — or purged after the days below, and the responsible person is told before. A mailbox under legal hold is never purged; one made shared is the organisation's and is left alone. To find them, filter Mailboxes by "left by a person who has gone".

        

        

          

          

          

        

        
 

        

        

      

      
DMARC reports sent

        
The aggregate reports sent to the domains that ask for them, one a day per domain, for the last thirty days — or why one went to nobody.

        
DayDomainMessages countedRecordsSent toNot sent because

          

        

      

    

  

  

    

      
Client apps

        
What the Dashboard and the sign-in screen offer people as a way to install SimpleTwo. Store links go to TestFlight / Google Play; the rest are builds hosted here, in the coordinator's data volume. Both the list and the downloads are public — the person who needs a client cannot sign in from one yet. Guide: client apps

        
PlatformPublished

        

        

          
          

            

            

          

          
The mac-v* and android-v* pipelines POST the build they just signed to <public-url>/v1/clients/<platform> with this token. It authorises that one thing and nothing else — not an admin session, which is what a pipeline holding admin credentials would be. Rotating stops the pipelines publishing until the CI variable is updated.

        

      

      
Encryption at rest

        
ADR-0039. One master key, kept in a file on this server outside the database's volume, and printed on a recovery sheet with a QR code. The working keys — message bodies, the blind search index, meeting transcripts — are derived from it, so the safe holds one sheet rather than one per purpose. Generating, rotating and re-printing need the encryption:keys permission and leave a line in the audit log; reading a body in the clear needs messages:export. Neither is in any built-in role.

        

        

        

        
Creating the key, changing it and printing the sheet again all need the encryption:keys permission, and your role does not hold it — no built-in role except owner does. Ask an owner, or add that permission to your role in Users → Roles.

        

          
          
          
          
        

        
New generation re-derives the working keys from the same master: new writes use them, old rows keep opening, and the printed sheet stays valid — this is the answer to a key that may have leaked from a messaging host. New master key prints a new sheet, and rows already sealed keep needing the old one.

      

      
Product options

        
VPN and the calendar are the base — always on, and there is no switch for them here. The rest are options: switch them per tenant and choose HOW they are reached — directly over TLS (works without the VPN) or through the tunnel only. Clients hide disabled modules. Skills (peer-confirmed skills, endorsements, kudos) is served by messaging and follows its access mode; it ships OFF, because collecting this about people is a decision an organization makes rather than one it discovers. Federation lets people here write to name@another-domain and is the one switch that lets messages leave this organization — it ships OFF, and needs the policy below. Greyed rows are designed and not built; they are listed so that what the product will compose from is visible, not to be switched on today.

        
ModuleEnabledAccess

          
VPNbasetunnel

          
Messaging
            
            

          
Conferencing
            
            

          
Skills
            
            follows Messaging

          
Federation
            
            server to server, over public HTTPS

          
Work
            
            SimpleOne tasks on the device, offline — designed, not built

          
Mail
            
            
              

        

        

        

      

      
General

        
        

        

        
        

          
          
          
        

        
        
Camouflage each gateway under a country-plausible host (RU→yandex.ru, NL→a .nl site). Verify on the gateway with xray tls ping <host> — pick one showing Post-Quantum: false (X25519). Per-gateway blank = inherit global. Applies after the gateway's next Update.

        

        

        
XTLS-Vision. Splices the inner TLS so a DPI cannot see TLS-inside-TLS — the fingerprint plain VLESS+Reality carries, and the one a path that kills established flows keys on. It is the designed answer to "the tunnel connects and passes nothing". The risk is the mirror image: the mobile (libXray) build has been measured negotiating Vision and never relaying the RESPONSE — gateway acknowledges, fetches, and sends a FIN with zero data. One switch for the whole install, because both ends must agree: gateways re-render within a heartbeat, clients pick it up on their next session. Turn it off here the moment mobile goes quiet. 

        

        

        

        
        

          

        
        

          

        

        

      

      
External Postgres and Redis

        
Use stores the organisation already runs instead of the ones the postgres, redis and s3 roles install. Leave a field empty and that store keeps coming from its role — this is a switch, not a migration: nothing is copied, so point a service at a new database only when it is empty or already holds its data. Guide: storage

        
Give each service a connection string its own login can use. We do not create databases or roles here: a cluster you do not own will not grant that, and half-creating something on it is worse than asking.


        
        
        

          

          

        


        
        
        

          

          

        


        
        
        
        
        

          

          

        


        
        

        
        

          

          

          

        

        

          

          

          

        

        

        

        

        

        
Checks dial from the coordinator. The host running the role still needs its own route to the database — that is the one thing this button cannot see. Saved values reach a role on its next poll, and the service restarts with them.

      

      
Client tunnel profile

        
Remotely tune client transport knobs — fingerprint, block_quic, dns (mode/servers), fragment, mtu, mux, kill_switch (true/false — enforce blocking all traffic when the tunnel is down; omit to let users decide), reconnect (true/false — enforce auto-reconnect; omit for user choice) — without an app rebuild. JSON is overlaid global → group → user → device (most specific key wins); the client applies keys it understands and ignores the rest. Applies on the client's next connect.

        

          
          
          
          
        

        
        

      

      
Calls & conferences (SFU)

        
Self-hosted the media server SFU for A/V calls, conferences, screen share. The coordinator mints room tokens (RBAC: calls:join / calls:host); media flows client↔SFU. Deploy the sfu and turn server roles, then enter the client URL + API key/secret here.  Guide: calls

        
The client URL is not a setting: each deployed SFU carries its own, and the
        coordinator hands a client the one that serves its room. A single field could only ever name
        one node, and it was the one place a wrong address could be typed — this one held the Redis
        host for a while, which the panel reported and clients were sent to anyway. For an SFU inside
        the perimeter, the address lives on the NODE and its subnet must be served by a gateway group,
        or a phone has no route to it.

        

        

          

        

        

      

      
Push notifications (APNs)

        
One key, both kinds of push. This is not calls-only: the same APNs key rings incoming calls and delivers every message notification. Leave it blank and users get no message banners at all — the messaging service builds no APNs client and every notification silently becomes a no-op. Saving is enough: the key is part of the messaging host’s desired state, so its agent picks the change up on its next poll (about a minute) and restarts the service. Nothing to redeploy — a host that pulls has no redeploy. 

        

          

        
        
        
        
        
        
Leave OFF for TestFlight and App Store builds — they are signed aps-environment: production, and the sandbox host rejects their tokens as BadDeviceToken. Only a Xcode-built debug install needs this.

        

        

      

      
Push notifications (Android / FCM)

        
The Android half of the same story: without it Android devices get notifications only while the app is open. Same rule as APNs — saving is enough, the messaging host’s agent applies it within a minute and restarts the service. Check push_android in the messaging /healthz to see it land. 

        
        
        
Firebase console → Project settings → Service accounts → Generate new private key. This is not google-services.json: that one is the client config, it belongs in the Android build (CI variable ANDROID_GOOGLE_SERVICES_JSON), and it is rejected here.

        

        

      

      
Identity  

        

        

        

        
The organisation's directory and the platform's sign-in (ADR-0047 §8a): people, groups and their membership, the attribute schema, address books, applications, company providers, SCIM, the LDAP server and the sign-in policy are identity's, and are managed in its own console (the link above). This card is the role's status, like every other role's. Guide: groups and the schema

        

      

      
Break-glass account 

        
One local account on the coordinator for the day identity is down and the fleet — identity included — has to be repaired (ADR-0047 §8a). A password and a mandatory authenticator code, held here and never on identity. It signs in only at its own address, every use is audited and every administrator is messaged, and its session opens this console for an hour. Keep the password and the authenticator somewhere the on-call administrator can reach without the platform.

        

        

        
 

      

      
Gateway DNS (VLESS / Reality recorder)

        
Resolvers gateways use for tunneled traffic. Without this, a gateway resolves via its host /etc/resolv.conf (often a broken VPS stub) — sites don't load though the tunnel is up. Applies on each gateway's next config pull; redeploy to apply now. 

        
        
        
        
        

        

      

      
Directory photos (AD / LDAP)

        
This card feeds identity's directory (ADR-0047 §8a). Its passes run on the coordinator only until identity takes them: as soon as an identity host is deployed, the coordinator hands it the connection, the bind password, the watermarks and the last results once, and deletes its own copies. Without identity they stay here. The photo policy below stays here either way.

        
Employee avatars are pulled from AD (thumbnailPhoto) after each SSO login and pushed to messaging. Guests/external accounts upload their own photo in the app. 

        
        

        
        

        

        
        
        

          

        
        

          

        
        
Groups (ADR-0047): with a group base DN the directory's groups — objects, their manager as owner, every member — are written into the identity role every six hours and on demand, so a group exists before anybody in it has signed in. Same groups the sign-in already writes; this pass says all of it at once. Members are matched to accounts here by userPrincipalName, then mail, then sAMAccountName; the unmatched are counted, never guessed. 

        

          

        
People (ADR-0047 §7a): every six hours and on demand, each account here takes from the directory the attributes the identity schema maps with source: ldap and an ldap_name — nothing else is read — and its manager, resolved to an account here. Standing (the disabled bit, accountExpires) is counted on every pass and applied only with the switch below: it is the one part that can lock a person out. 

        
        
Passwords (ADR-0047 §7a): identity holds a copy of this connection for the bind pass-through. Whether it binds at all is identity's own setting, switched in identity's console.

        

        

        

          
          
          
          
          

        

      

      
SimpleOne (HRMS)

        
This card feeds identity's directory (ADR-0047 §8a). The HRMS module runs on the coordinator only until identity takes it: as soon as an identity host is deployed, the coordinator hands it the connection, its secret, the settings and the last run once, and deletes its own copies. Without identity it stays here.

        
One connection to a SimpleOne instance, shared by every module integration; HRMS is the first. It enriches employee cards with the two managers an organization actually has — functional and organizational — which AD cannot express, since it carries a single manager. Plain directory data: nothing here is behind the Skills switch. We always call them, never the reverse (their Scripted REST executes as Guest User on a bad token). 

        
        

        
        

          

        

          

        

        

        

        
        
        
        
The platform's own way to read a table is the Table API: /rest/v1/table/employee, which answers {"status":"OK","data":[…]} and takes Basic or Bearer. A path shaped like /v1/api/… is a Scripted REST action, which exists only if somebody built one on your instance.

        
Four things the query has to do, because nothing here can do them for you:
          narrow it to real staff (on SimpleOne: sysparm_query=active=1^company.class=internal, or contractors and closed accounts arrive too),
          ask for display values (sysparm_display_value=1) — a manager without one comes back as an 18-digit record id, and the report counts those rather than writing them,
          walk the reference where the field you want belongs to another record (immediate_unit_id.manager is the manager of the person’s own unit, and timezone_id.name is the zone name a calendar can load rather than the “(GMT+03:00) …” label),
          and raise the page size (sysparm_limit=1000) — the default is twenty. Pages after the first are read automatically; pin sysparm_page yourself only to look at one.

        

          

        
        
The person's working hours in the calendar — the frame a scheduling wizard proposes meetings inside, and until now the tenant's single answer for everybody. work_schedule on the employee record is a reference to a schedule, so what arrives is its name; the hours live in that schedule's elements, in a shape (night shifts, holidays, two levels of inclusion) that days/start/end cannot hold. So state the translation here once. Days are ISO weekdays, 1 = Monday. Run the preview first: it lists every schedule name your instance actually answers with, and how many people are on each. A name you leave unmapped is reported, not guessed at — those people keep the hours they chose. A name you map takes the field over: their calendar shows it as coming from HR and refuses edits, on every client.

        

          
          

        

        

        

      

    

    
    
Domains

      
Every domain of the organisation, and what each service does with it. Sign-in: people may sign in with an address in it (Single sign-on, Served mail domains; identity takes this list over). Mail: the mail role accepts mail for it — mailboxes (its addresses are mailboxes, aliases and groups here; a primary address may only be in such a domain), aliases only (receives for aliases of mailboxes in another domain), or not at all. The primary mail domain is where postmaster@, dmarc@ and no-reply@ are. A domain that still holds addresses cannot be removed from mail, and the mail role says why.

      
DomainSign-inMailHolds

        

      

        
        
        
        
      

      

      

      

    

    

      
TLS / Certificate

      

        

          

          

          

        

        

          
Let's Encrypt (auto)

          

            

          
The address Let's Encrypt writes to when a certificate is about to expire and renewal has not happened. Issuance works without it — and then nobody is warned.

          

          

          
          
          
Point these hostnames (DNS) at this coordinator. Once Let's Encrypt is enabled above, a certificate for each name is issued on first connect. The mobile app discovers the coordinator via https://<host>/.well-known/simpletwo.json.

          
          

          

          
Password autofill on iOS and macOS
            

              A saved password belongs to the domain it was saved on, and Apple will not hand one to an app the domain has not vouched for. The vouching is /.well-known/apple-app-site-association, and this coordinator already serves it on every name that reaches it — so every domain listed above is covered with nothing to host.
              


              The other half is in the APP, and it is baked at build time: the client must claim each of these domains. If autofill offers nothing on one of them, that is the half that is missing — not this list. The lines the app build needs:
              
webcredentials:<each domain above>

              Apple fetches the file through its own CDN and caches both success and failure for up to a day, so a freshly added domain is not offered immediately. sudo swcutil developer-mode -e 1 on a Mac makes it fetch directly and is the way to check before the cache turns over.
            

          

          
How auto-discovery works & setup
            

              The mobile app asks users only for email + password and finds this coordinator from the email domain. This coordinator: —. It tries, in order:
              
    
                
  1. Subdomain (recommended) — create a DNS record s2.<yourdomain> pointing here (CNAME to this coordinator's host, or an A record to its IP), then add s2.<yourdomain> to Tenant domains above, with Let's Encrypt enabled. The coordinator serves the discovery document and issues a certificate for that name on first connect. Nothing else to host.
    2. 
                
  2. Root file — publish https://<yourdomain>/.well-known/simpletwo.json with { "coordinator_url": "…", "name": "…", "allow_insecure": false }.
    3. 
                
  3. DNS TXT — add _simpletwo.<yourdomain> TXT = simpletwo=https://<coordinator> (used only if 1–2 fail; may be blocked on some networks).
    4. 
              

              Example for user@itglobal.com: DNS s2.itglobal.com → this coordinator, add s2.itglobal.com to Tenant domains. The app then discovers it via https://s2.itglobal.com/.well-known/simpletwo.json. Verify anytime by opening that URL in a browser.
            

          

        

      

      

      
Obtain from provider

      

        

        

        

      

      

      

      

      

      
Manual import (paste PEM from any provider)