Workspaces and roles

A workspace holds your apps, the people who work on them, a plan and an audit log. Each person in it has a workspace role. Each app also has its own list of people, with app roles. This page covers both kinds of role and how they fit together.

Workspaces

Every app belongs to one workspace, and its name starts with the workspace’s slug: acme/hello is the app hello in the workspace acme. The slug is also in the app’s address, https://hello--acme.forculuslabs-apps.tech.

A workspace also has:

Members, each with a workspace role: member, admin or owner.
A plan. It sets how many apps and members the workspace can have. See Plans and billing.
An audit log of every request to its apps and every change made to it. See Audit log.
Optionally, allowed email domains. Only people at those domains can join or be shared with.

Signing up doesn’t make a workspace. You create one, or someone adds you to theirs.

Create a workspace

forculus workspace create acme

Created workspace acme. You're its owner.

The slug can use lowercase letters, digits and single dashes, up to 30 characters. You can’t change it later. The dashboard calls it the short name. --name sets a display name. Without it, the display name is the slug. You can also create a workspace in the dashboard.

We refuse slugs that look like a well-known brand, like Forculus, or like a sign-in page, such as paypal-login or secure-account. A brand next to ordinary words is refused too, like stripe-reports, because nobody can tell a tool for a brand’s customers from a page pretending to be the brand.

Ordinary words on their own are fine: billing-admin and support-tools both work. A sign-in word like login or password works only next to a word that says what the tool is, like visitor-sign-in or password-manager. So sso-login and login-portal are refused.

App slugs are checked together with the workspace’s, because an app’s address holds both. account is fine, but not in a workspace called verify.

A new workspace is on the Free plan. You can own up to 50 workspaces. Workspaces you’re only a member of don’t count. Deleted ones you can still restore do, since they keep their data until then.

A workspace keeps its apps’ data in the US. Keeping it in the EU, for Enterprise, isn’t open yet: see Keeping data in the EU.

Errors you may see:

error: That short name is taken by another workspace, or one deleted in the last 30 days. Pick another.

A deleted workspace keeps its slug for 30 days, even once it’s deleted for good, so you can’t reuse the slug straight away.

error: Use up to 30 lowercase letters, digits and single dashes for a workspace slug.

error: That short name looks like a brand or a sign-in page, and it would be in every app's address. Pick another.

See your workspaces

forculus workspace list

acme                           owner   free      acme

The columns are the slug, your role, the plan and the display name.

forculus workspace show acme

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

On a paid plan, a price: line says what the workspace’s subscription costs a month. A subscription keeps the prices it started with, so it can differ from the pricing page, and then workspace show says so. Single sign-on, SCIM, the CSV and audit log streams are Enterprise features. On Business each of their lines ends with for early customers for a limited time:

single sign-on: yes, for early customers for a limited time
scim: yes, for early customers for a limited time
audit log as csv: yes, for early customers for a limited time
audit log streams: 1, for early customers for a limited time

forculus workspace members acme

owner   ada@example.com
admin   bob@example.com
member  grace@example.com

Workspace roles

	member	admin	owner
Open apps shared with them, or open to the whole workspace	Yes	Yes	Yes
Create apps, and own the ones they create	Yes	Yes	Yes
See the workspace’s members	Yes	Yes	Yes
Manage every app: deploy, configure, share and delete	No	Yes	Yes
Add and remove members and admins	No	Yes	Yes
Read the audit log and the workspace’s usage	No	Yes	Yes
Rename the workspace and set its allowed email domains	No	Yes	Yes
See the workspace’s billing	No	Yes	Yes
Add and remove owners	No	No	Yes
Change the plan	No	No	Yes
Export the workspace, or an app’s database	No	No	Yes
Delete the workspace	No	No	Yes

To split duties more finely, give members custom roles: one that reads the audit log and can’t deploy, or one that adds and removes members and nothing else.

An owner deletes a workspace in the dashboard, under the workspace’s Settings, then Danger zone. forculus workspace delete <workspace> opens that page and says what to choose there. A deleted workspace is kept for 30 days, and an owner can restore it until then: see Backups and restore. It isn’t kept while an owner of it or of one of its apps has yet to accept our terms, and the page says so before you delete. It’s the owners’ data, so only their terms decide, whoever deletes it.

A workspace always has at least one owner. Members and invitations covers adding and removing people. To add someone:

forculus workspace add acme grace@example.com

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

--role admin or --role owner adds someone with that role, or changes the role of someone already in the workspace. Only an owner can make someone an owner, or change or remove an owner. An admin who tries sees:

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

App roles

Each app has its own list of people and their roles. Whoever creates an app is its owner.

	viewer	editor	owner
Open and use the app	Yes	Yes	Yes
See the app’s versions	No	Yes	Yes
Deploy, roll back and rename it	No	Yes	Yes
Manage its environment variables, secrets and bypass tokens	No	Yes	Yes
Share it, and change its visibility	No	No	Yes
Open public paths on it and set their verifiers, in the dashboard	No	No	Yes
Delete it	No	No	Yes
Has to be a member of the workspace	No	Yes	Yes

You give someone an app role by sharing the app with them:

forculus share acme/hello grace@example.com --role editor

A viewer can be anyone with an email address. Editors and owners work on the app through the workspace, so they have to be members first:

error: Editors and owners must be members of the workspace. Add them first with `forculus workspace add acme grace@example.com`, then share again.

Only a workspace owner or admin can add members. If you own the app but aren’t one of them, you’re told to ask one.

An app always has at least one owner. Taking the role from the last one fails with An app needs at least one owner. See Share an app for more on sharing.

Your app sees the role too, as the role claim in the identity token, so your code can let editors do more than viewers. The SDK overview shows how to check it.

Visibility

An app is private or open to the whole workspace:

private, the default: only the people it’s shared with can open it.
workspace: every member of the workspace can open it as a viewer, as well as the people it’s shared with.

forculus app visibility acme/hello workspace

Everyone in acme can view acme/hello.

forculus app visibility acme/hello private

acme/hello is private. Only people you share it with can reach it.

Changing visibility counts as sharing, so you need to be an app owner, or a workspace owner or admin. You can also set it with forculus deploy --create --visibility workspace when the deploy creates the app.

Delete an app

forculus app delete acme/hello --yes

Deleted acme/hello. You can restore it until 2026-11-03 14:05 UTC with `forculus app restore acme/hello`.

Without --yes, nothing is deleted, and it says what happens to the app’s data:

error: This deletes acme/hello and revokes its tokens. Its database, files and versions are kept for 30 days, and `forculus app restore acme/hello` brings it back. If that's no longer so when you delete it, nothing is deleted. Run again with --yes --kept.

With --kept, if an owner who has yet to accept our terms was added since and deleting it would now be final, nothing is deleted and it says so. --yes alone deletes it either way, and says after whether it was kept.

The app goes offline and its bypass tokens are revoked straight away. The app, its versions, database and secrets are kept for 30 days, and can be restored until then: see Backups and restore. For up to a minute after, the app can still answer people who had it open in a browser, and callers on its public paths. Those requests are in the audit log under the deleted app. A request that gets that far after the app has gone is refused as if there were no app. It’s in the log too, and it isn’t counted toward your plan. The app’s entries stay in the log until they age out. To delete an app, you need to be an app owner, or a workspace owner or admin.

When the app isn’t kept, it says Deleted acme/hello for good. It can't be restored. instead, and without --yes it warns as below. It isn’t kept while an owner of the workspace or of the app has yet to accept our terms, whoever deletes it, since it’s the owners’ data: see when deletion is immediate.

forculus app delete acme/hello --yes --for-good deletes it now instead, with its database and files, and then nothing can be restored. Without --yes it says so:

error: This deletes acme/hello, its database, its files and its versions for good, and revokes its tokens. Nothing can be restored, so export the database first: forculus db export acme/hello. Run again with --yes.

You can’t delete an app while a version is still going live, such as a site with thousands of files:

error: Version 4 of this app is still going live. Try again once it's done.

forculus versions acme/hello shows when that version is deployed or failed. Then delete it.

How roles combine

The two kinds of role answer different questions.

Who can open the app. Only app roles and visibility count here. You get in when the app is shared with you, or when it’s open to the workspace and you’re a member. A workspace owner or admin with no app role can’t open a private app. They can share it with themselves, though, since they manage every app:

forculus share acme/notes bob@example.com

bob@example.com can now use acme/notes as a viewer. We emailed them the app's link.

Who can change the app. Here a workspace owner or admin counts as an owner of every app in the workspace. They can deploy, share and delete any app without an app role. Everyone else needs the right app role: editor to deploy, owner to share.

So:

The role in the identity token is your app role. On an app open to the workspace, a member with no app role gets viewer.
forculus app list acme shows owners and admins every app in the workspace. Members see the apps shared with them and the apps open to the workspace.
Someone you share an app with doesn’t need to be in the workspace. They can open the app in a browser, or call it with forculus curl, and they can’t see anything else in the workspace.
Removing someone from the workspace also removes every app role they had in it. If they are the only owner of an app, make someone else its owner first:
```
error: They're the only owner of hello. Make someone else an owner of it, or delete it, first.
```

Allowed email domains

An owner or admin can limit a workspace to addresses at your company’s domains:

forculus workspace domains acme example.com

Members and sharing are limited to example.com.

Your own address’s domain has to be on the list, or you’re shut out too. A list without it is refused unless you add --yes. The list also shuts out people at other domains who already have access. Limit who can join covers where it applies and how to clear it.

Leave a workspace

Anyone can leave a workspace by removing their own address with forculus workspace remove. The last owner can’t, and neither can the only owner of an app. See Leave a workspace.

Limits

The plan sets how many members and apps a workspace can have. Free allows 3 members and 3 apps. Adding one more fails, and the message names the plan that allows more:

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

Every member counts toward the limit, owners and admins included. People you only share an app with as viewers aren’t members, so they don’t count. We check the limit only when someone new joins, so you can always change a member’s role. See Limits for every plan’s numbers.

Next steps

Share an app to give people app roles.
Members and invitations to add people to the workspace.