A Project is a persistent repository environment, not one transient agent process. Several repositories can have their own Projects on an appliance. Within one Project, joined humans and authorized factory roles use separate accounts, checkouts and executions while sharing tools and development services.
Decide what should be separate
Use the repository and its access policy as the starting boundary. Two independent applications with different maintainers and data generally need separate Projects. Several agents working on the same repository do not imply that every run needs a new copy of the entire operating environment.
Separate checkouts keep candidate changes distinct; shared tools and services remain shared state. If a dependency upgrade or database migration changes that common environment, coordinate it as a project change. Persistent does not mean hermetic. See the Project model and shared tools and files.
Establish access for each project
- Confirm repository ownership, native forge permissions and the people allowed to join the Project.
- Prepare its toolchain and development services, then verify a human terminal and the repository's check command.
- Configure factory policy and required checks for that repository, rather than copying another project's authority assumptions.
- Authorize appliance capacity and provider sponsorship for the intended roles. A person's access to one repository does not authorize another.
- Confirm that direct SSH or service access has an actual network route when it is needed.
Keep host administration with the operator. Project members do not need personal host root accounts to develop. Provider sponsorship and Git permissions remain separate even when the same person administers both.
Plan simultaneous work
Several persistent Projects can exist without all executing at once. Set concurrency and resource limits according to the builds, tests and services they run. Account for peak memory, CPU-heavy compilation, disk growth, retained artifacts and provider availability. A repository waiting for capacity is different from an issue blocked on an unanswered requirement.
Start with a representative run in each Project. Observe combined load before raising parallelism. Keep enough capacity to administer and recover the machine while work is active. This guide does not prescribe an unmeasured number of agents per CPU or promise linear throughput gains.
Supervise without disturbing unrelated work
Spaces connects live activity to its repository and execution. Investigate the exact run and candidate before intervening. Stopping one factory execution should target that run, preserving human sessions, sibling work and retained services; stopping or deleting the whole Project is a broader operation.
If an execution cannot confirm credential return or process retirement, treat it as unresolved rather than assuming a process exit completed every cleanup step. Use the factory operator reference on GitHub for status, stop and reconciliation semantics.
Preserve state and understand the boundary
Back up the forge, platform state and Project service data with a restore procedure that accounts for their relationship. A checkout alone is not a backup of a running project's database. Keep dependencies and installation scripts in version control when you need to reconstruct tools.
Projects share a host kernel and a machine failure domain. They support a trusted team's collaboration; they are not isolated machines for unrelated hostile tenants. When independent failure domains, stronger isolation or multi-node scheduling are required, evaluate a VM or Kubernetes-based design. Read private infrastructure for access and provider-egress decisions.