Projects (Teams)
Projects (also called Teams) help you organize resources, manage billing, and collaborate with team members.
What are Projects?
A Project is a workspace that contains:
- All your resources (databases, cache, VPS)
- Team members and their permissions
- Separate billing and invoices
- Isolated networking
- Individual resource limits
Why Use Projects?
Separation
- Development vs Production: Keep environments separate
- Client Work: Separate projects for each client
- Departments: Organize by team or department
- Cost Tracking: Track spending per project
Collaboration
- Invite team members
- Control access with roles
- Share resources safely
- Audit team actions
Organization
- Logical resource grouping
- Clear billing attribution
- Independent limits
- Better management
Creating a Project
Your First Project
When you sign up, you're prompted to create your first project:
- Enter a project name (e.g., "Production", "Development")
- Optionally, pick what you want to run first: a static site, object storage, a pod, a database, a Rapids container or an app
- Click Create project
If you picked something, you go straight to its create page. If you didn't, you land on the dashboard, or on the console page you were opening when you signed up. You can rename the project or add more projects later.
Additional Projects
Create more projects anytime:
- Click the project dropdown in the navigation bar
- Click Create New Project
- Enter a project name
- Click Create project
Project Naming
Choose descriptive names:
- Good: "Production", "Staging", "Client-Acme", "Marketing"
- Avoid: "Project 1", "Test", "Temp"
Switching Between Projects
All project members can switch between projects:
- Click the project dropdown in the navigation
- Click on the project you want to switch to
Current project is marked with a checkmark.
All resources you see and create belong to the current project.
Project Settings
Access project settings:
- Click the project dropdown
- Click Project Settings
Rename Project
Only the project's owner can rename it:
- Go to Project Settings (it opens on the General tab)
- Change the Name in the Project card
- Click Save name
Delete Project
Before you delete a project, remove all of its resources and retained data. This includes stopped, failed or deleting resources; wait for resource deletion to finish. Project deletion cannot be used to remove those resources for you.
Only the owner can delete a project, and personal projects cannot be deleted. Remove all caches, databases, VPS instances and VPS block volumes, storage buckets, Rapids containers and Serverless volumes, static sites, apps, Immich and Nextcloud instances, queues, Kubernetes clusters and load balancers, Floating IPs, uptime checks, registry repositories, private networks, network peerings, and customer-managed secrets first. Retained database backups, VPS snapshots (including exported copies kept after VPS removal), and Serverless volume backups also block deletion until removed. Stopped, failed and deleting resources continue to block deletion until their records are fully removed. The Delete project card lists any remaining blockers.
Billing safeguards also apply: unlink any organizations billed through this project, settle unpaid charges not covered by credits, and wait until current-period usage has been invoiced. You cannot delete the project while any of these billing blockers remain.
Before deleting:
- Back up important data
- Delete all resources manually first (recommended)
- Export invoices
To delete:
- Go to Project Settings, General tab
- Click Delete project at the bottom
- Type the project name to confirm
- Click Delete project
Project API
The project API lets API tokens list and view projects, create and rename them, invite members, list and remove members, and delete projects. Creating a project requires an account-wide token. The existing /api/v1/user/teams endpoint and its response remain unchanged.
| Method and path | Permission | What it does |
|---|---|---|
GET /api/v1/projects | project:read | Lists projects the caller belongs to. |
POST /api/v1/projects | project:create | Creates a project. The token must be account-wide; a token locked to one project cannot create another. Creating a project does not change the console's current project. |
GET /api/v1/projects/{team} | project:read | Gets a project the caller can access. |
PATCH /api/v1/projects/{team} | project:write | Renames a project. Only its owner can do this. |
POST /api/v1/projects/{team}/invitations | project:invite | Invites an email address as admin, editor, viewer or billing. Only the project owner can invite. |
GET /api/v1/projects/{team}/members | project:members:read | Lists accepted members as {id, name, email, role}. The owner is first; roles are owner, admin, editor, viewer or billing. |
DELETE /api/v1/projects/{team}/members/{user} | project:members:delete | Removes a member from this project. Only the owner can do this; the project owner cannot be removed. Returns 204 and revokes that member's tokens locked to this project. |
DELETE /api/v1/projects/{team} | project:delete | Deletes a project. Only its owner can do this. |
Project members can use project:read to list and view projects they belong to. A token locked to one project can reach only that project. Project creation requires an account-wide token. Rename and invitation permissions are separate: project:write allows an owner to rename, while project:invite allows an owner to invite members.
Member access and project deletion are separate opt-in permissions. project:members:read lists accepted members, and project:members:delete lets the owner remove a member without affecting their membership in any other project. The owner cannot remove themselves. Removal revokes only that member's tokens locked to this project; account-wide tokens and tokens locked to other projects remain active. project:delete lets the owner delete a project after verifying their email address. A project cannot be deleted if it is personal, has resources or retained data (including stopped or deleting resources, backups, registry data, or customer-managed secrets), or has a billing blocker. The response is 204; infrastructure cleanup continues in the background. Project-scoped API tokens for the deleted project are revoked, while account-wide tokens remain.
These permissions are opt-in. Existing scoped tokens do not gain them automatically; tokens with the wildcard * keep their existing all-permissions access.
Creating, renaming, inviting, removing members and deleting projects require a verified email address. Project mutations share a limit of 10 requests per minute per user, across that user's tokens and projects.
Invitations use the existing email acceptance flow. The API sends an invitation; it does not add a member directly. Project creation always creates a new project with its own ID, even when its name matches another project; it is not a get-or-create operation and does not use an idempotency key. Team roles do not grant these project API permissions automatically.
Team Management
Everyone in a project can see who else is in it, on the Members tab of Project Settings. Only the project's owner can invite people, change their roles and remove them.
Invite Team Members
- Go to Project Settings and open the Members tab
- Click Invite member
- Enter their email address
- Choose a role: Administrator, Editor, Viewer or Billing
- Click Send invitation, then confirm it's you when asked
The user receives an email invitation, and we email you a copy of what was sent, so an invitation you didn't make can't go unnoticed. Until they accept, the invitation waits under Pending invitations on the Members tab. If they don't have an account yet, the invitation is accepted automatically when they register with that email address.
Team Member Roles
A member's role decides what they can do in the project, in the console and through the API (the CLI and MCP tools included).
- Owner: whoever created the project. The owner can do everything an Administrator can. Some actions are the owner's alone: renaming or deleting the project, inviting people, changing roles, removing members, setting the budget and linking organizations for billing. Product pages name the others: on the container registry, only the owner manages access keys, deletes repositories and images, and sets the retention override.
- Administrator: everything else in the project. An Administrator can create, change and delete resources (container registry repositories and images excepted), read every password and secret, and manage billing.
- Editor: can create and change resources, start and stop them, and work with the data inside them. An Editor cannot delete a resource itself, read VPS root passwords or app admin passwords, open the VPS console, or manage billing.
- Viewer: can see the project's resources and their settings, and nothing more. A Viewer cannot change or delete anything, read any password or secret, see logs, diagnostics or the audit log, or see billing.
- Billing: for whoever pays the invoices. A Billing member sees Billing, the project's members and Support, starts on the Billing page, and can pay invoices and manage cards and billing details. They cannot see or change any resource.
| Administrator | Editor | Viewer | Billing | |
|---|---|---|---|---|
| See resources and their settings | Yes | Yes | Yes | No |
| See logs, diagnostics and the audit log | Yes | Yes | No | No |
| Create, change, start, stop and resize resources | Yes | Yes | No | No |
| Work with the data inside a resource: database, cache and queue passwords, SQL Studio (changes included), bucket objects, S3 access keys and SFTP users, Rapids and static site secrets, the Kubernetes kubeconfig and console | Yes | Yes | No | No |
| Delete a resource itself | Yes | No | No | No |
| Replace a resource's data in place: reinstall a VPS, restore a snapshot over a resource, roll back an app upgrade or a migration | Yes | No | No | No |
| VPS root passwords and the VPS console | Yes | No | No | No |
| App admin passwords, Storage Share and Immich included | Yes | No | No | No |
| Export the audit log, see the raw context of its entries (such as old and new values and IP addresses) and close audit findings | Yes | No | No | No |
| Change a static site's plan | Yes | No | No | No |
| Use the partner API | Yes | No | No | No |
| Billing: cards, billing details, invoices and promo codes | Yes | No | No | Yes |
Changing what is inside a resource is not deleting the resource, so an Editor can still delete table rows in SQL Studio or objects in a bucket, and remove a firewall rule, an S3 access key, an SFTP user, a custom domain or a secret stored through the Secrets API. Restoring a snapshot into a new resource leaves the original untouched, so an Editor can do that too.
Where your role does not allow an action, the console switches it off and says why beside it, or leaves it out. Ask the owner or an Administrator to do it, or ask the owner to change your role.
API tokens follow the same rules. A token never does more than the role of the person who made it, and the role is checked on every call. See Roles and Tokens.
Change Member Role
- Go to Project Settings > Members
- Click the member
- Choose the new role and click Save role, then confirm it's you when asked
The new role applies from the member's next request. Their API tokens follow it too, with nothing to change on the tokens: see Roles and Tokens.
Remove Team Member
- Go to Project Settings > Members
- Click the member, then Remove
- Confirm with Remove member
Removed members lose access to the project at once. You can invite them again later.
Cancel an Invitation
- Go to Project Settings > Members
- Under Pending invitations, click Cancel next to the address
- Confirm with Cancel invitation
The link in their email stops working, and you can invite them again at any time.
Leave a Project
If you're a member (not the owner):
- Go to Project Settings > Members
- Click your own name, then Leave project
- Confirm
You'll lose access to the project immediately. To come back, the owner has to invite you again.
The owner cannot leave their own project.
Project Billing
Each project has separate billing:
Payment Methods
- Each project needs its own payment method
- Payment methods are not shared between projects
- Set a default payment method per project
Invoices
- Generated separately per project
- Monthly billing cycle
- Download invoices per project
Usage Tracking
- Track resource costs per project
- View current month's usage
- See cost breakdown by resource
See Billing & Payments for more details.
Project Resources
Resources belong to projects and cannot be moved between projects:
Create Resources
- Switch to the target project
- Create resources normally
- Resources belong to that project
View Resources
- Only see resources for the current project
- Switch projects to see other resources
Resource Limits
- Limits apply per project
- Each project has independent limits
Project Use Cases
Development & Production
Create separate projects:
Production Project
- Production databases and cache
- Strict team access
- Production payment method
- Higher resource limits
Development Project
- Development/staging resources
- More relaxed access
- Separate billing for cost tracking
- Lower resource limits
Staging Project (optional)
- Pre-production testing
- Identical to production configuration
- Different data
Agency/Freelancer
Create a project per client:
Client-Acme
- All Acme resources
- Invite client team members if needed
- Bill separately per client
- Easy project handoff
Client-TechCo
- All TechCo resources
- Independent billing
- Separate team access
Department/Team Organization
Marketing Team
- Marketing websites
- Analytics databases
- Marketing team members
Engineering Team
- Backend services
- Development databases
- Engineering team access
Data Team
- Analytics databases
- Data processing VPS
- Data team members
Best Practices
Naming
- Use clear, descriptive names
- Include environment (prod, staging, dev)
- Include client/project name
- Be consistent
Organization
- One project per environment minimum
- Separate billing entities
- Separate by team/department
- Keep test projects separate
Team Management
- Give each person the role they need
- Review team members regularly
- Remove members who leave
Security
- Scope API tokens to a single project (the default) so integrations only touch that project — see Account Settings
- Audit team actions regularly
- Remove inactive members
Billing
- One payment method per project
- Clear cost allocation
- Regular usage reviews
- Set a monthly budget with alerts under Billing > Budget
Troubleshooting
Can't Create Resources
Check:
- You're a member of the project, as an Administrator or Editor (a Viewer and a Billing member cannot create resources)
- Project has a payment method (only the owner, Administrators and Billing members can add one)
- Haven't exceeded resource limits
- Selected the correct project
Can't Delete, Reinstall or Read a Password
Check:
- Your role: an Editor cannot delete a resource itself, reinstall a VPS, restore a snapshot over a resource, read VPS root passwords or app admin passwords, or manage billing, and a Viewer or Billing member cannot change resources at all (see the table under Team Member Roles)
- Ask the owner or an Administrator to do it, or ask the owner to change your role
- For an API call, the
403message says whether the token or your role refused it: see Roles and Tokens
Can't See Resources
Check:
- You're in the correct project
- Resources exist in this project
- You have appropriate permissions
- Resources haven't been deleted
Can't Invite Team Members
Check:
- You're the project's owner: only the owner can invite
- Email address is correct
- User hasn't already been invited
- Project limit not exceeded
Invitation Not Received
Tell the invitee to:
- Check spam/junk folder
- Check correct email address
- Wait a few minutes
- Ask you to cancel the invitation and send a new one
Can't Switch Projects
Check:
- You're a member of multiple projects
- Projects exist
- You haven't been removed from project
- Try logging out and back in
Project Limits
Default limits per project (Starter tier; limits depend on your account tier — see Account Limits):
- Team Members: 10
- VPS Instances: 3
- Database Instances: 5
- Cache Instances: 5
- Firewalls: 10
- SSH Keys: 25
Request increases through Account Limits page.
Next Steps
Need help? Contact support through the dashboard.