Workspaces & Projects
How tenancy, projects, services, and environments fit together
Workspaces & Projects
Workspace
A workspace is the top-level container for everything you do on Parslinks. It owns:
- Members and their roles, plus invitations
- Projects (all of them)
- Billing and plan entitlements
Your workspace has a slug used in URLs and API paths. In the HTTP API you will
see /organizations/:slug — this is a historical path segment; the product
concept is the workspace.
Project
A project groups related work. It is a container, not a deployable unit:
- Holds services (the things that actually run)
- Holds environments (production, previews, custom)
- Owns shared infrastructure: the project Docker network, volumes policy, and settings
Deleting a project is safe by design: it first disables (pauses instances, drops routes) then waits through a 14-day undo window before anything is purged. See Deleting & Restoring.
Services
A service is the unit of source, build, networking, and resources. Every service has exactly one source type:
| Type | Meaning |
|---|---|
git | Connected repository + branch; Parslinks builds it |
image | Prebuilt OCI image from a registry |
template | Created from a versioned recipe in the catalog |
resource | A managed adapter (Postgres, Redis, …) or an external resource brokered by a plugin |
Creating a service automatically inserts one instance into every live environment of the project — production today, plus every preview and custom environment.
Environments
An environment is an isolated copy of the whole project graph. Three kinds:
| Kind | Behavior |
|---|---|
| Production | Tracks your deploy branch |
| Preview | Catch-all for branches without a dedicated environment |
| Custom | Tracks an explicit branch you choose |
Environments are where deployments belong and where domains are scoped. A deployment always belongs to exactly one environment.
Instances
An instance is service × environment. It carries:
- The environment-specific deployment pointer (
current deployment) - Instance variables and references to shared variables
- Clone/pause state
- Placement intent: per-region desired replica count
Scaling an instance means changing its placement intent — it never rebuilds or creates a new release.
Where things are owned
Parslinks runs as focused microservices. You don't interact with them directly, but knowing the ownership explains platform behavior:
- catalog-service — workspace/project/service/environment identity, instances, placement intent, variables, source connections
- build-service — build execution, ArtifactSets, deployments, aliases
- edge-service — domains, TLS status, routing
- runtime-service — replica-sets (workloads), volumes, networks, console
- observability-service — logs and metrics
- billing-service — plans, usage, credits