Organizations

An organization — an ORG — is the container that everything shared in ORG-2 belongs to. Sessions, projects, work items, comments, share links, and quotas are all scoped to exactly one ORG. ORG-2 is built this way on purpose: the product treats agents as persistent, observable colleagues inside a structured organization rather than as one-off assistants, so humans and agents join the same ORG, appear in the same member roster, and work against the same shared context.

You do not have to use an ORG to use ORG-2. Sessions run locally and are grouped under My Personal Org in the sidebar org selector until you add a real one.

Two ways to run an ORG

ORG-2 is open core. There are two backends, and they differ in the roles they support.

Note: Session collaboration and group issue workflows over self-hosted Supabase are marked work-in-progress in the ORG-2 README. Expect rough edges, and read Collaboration for what is actually implemented on each path.

Creating an ORG

In the desktop app, open the ORG list in the sidebar and choose Add ORG.

1. Pick an Org source: Local (a name-only container, no sync) or Supabase Sync.
2. For Supabase Sync, pick a Setup mode: Create or Join.
3. In Create mode, fill in the ORG name, Join as (your display name), the Supabase Project URL, and the Supabase anon key.
4. Click Copy setup SQL, then Open Supabase SQL Editor, paste, and run it. Come back and click Verify setup — you should see Supabase setup verified.
5. Click Create.

The setup SQL creates the orgii_orgs, orgii_members, orgii_invites, orgii_projects, orgii_work_items, orgii_sessions, orgii_chat_messages and snapshot tables, plus a private orgii-session-snapshots storage bucket. No terminal commands are required.

Creating an ORG makes you its admin. On ORG-2 Cloud, create_org makes you the owner instead, and records you as both the org owner and the billing owner.

Inviting members and accepting an invite

When you create a Supabase Sync ORG, ORG-2 immediately mints an invite link and shows it under Invite ready with a Copy invite button. You can mint more later from the ORG panel's Members tab — Create invite copies the new link to your clipboard. Only ORG admins can create invite links.

Invite links look like orgii://collaboration/join?sync=supabase&supabase=…&invite=…, and carry the project URL (and optionally the anon key) so the recipient does not have to type them. Clicking one opens ORG-2 with the join form prefilled; pasting the link — or just the bare invite code — into Invite link or code works too. Invites default to 10 uses.

To accept: Add ORG → Supabase Sync → Join, paste the invite, set Join as, and choose My identity — Human or Agent. That identity kind is a first-class property of a member, which is how an ORG holds both people and agents in one roster. Only human identities can post in group chat.

On ORG-2 Cloud, invites are created by admins with a role attached (admin, member, or viewer), an optional expiry, and a use count that defaults to 10. Accepting is seat-gated: if the ORG is already at its member cap, the accept fails with ORG2_QUOTA_EXCEEDED. Re-accepting as an existing active member never downgrades your role.

Roles and permissions

Self-hosted Supabase has two roles:

ORG-2 Cloud has four. Anything marked "admin" below means owner or admin.

Note: viewer is a valid role value that invites and role changes accept, but the backend's write RPCs currently gate on membership and on admin, not on viewer versus member. Treat viewer as an intent marker for now, not as an enforced read-only boundary.

Two guardrails are enforced in the database. An ORG can never be left with zero active owners or admins — demoting, removing, or leaving as the last admin fails with ORG2_LAST_ADMIN. And the owner role only ever moves through an explicit ownership transfer.

What is scoped to an ORG

Every one of these rows carries an org_id, and reads are gated on active membership:

• Sessions — session metadata and replay event segments, including the frozen segments stored in the private replay bucket
• Projects and work items — with per-ORG work-item prefixes and short-ID counters
• Comments — session and event comment threads
• Session shares — directed grants and share-link tokens
• Repo scopes — the allowlist of repositories whose sessions may enter the ORG
• Entitlements and usage — plan, quotas, and the monthly usage ledger
• Presence and change signals — one private realtime channel per ORG, presence:org:<orgId>

Agent memory is not org-scoped. Cross-session memory stays on your machine; nothing syncs it into an ORG.

Switching between ORGs

The sidebar has an org selector. It always contains My Personal Org (the local default), then your local project orgs, then your synced ORGs. Picking one filters the session list to that ORG. Opening an ORG gives you its panel, with tabs for Work Items, Project, Sessions, Members, Group chat, and Settings.

On ORG-2 Cloud, signing up automatically provisions a personal workspace ORG named after you (for example, Ada's workspace), owned by you, so a new account has somewhere to scope repos and invite people into on day one.

Leaving, removing, and transferring

An admin removes someone from the Members tab with Remove. On ORG-2 Cloud the rules are:

• Removing yourself is not allowed through the remove path; use leave instead.
• Leaving is blocked for the owner — you get ORG2_OWNER_MUST_TRANSFER. Transfer ownership first, or delete the ORG.
• Transferring ownership requires you to be the current owner and the target to be an active member. It makes them owner and demotes you to admin in one atomic step.
• Deleting an ORG is owner-only. It soft-deletes the ORG, tombstones its sessions, and marks every active membership removed, which evicts open clients.

Still on Cloud, removals and leaves are soft: the membership row flips to removed with a timestamp. Accepting a fresh invite later reactivates it.

Limits and quotas

ORG-2 Cloud enforces per-ORG quotas from the plan catalog.

Two behaviours are worth knowing. Retention is soft: the replay window is a read-time visibility filter, never a deletion — widening it (by upgrading) instantly makes older sessions visible again, and "full while subscribed" means the window narrows back to the free one if a subscription lapses, without anything being erased. And removed repo scopes keep occupying a slot for a cooldown period (7 days on free, 30 on paid) so you cannot rotate around the repo cap.

Exceeding a quota raises ORG2_QUOTA_EXCEEDED on the operation that crossed the line, rather than silently dropping data.

Next steps

• Collaboration — sharing sessions, comments, share links, and reviewing an agent's work as a team
• Cloud — the managed backend, plans, and the self-hosted alternative
• Projects — projects and work items inside an ORG
• Security — what leaves your machine and what does not