# Organizations, Projects & Members An organization is the top-level container for your team: it owns projects, members, billing, and identity configuration. Everything in Swarmfile lives inside exactly one org. ## Creating an organization There's no separate "create your organization" step. When you sign up at `/start`, you register and an org is created for you in the same flow. Choosing **Starter or Pro** goes straight into Stripe Checkout to pick and pay for a plan; choosing **Free** creates the org without any card or checkout. The org gets a slug auto-derived from what you typed at signup; if that slug is already taken, it's auto-resolved to something unique so signup never blocks on a collision. One account can create up to **25 organizations**; past that, creating another answers with a support pointer. The limit is an abuse bound (a real buyer has a handful of orgs), not a plan feature - contact support if a legitimate setup needs more. The org slug matters beyond cosmetics - it's part of every public share link (`/s/:orgSlug/:token`). ## Renaming your org As owner, you can rename the org's display name or its slug from Settings at any time. Renaming the name is cosmetic. Renaming the slug is not: it invalidates every outstanding public share link tied to the old slug, and there's no redirect kept from old to new. Anyone with an old share link loses access silently. Because of that, changing the slug requires retyping the current slug as confirmation before it takes effect - treat it as a real, disruptive action, not a settings tweak. ## Projects A project is a mounted filesystem within an org. Owners and members with sufficient permissions can: - **Create** a new project - **Rename** a project - **Archive** a project (read-only, unmounts for day-to-day use, reversible) - **Delete** a project (removed from active use straight away; its files, history, git-LFS objects, and stored data are permanently purged 30 days after deletion, and there is no self-serve undelete. Recovery is not guaranteed - [contact us](https://swarmfile.com/contact) before the purge window closes to discuss it. The 30-day window is fixed; a shorter per-user trash-retention setting does not shorten it. A very large entry tree is removed through a durable background job rather than the immediate cascade, so a big delete can take a while to finish; the CLI waits for it by default and `op status` shows its progress.) Deletion writes durable audit rows that outlive the purge, so it remains auditable after the data is gone. A project can also be cloned and pushed with git once an owner turns on git access (`swarmfile git enable`, the web project menu, or the Desktop App's **Project settings → Git access**) - see [Cloning a Project with Git](https://swarmfile.com/docs/guides/git-clone). ### Archived projects are read-only Archiving freezes a project's content until someone unarchives it. Every change is refused with `403 project_archived`, whether it comes from the desktop drive, the web, the CLI, an API key, git-LFS, or a share link: - saving, uploading, creating, renaming, moving, or deleting files - commits and changelists, branches (create, merge, archive, protection rules), tags, and merge requests - publishing releases, RFIs, labels, and comments (adding or resolving, including through a share link) - changing access: granting permissions, switching the project's ACL mode, or creating new share links (revoking existing access still works) - taking a lock: file locks, offline checkouts, folder reservations, byte-range locks, and `git lfs lock` What keeps working: - reading, browsing, downloading, and history - **unarchiving** the project - taking a public release down, revoking access (removing an existing grant or revoking a share link), and releasing locks (including checking a file back in and `git lfs unlock`) - canceling an upload that was still in progress when the project was archived, so nobody is left waiting for a file that will never arrive If someone still has the drive mounted, a save to an existing file is kept beside it as a separate copy instead of being lost, and a brand-new file's content stays on their machine with a message explaining why it wasn't uploaded. Each project runs in one of two modes: - **Open mode** - the default for every new project; more permissive, suited to small teams or early-stage projects - **Protected mode** - enforces explicit ACL grants on folders and files; opt-in at creation or by switching the project later Mode selection and the underlying ACL model are covered in [Permissions](https://swarmfile.com/docs/admin/permissions) - this page only covers project lifecycle, not access control. ### Project configuration and templates One options manifest is the single source for every create-time control - encryption tier, commit mode, retention, visibility, ACL mode, data plane, project type, default-branch protection, the create-only default branch name, **Ensure Git Compatible**, data residency, and the per-project external-collaborator policy. The web dashboard, the Desktop App, and the CLI all render the same set from it, so a choice looks and behaves the same wherever you create the project. Templates give a new project a starting shape: **Blank**, **Media & post**, **Software (git repository)**, **Revit worksharing**, or **Geospatial**. Where a template defines one, creation seeds a starter ignore file and a folder skeleton; an explicit create option always wins over the template's value. After creation, the project's settings show each effective value and where it came from. `swarmfile project show` prints the same view for scripts, and `swarmfile project set` changes the settings it can - see the [CLI reference](https://swarmfile.com/docs/cli/swarmfile#project) and [Getting Started](https://swarmfile.com/docs/guides/getting-started#creating-a-project). The billing page's three-state entitlements matrix labels each setting **included**, **upgrade**, or **not built**, so a plan gate is visible before you hit it. ## Switching the active organization or project An engine can host several mounts at once - one project (and one branch) per mount - so a single machine can work in more than one project without a second install. The common case is still one active workspace per engine, and switching it is a hot, in-place operation where possible: ```bash swarmfile workspace status # which org/project this engine is on swarmfile workspace list # every org you can reach, plus the current org's projects swarmfile workspace switch --org # adopt that org's default project swarmfile workspace switch --org --project ``` To run more than one project side by side instead of switching, open an additional mount - `swarmfile mounts open --label "..." --project ` (same org only) - and target commands at it with the global `--mount ` flag; `swarmfile mounts list` shows every open mount and which one is `current`. The per-agent version of this setup is documented in [Coding Agents](https://swarmfile.com/docs/guides/coding-agents). Switching is **not** a re-authentication: your session is per-user, not per-org, and already covers every org you belong to. Both same-org and org switches normally happen in place (no engine restart), and a target project whose key has not been released yet is waited for rather than turned into a restart. The engine drains and restarts only when the hot path cannot complete - typically when there is no live mount to re-scope - so the drive may then briefly unmount and return. A hot switch is workspace-wide for the project you are leaving: every mount of that project moves to the new project's active branch (a per-mount branch pin doesn't survive a project change), so open drives follow the switch. A mount on a *different* project stays where it is - and because such a drive can't follow the engine to another **org**, an org switch is refused while one is open (`cross_project_mount_open`). The Desktop App names both before you confirm: the drives that will follow and any that must be closed first. A switch is refused while a changelist is open (submit, cancel, or `--park` it first). A switch doesn't wait for uploads: saves still uploading in the project you're leaving keep uploading in the background, and the Desktop App and `swarmfile status` show them as saving in other projects until they land (see [Reading the sync status](https://swarmfile.com/docs/guides/working-with-files#reading-the-sync-status)). While a switch is running, opening or saving a file on the drive can pause for up to a minute until it finishes, and the Desktop App shows that the drive is switching. A file that was already open in an application before the switch still belongs to the project it came from: its later saves are refused rather than written into the new project, the Desktop App tells you straight away, and when the file closes its unsaved changes are kept on disk and the notification says where. If the application hadn't changed the file before the switch, its first change is refused before anything is written, so Swarmfile has nothing to keep: the changes are still in the application, and the notification says so. Save them under a new name, or switch back and save again. The one exception is an org behind its own SSO - reaching it goes through that org's identity provider, not the built-in one (see [Identity](https://swarmfile.com/docs/admin/identity)). A freshly-provisioned machine auto-adopts an org and project on first sign-in, so there's often nothing to switch - see [Deploying to Your Team](https://swarmfile.com/docs/admin/deploying-to-your-team) for how that default is chosen. ## Inviting members Members are invited by email. An invite generates a link; the invitee accepts it to join the org, landing with the coarse `member` org role (below `admin` and `owner` - see the next section for what that hierarchy gates). Don't look for a role picker on the invite screen; there isn't one - you can't invite someone directly as an admin, only promote them afterward. On a plan with ACLs (Pro and above) the invite form can also pre-grant whole-project **Read** or **Write** access, listed on the pending invitation and applied when it is accepted; an invite sent without picks adds the org membership only, and project access is granted afterward under that project's **Permissions** tab. The plan bounds who can be invited: **Free is a solo tier (one seat)** - the Team tab shows a one-seat notice with an upgrade link instead of the invite form - and a Starter/Pro **trial** is capped at two seats until it converts - or until an owner ends it early from the Billing tab, which the Team tab's seat-limit notice links to (admins see an "ask an owner" note instead). A signup that picks more than two seats skips the trial and starts paid. See [Billing & Plans](https://swarmfile.com/docs/admin/billing-and-plans). Paid Starter, Pro, and Enterprise orgs have no seat ceiling; each seat simply bills at the plan's per-seat rate. What a member can see and do *within a project* is governed by the ACL system described in [Permissions](https://swarmfile.com/docs/admin/permissions); the org role is a separate, coarser layer that gates org-wide admin surfaces (billing, permissions administration, quarantine) rather than per-file access. If your org configures SSO with an auto-provisioning group (see [Identity](https://swarmfile.com/docs/admin/identity)), anyone in that IdP group is added to the org automatically on their first sign-in - no manual email invite needed. SCIM on its own doesn't do this: it syncs your directory into Swarmfile, but org access still requires either that SSO group match or a manual invite. On a public project with access requests enabled, an approved **membership** request arrives through this same invitation flow - the requester accepts the standard email invite to join, and on a protected project the invitation carries the project grant they need to see it ([Public access requests](https://swarmfile.com/docs/admin/permissions#public-access-requests)). ## Removing members An owner or admin removes a member from the **Team** tab (only an owner can remove another owner). The hub stops serving them the org's file content and keys within a few seconds. The web dashboard drops the org for them, and their desktop drive stops serving the org's files, including files it had already cached. A computer that's offline at the time does this when it next reaches the hub. A link to a single block that was issued just before the removal can keep working for up to two minutes until it expires. Their engine also clears its local cache of the project (file listings and cached content) and discards its copy of the project's content key. The one exception is changes they saved that hadn't finished uploading: those stay on their computer, held, and upload if their access is restored. Their desktop app tells them so. The project's key itself isn't changed. For an [end-to-end encrypted](https://swarmfile.com/docs/admin/end-to-end-encryption#when-a-member-is-removed) project, removal also revokes their key wraps, but can't recall key material already on their device. Re-inviting the member restores their access without a reinstall - including the project permissions they held - and their org role comes from the new invitation. To cut a removed member off everywhere, Swarmfile visits each of the org's projects in turn, closing their open connections and revoking their keys there; in a large org this can take a few minutes. The same happens when a guest's access is revoked, your directory deprovisions someone, a device key is revoked, or a group's membership changes. Owners and admins can follow it in **Settings → Access revocations**: what's still in progress, any project Swarmfile couldn't reach (with the reason), and what each finished sweep did - including how many devices confirmed they deleted their cached copy, and a **Retry** for a project whose sweep stopped. Removal also changes the org's peer-to-peer key, the secret your team's computers use to connect directly to each other, so the removed member's computer can no longer join in. Everyone else's desktop app picks up the new key on its own within a couple of minutes, with no restart and no interruption to the drive. If any computer seen in the last seven days is running a client that can't switch keys without restarting, the change waits until those computers update. Owners and admins see a notice with the number of computers in **Settings → Network**, and the org's activity feed records both the postponement and the change when it happens. ## Who can see plan and usage standing Any org member - not just the owner - can see the org's current plan and usage standing: seats, storage, and how close the org is to any limits. This is surfaced in both the Desktop App's plan panel and the web dashboard. This is a deliberate choice, not an oversight. Owner-only areas of the dashboard - billing and usage administration - stay restricted to owners. Permissions administration and quarantine are open to admins as well as owners. The audit log itself is open to any member (ACL-filtered - you see events on entries you can read); only its CSV export, plus quarantine and org-policy events within the feed, stay owner-only. But plan and usage *visibility* is open to everyone on the org, so a member isn't left guessing why an upload is being throttled or what tier the team is on. Usage standing is read-only for members; the **request limits** themselves - the per-org and per-user request ceilings - are configurable from the web dashboard's **Settings → Organization** (owners only), the Desktop App's **Settings → Developer** panel (owners and admins), or `swarmfile admin rate-limits` (owners and admins). `swarmfile admin rate-limits usage` shows the current minute's usage against them, and a raise can be time-boxed (`--for 6h`). A single API key can carry its own ceiling (`swarmfile api-key rate-limit`), which is how a render-farm or agent fleet gets more headroom than one person without raising everyone's. Seat count itself isn't something you set manually - it's derived from live org membership and kept in sync automatically. Details are in [Billing & Plans](https://swarmfile.com/docs/admin/billing-and-plans).