Members and invitations

Members are the people in a workspace. Each has one role: member, admin or owner. Workspaces and roles says what each can do.

Owners and admins manage the member list. Only an owner can add an owner, or change or remove one. A member whose custom role has members.manage can add and remove members too, but no owner or admin.

Add a member

forculus workspace add acme dana@example.com

dana@example.com is a member of acme. We emailed them a link to the workspace.

Dana gets an email with a link to the workspace in the dashboard. They sign in with a code sent to that address. There’s no password to set.

--role picks the role. The default is member:

forculus workspace add acme dana@example.com --role admin

To change someone’s role, run forculus workspace add again with the new one. A role change sends no email and doesn’t count against the plan.

A member who isn’t an admin or an owner sees this if they try:

error: You don't have permission to do that.

The invitation email

The subject is “You’ve been added to a workspace on Forculus”. The email says who added them, to which workspace and with what role, for example “ana@example.com added you to the workspace Acme as a member.” The link goes to the workspace’s page in the dashboard.

A workspace sends at most 50 invitation emails in any 24 hours, and one person sends at most 100 across all their workspaces. Sharing an app counts too. Forculus also limits how many it sends in a day across all workspaces, which leaves room for sign-in codes. Past any of these limits, the person is still added but no email goes out. The dashboard, the CLI and the MCP server tell you when that happens and which limit it was, so you can send the link yourself:

dana@example.com is a member of acme. We didn't email them: acme has sent all the invitation emails a workspace may in a day. Send them a link to the workspace yourself.

The audit log records each invitation as mail.sent, or mail.skipped when a limit was reached.

List the members

forculus workspace members acme

owner   ana@example.com
member  dana@example.com
member  sam@example.com

forculus workspace show acme shows your own role, the plan, where its data is kept, the allowed email domains and what the plan allows:

acme (Acme)
your role: owner
plan: free
data kept in: the US
allowed email domains: any
apps: 3
members: 3
container apps: none on this plan
custom domains: none on this plan
pull requests' previews at once: 3
audit log kept: 3 months
single sign-on: no
scim: no
audit log as csv: no
audit log streams: none on this plan

Remove someone

forculus workspace remove acme dana@example.com

Removed dana@example.com from acme.

Dana also loses every app in the workspace that was shared with them, and leaves its groups. Their access ends within a minute, open connections included. The audit log’s member.remove entry lists the apps they lost.

An app shared with everyone at Dana’s domain still lets Dana in as a viewer, as it lets in anyone at example.com, member or not. You’re told which:

Removed dana@example.com from acme. acme/hello is still shared with @example.com, which lets them in as a viewer.

forculus --json workspace remove lists those apps under still_shared_by_domain, and so does the member.remove entry in the audit log. To shut Dana out of one, unshare it with the domain. The bypass tokens Dana made stop working on their next request and are marked revoked, each with a token.revoke in the log.

Some removals are refused:

You see	Because
error: A workspace needs at least one owner.	They are the last owner. Make someone else an owner first.
error: They're the only owner of hello. Make someone else an owner of it, or delete it, first.	An app would be left with no owner. Share it with another owner first.
error: Not found: dana@example.com isn't a member of acme, or you're not in acme.	They aren’t a member, or you aren’t.
error: You don't have permission to do that.	You’re a member, or an admin removing an owner.

Leave a workspace

Anyone can leave, whatever their role. Remove your own address:

forculus workspace remove acme ana@example.com

The last owner can’t leave, and neither can the only owner of an app:

error: A workspace needs at least one owner.

error: You're the only owner of hello. Make someone else an owner of it, or delete it, first.

Limit who can join

Allowed email domains keep a workspace to your company’s addresses:

forculus workspace domains acme example.com,example.org

Members and sharing are limited to example.com, example.org.

The list applies in three places:

• Adding a member at another domain is refused: This workspace only allows members from its allowed email domains.
• Sharing an app with another domain, by an address or as a domain, and adding someone at another domain to a group, is refused, and the allowed domains are named: acme only allows addresses at example.com, so hello can't be shared with pat@gmail.com.
• The edge checks it on every request. People at other domains stay listed, but within a minute they can’t open any app in the workspace. That includes you, if your own address isn’t on the list. Bypass tokens made by anyone outside the list are revoked.

A list that leaves out the domain of your own address is refused, unless you say you mean it. If you’re at corp.com:

error: Your own email, ana@corp.com, isn't at example.com or example.org, so this would lock you out of every app in this workspace within a minute. Add corp.com to the list, or run again with --yes to save it anyway.

Add --yes to save it anyway. In the dashboard, saving such a list asks you first.

A list has up to 20 domains, each a hostname like example.com. Anything else gets You can allow up to 20 domains, like example.com. A domain matches exactly: example.com doesn’t let in mail.example.com.

To see the list, leave the domains out:

forculus workspace domains acme

Members and sharing are limited to example.com, example.org.

To let any domain in again:

forculus workspace domains acme --clear

Members and sharing are open to any email domain.

Groups

A group is a named list of people, to share apps with all at once. Workspace owners and admins make groups and choose who is in them. App owners see them, to share their apps with one.

forculus group create acme finance

Made the finance group in acme. Add people with `forculus group add acme finance <email>`.

A name is up to 30 lower-case letters, digits and single dashes, like finance or field-team.

forculus group add acme finance sam@example.com

Added sam@example.com to the finance group.

Adding someone who’s in the group already changes nothing, and says sam@example.com is already in the finance group. Anyone can be in a group, member of the workspace or not, as anyone can be a viewer. When the workspace has allowed email domains, only addresses at those domains can be added. Adding someone sends no email, and a group lets nobody in until an app is shared with it.

forculus group list acme

finance (2 people)
  lee@example.com
  sam@example.com

To take someone out:

forculus group remove acme finance sam@example.com

Took sam@example.com out of the finance group. What the group gave them ends within 60 seconds.

To delete the group, and every share it had, add --yes. Putting it back means making the group again and sharing each app with it again, so without --yes nothing is deleted:

forculus group delete acme finance --yes

Deleted the finance group. The apps shared with it stop letting its people in within 60 seconds.

Removing someone from the workspace, or their leaving it, takes them out of its groups too. A workspace has up to 100 groups, and a group up to 500 people. People in a group aren’t members, and don’t count against the plan.

A group can give a custom role to the members in it. Only owners and admins choose who is in such a group, and say which role it gives.

Your identity provider can keep groups over SCIM. Who is in one of those is changed in the provider, and forculus group list says kept by your identity provider beside it. You can still share apps with it, or delete it.

Plan limits

Every member counts against the plan, owners included: 3 on Free, 25 on Team, and 200 on Business and Enterprise. At the limit, adding one more is refused:

error: This workspace has 3 members. The Free plan allows 3. Remove one or upgrade. Team allows 25 members. Billing: https://app.forculuslabs.tech/w/acme/billing

People you only share an app with, as viewers, aren’t members and don’t count. See Limits for the rest.

In the dashboard

Go to the workspace’s Members page.

• Add member opens a dialog for an email and a role. Add sends the invitation.
• To give someone one app, use Share on that app instead. It shares the app and, for an editor or owner, adds them to the workspace in the same step. See Share an app.
• The role menu on each row changes a role. Admins see Member and Admin. Owners also see Owner.
• The remove button on a row takes that person out. On your own row it leaves the workspace.
• Admins and members can also leave from the workspace’s Settings, even before they’ve accepted the terms.

Groups, below the members, lists the workspace’s groups and who is in each. Owners and admins can make a group, add and remove people, and delete a group there.

Allowed email domains are under Settings, one domain per line. When a new list would shut out current members, the dashboard names them and asks you to confirm.

Next steps

• Workspaces and roles
• Share an app
• Audit log: member.put, member.remove and member.leave record every change, and group.create, group.delete, group.member_put and group.member_remove every change to a group.