Organizations and projects

Telmoni has two tiers: Organizations and Projects. There are no teams.

An Organization is the top level. It holds projects, organization-level members, organization settings, and a rolled-up audit log.

A Project lives inside an organization. It holds API keys, notification connectors (Slack, webhooks), in-app notifications, project-specific audit records, and its content mode.

A solo developer and an enterprise work the same way: an organization with one member and a project, or one with many members across multiple projects.

Your organizations and projectsCopy Anchor Link

When you first sign in, Telmoni provisions an Organization, with you as its Owner (see Signing in for the switch an operator can turn this off with). It arrives named after the first word of your name ("Ada's organization"), or "My organization" when your account has no name; Signing in says where the name comes from. The name is what everyone in it sees, and its URL follows from it (see Name and URL). Nothing is asked first: you can change both in Settings whenever you like.

The organization starts with no projects. The console opens on its Overview (/{organization}), titled by the organization's name; create the first project from the Projects page or the switcher. API keys and connectors belong to a project, so there is little else to do until one exists.

A sign-in opens the Overview of your default organization, or returns you to the page that sent you to sign in. Within a session, opening the console (/console) returns to the Overview of the organization you were last in.

You can belong to multiple organizations at once: ones you own, including any you create, and ones you have been invited to. Your role in one organization does not dictate your role in another.

Roles at a glanceCopy Anchor Link

Both organizations and projects use three roles: Owner, Admin, and Member. See Roles and permissions for the full permissions matrix.

• Organization Owner: Full access across all projects, project creation and deletion, member management, organization settings, and organization transfer/deletion.
• Organization Admin: Can create projects, manage members and organization settings, and read the organization's audit log. Operates as an admin across all projects. Cannot delete projects, delete the organization, or transfer ownership.
• Organization Member: Access is restricted to the specific projects they are seated in. No organization-wide management powers.

Moving between themCopy Anchor Link

The console's address names the organization, and the project under it, by a slug: a short URL-safe handle, such as acme. An organization's is set when it is created, as the URL you give it or one derived from its name, and changed only in its Settings; a project's follows its name (see Name and URL). On these pages, {organization} and {project} stand for those two slugs.

• An organization's overview is /{organization}, titled by the organization's name. It shows the organization's notices to its Owner and Admins when there are any, and Leave organization to everyone but the Owner. Its projects are in the switcher, and on the Projects page for its Owner and Admins.
• Organization pages sit beside its projects, at words no project goes by: /{organization}/projects, /{organization}/members, /{organization}/audit-log, and /{organization}/settings, with /{organization}/billing on the hosted service.
• Project pages sit under the organization: /{organization}/{project} is the project's overview, titled by the project's name and showing its notices to anyone on the project when there are any, with /traces — every run of the project's agents, and a page for each — /sessions — its runs grouped by session, and a page for each — /users — by the user they served — and /alerts and /dashboards, which say what each will show until their pages are built, and /api-keys, /connectors, /members, /audit-log, /privacy — the project's content mode and the field inventory, every attribute Telmoni reads from a span and what becomes of it — and /settings under it.
• Account pages live under /account, including /account/settings, /account/notifications, /account/accessibility, and /account/privacy.
• Switch between projects and organizations using the switcher in the console header: two menus side by side. The organization's name opens your organizations, ending with New organization. Beside it, the project's name — or Select a project on the organization's own pages — opens that organization's projects, ending with New project for its Owner and Admins.

Name and URLCopy Anchor Link

An organization has a name, which everyone in it sees, and a URL, the slug its addresses begin with. They are two settings.

• A slug is lowercase ASCII letters and digits, in words joined by hyphens, at most 48 characters long.
• A new organization starts with a URL. You can give one when you create the organization; otherwise it is derived from the name it is created with: accents fold and apostrophes drop, so "Zoë's organization" becomes zoes-organization, and "My organization" my-organization. A URL already in use gets a number, up to -20 (zoes-organization-2); past that it ends in six random characters (zoes-organization-k3x9qz). When the first word of your name has no Latin letter or digit ("李明's organization"), the organization gets a placeholder (org- and ten random characters) until you choose a URL. So does a name whose URL would hold profanity or a slur, which no URL may: the name itself is kept as given.
• Renaming an organization moves nothing. Its URL stays as it is, and so does every link to its pages.
• Changing the URL is done on the organization's Settings page, under URL: any slug not held by another organization, not one of the console's own words, and holding no profanity or slur. Every page of the organization and of its projects moves to the new address, and the old address answers Not found. Pages open in the console follow the change; links made before it do not.
• A project's URL follows its name. Within its organization a project's slug is unique; a name already taken as a slug gets a number. Some words are kept for the organization's own pages (projects, members, settings, and others), and a name that is one gets the numbered form: Settings becomes settings-2. A name with no Latin letters or digits, or one whose URL would hold profanity or a slur, gets a placeholder (project- and ten random characters). Renaming a project moves its pages, and the old address answers Not found; a new name that gives no slug leaves the URL as it was.
• An organization's URL is unique across all organizations, ones awaiting deletion included; once a deleted organization is purged, another may take its URL.
• IDs never move. An organization's ID (org_...) and a project's ID (project_...) are unchanged by any rename or URL change, and a console path spelled with an ID in place of a slug redirects to the current slugs, keeping the rest of the path. Use the ID in anything you script. An organization's ID is shown on its Settings page, which opens for its Owner and Admins (telmoni org list, after a browser telmoni login, prints it for anyone in it); a project's on its Settings page.

Console navigation and keyboard shortcutsCopy Anchor Link

The web console provides built-in keyboard navigation (⌘ is Ctrl on Windows and Linux):

• Quick search (⌘K or /): Opens the search palette: recently visited pages, projects, documentation, and, on a project's pages, that project's API keys and members.

• Ask the agent (⌘J): Opens the Telmoni Agent window (the console agent) over the page you are on, where you last left it. Drag it by its title bar, size it from any edge or corner, or fill the screen from its header or with a double-click on its title bar. Ask questions about a project's activity, members, connectors, or audit log; a new conversation offers a few to start with. Responses stream with inline citations and links to referenced sources, and Stop ends one early, without saving it. Past conversations are saved per person and per project: the history lists the ones you asked from the project you are on, and each can be reopened or deleted. A conversation stays open on the organization's own pages; another project's pages start a new one.

• Account menu (⌘⇧K): Opens the user menu: your account, the home page, the documentation, the keyboard shortcuts sheet, theme and corners, the platform's GitHub repository, and sign out.

• Primary action (c): Triggers the primary action of the current page: New project, Mint key, Invite member (on a project's Members page, Add member), or Export on the organization's audit log; on the hosted service's Billing page, Plans or Manage billing.

• Next and previous (j, k), open (o): With a trace open over the Traces list, open the next row's trace or the previous one's; on a session's page, stand on the next trace or the previous one, and o opens it or shuts it. After g, k is still API keys and o the Overview.

• Navigation sequences (g followed by a key): every row of the sidebar you are in has one, and the sheet (?) lists the rows of that sidebar. On a project's pages:

  • g o: Overview
  • g t: Traces, g s: Sessions, g u: Users, g a: Alerts, g d: Dashboards
  • g k: API keys, g c: Connectors, g m: Members, g l: Audit log, g p: Privacy
  • g ,: Settings, as ⌘, opens preferences on a Mac

  On an organization's pages: g o Overview, g p Projects, g m Members, g l Audit log, g , Settings, and on the hosted service g b Billing. On your account's pages: g , Settings, g a Accessibility, g p Privacy. A row that is not on the sidebar you are in has no sequence there, so g k on an organization's pages does nothing. A console built on this one can add rows of its own, each with a key of its own. Two sequences work from anywhere in the console:

  • g n: Notifications, the page behind the bell
  • g O (shift): The organization's overview

• Keyboard shortcuts cheat sheet (?, Shift / on a US keyboard): Opens the full shortcuts sheet. Letter-key shortcuts can be turned off on the Accessibility page; the sheet then lists the ⌘ shortcuts alone.

Hover over a sidebar row, or over search, the bell, the agent or your account in the header, to see its shortcut. With letter-key shortcuts off, only the ⌘ ones are shown.

The foot of the sidebar shows the version of Telmoni the console runs.

ProjectsCopy Anchor Link

A project's overviewCopy Anchor Link

A project opens on its Overview, /{organization}/{project}, titled by the project's name. Under the title are the project's notices when there are any — a member joining or leaving, a channel connected or lost — newest first, each unread one bold, with Mark read beside them.

Creating a projectCopy Anchor Link

An organization Owner or Admin can create a new project from the organization's Projects page (/{organization}/projects) or the switcher's project menu:

1. Select New project on the Projects page, or New project in the switcher's project menu. A panel opens over the page, as a trace opens over its list at full size: it names the organization the project lands in, the one you are in, and asks only for a name. Escape, Cancel or its close button shuts it, and so does moving to another page.
2. Provide a project name: up to 100 characters, and not one another project in the organization already has (compared without regard to case).
3. The project is created immediately. Its API keys and connectors are its own.

Renaming a projectCopy Anchor Link

An Admin or Owner can rename a project from the project's Settings page (/{organization}/{project}/settings). The same limits apply as at creation, and the rename moves the project's URL (see Name and URL).

A project's content modeCopy Anchor Link

A project's content mode says what it keeps of the content its spans carry: the prompts and completions of an agent's model calls, the inputs and outputs of its tool calls, error messages, a person's name or email address, and anything else a person or a model wrote. A span's name, its tags, a user id and an error's type (its class, never its message) are metadata you choose to send, and the content mode does not decide what happens to them. Everyone on the project sees the mode under Content on the project's Settings page (/{organization}/{project}/settings).

• Off, the mode every project starts in, keeps none of it: each piece of content is dropped as its span arrives, and the span is kept without it.
• On and Sealed are not available yet. The Owner sees them on the page, closed.
• Only the organization's Owner can change a project's mode, because what a project keeps changes what the organization is responsible for. Admins and Members see the mode and cannot change it.
• Every change is recorded in the audit log.

Ingest reads the mode on every export, so it acts at the door, as the span arrives. The project's Privacy page shows the mode beside the field inventory: every attribute ingest reads, and what becomes of each.

Deleting a projectCopy Anchor Link

Only the Owner can delete a project. Deletion is initiated from the Danger zone on the project's Settings page (/{organization}/{project}/settings):

• The dialog asks you to type the project's name before it deletes anything.
• It takes effect at once, with no undo.
• Deleting a project deletes its API keys, member seats, and pending invitations with it, and its connectors, their delivery history, and its activity feed are purged right after (whatever fails then is tried again every hour until it goes). The console agent removes what it holds about the project.
• Its traces go with it: every span and every hour of totals the project sent is marked deleted in the same purge, gone from every read within moments as the store applies the mark, and the nightly rotation removes them from disk. Telemetry is kept only while its project is active, never past its deletion.
• Data deletion lists everything a deletion removes, when, and what stays.
• Historical audit events for that project remain preserved in the organization's append-only audit chain.

Transferring a projectCopy Anchor Link

An organization Owner can hand a project to one of the project's Admins:

1. The Owner selects Transfer project on the Admin's row on the project's Members page (/{organization}/{project}/members) and confirms with Send offer. Only someone with an Admin seat on the project can be offered it, so invite an organization Admin to the project as an Admin first.
2. The Admin is emailed, and the offer appears in their console bell and under Project offers on their account's Notifications page (/account/notifications). It stands for 7 days, and a project has one live offer at a time: a new offer withdraws the earlier one, and whoever held it is told. The Owner can withdraw it with Withdraw offer on the same row; removing the Admin from the project, or their leaving it, ends the offer too. The Owner is emailed a decline, and the Admin a withdrawal.
3. The Admin accepts the project into an organization they own. The page asks which one when they own several, and offers only Decline when they own none.
4. On acceptance:
   • The project row moves into the new organization. It keeps its name unless that organization already has a project by it, in which case it arrives with the next free number on the end (Payments 2). Its URL changes with the move (see Name and URL).
   • Its API keys follow into the new organization. The offer on the Notifications page advises the new owner to rotate any key they did not mint.
   • Its content mode follows it, for the new organization's Owner to change.
   • Project seats and pending invitations stay on the project, and everyone seated is enrolled on the new organization's roster as a Member, as a project invitation would enrol them — a seat given from the old organization's roster among them, and one its holder had not yet seen leaves their bell with the move. The accepting Admin's own seat is folded into their ownership.
   • The former owner stays on the project as an Admin, joins the new organization as a Member, and is emailed that the project moved.
   • Connectors do not follow: a project's Slack grants and webhook secrets are the old organization's, so they are removed before the move commits, with their delivery history and the project's activity feed, and a removal that fails moves nothing. The console agent removes what it holds about the project in the old organization.
   • Both organizations' audit logs record the move; the receiving one also notes the name the project was offered under when a clash renamed it. The project's earlier events stay in the old organization's log, so its Audit log page starts at the move.

OrganizationsCopy Anchor Link

Creating an organizationCopy Anchor Link

Anyone signed in to the console can create another organization, and becomes its Owner:

1. Open the switcher in the console header and select New organization; a panel opens over the page, as New project does.
2. Give it a Name: up to 80 characters, the name everyone in it sees.
3. Give it a URL, or leave the field blank to have one derived from the name, as Name and URL describes: "Acme Robotics" becomes acme-robotics, with a number on the end when another organization holds that, and a name with no Latin letter or digit gets a placeholder (org- and ten random characters) until you choose a URL. A URL you give must be a slug no other organization holds, not one of the console's own words, and holding no profanity or slur.
4. Select Create organization. The console opens the new organization's Overview; create its first project from its Projects page or the switcher. On the hosted service, a second organization is paid for first, as below: the panel asks for its plan and sends you to the payment page, and the organization opens once the payment is confirmed.

There is no limit on how many organizations you create or own. Creating one leaves your default organization, the one a sign-in opens, as it was. An operator who has closed new organizations closes this too: the switcher offers no New organization. On the hosted service, one you create while you already own an organization on its free plan is paid for before it exists, on Pro or Teams, and created once the payment is confirmed (One Hobby organization).

Renaming an organizationCopy Anchor Link

An Owner or Admin can rename an organization from its Settings page (/{organization}/settings). The name can be up to 80 characters. A rename moves nothing: the organization's URL is its own setting on the same page (see Name and URL).

Transferring organization ownershipCopy Anchor Link

An organization has exactly one Owner. The Owner can transfer ownership to any organization Admin; on the hosted service, one on the free plan goes only to an Admin who owns no organization on it (One Hobby organization):

1. The Owner selects Transfer ownership on the Admin's row on the organization's Members page (/{organization}/members) and confirms with Send offer.
2. The Admin is emailed, and the offer appears in their console bell and on their account's Notifications page (/account/notifications). It stands for 7 days, and an organization has one live offer at a time: a new offer withdraws the earlier one, and whoever held it is told. The Owner may withdraw the offer at any time before it is accepted; removing the Admin from the organization, or their leaving it, ends the offer too.
3. The Admin accepts (confirming with Become the owner) or declines on the Notifications page. The Owner is emailed either answer, and the Admin is emailed a withdrawal.
4. Upon acceptance:
   • The accepting Admin becomes the new Owner. Any project seats they held are removed, since the Owner's standing on every project comes from the organization.
   • The former owner becomes an Admin in the organization, and may then leave it.
   • All projects, API keys, connectors, and audit histories stay intact. The handover, and each removed seat, is written to the audit log.

Deleting an organizationCopy Anchor Link

Only the Owner can delete an organization. Deletion is performed from the Danger zone in the organization's Settings page (/{organization}/settings):

1. Request a 6-digit confirmation code, which is emailed to the Owner's address and remains valid for 15 minutes. Five wrong guesses burn it; Resend code issues another. The console sends at most three codes an hour and takes ten attempts an hour. On a self-hosted deployment, the code goes out only when the operator has configured mail (SMTP_URL); without it, the organization cannot be deleted from the console.
2. Enter the confirmation code.
3. Access ends immediately: the organization is closed, all API keys stop authenticating, and member access ceases. On the hosted service, its billing is closed at once; a part that cannot finish is retried every ten minutes, and the confirmation screen says so when that happens. Your own account is untouched, and if this was your last organization, your next console page provisions a new one while new organizations are allowed, as your first sign-in did.
4. Erasure follows, usually within the hour: the automated deletion sweep permanently purges the organization, its projects and their traces, API keys, connectors, notices and console agent data. There is no restore window and no undo. Data deletion lists everything it removes, and what stays.

An organization an operator closed from the server (telmoni terminate, on a self-hosted instance) goes the same way.

Leaving an organization or projectCopy Anchor Link

• Leaving an organization: Anyone but the Owner can leave from the organization's Overview page (/{organization}), with Leave organization. Leaving removes you from the organization and from every project in it.
• Leaving a project: Your own row of the project's Members page (/{organization}/{project}/members) offers Leave, whatever your seat's role and however it came, by invitation or from the organization's roster. Leaving gives up the seat alone: you stay on the organization's roster, and an Owner or Admin can add you back. The organization's Projects page (/{organization}/projects), which opens only for the organization's Owner and Admins, offers an Admin Leave beside each project they still hold a seat on; they keep their access to every project through their organization role, and the Owner, who holds every project outright, is offered none.
• The Owner cannot leave an active organization. To leave, the Owner must either transfer ownership to an Admin or delete the organization.