> For the complete documentation index, see [llms.txt](https://docs.nuvolos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nuvolos.com/concepts/nuvolos-basic-concepts/organisational-hierarchy.md). # Organisational hierarchy All work in Nuvolos is organised into a three-level hierarchy: * **Organisations** - administrative containers representing a customer entity (typically a university or department). * **Spaces** - self-contained projects within an organisation: a course, a summer school, a research project, or a dataset. * **Instances** - parallel work environments within a Space, holding the actual files, data, and Applications. Three observations make this hierarchy useful to internalise. * First, it determines who can see what: every role applies at one specific level, so access is naturally scoped to the part of the tree where it makes sense. * Second, it determines who pays for what: resource pools (introduced below) attach to organisations or Spaces, so cost-accounting follows the same lines. * Third, it determines how the UI navigates: the breadcrumbs at the top of every screen mirror the tree, with one element per hierarchy level. When you subscribe to Nuvolos, the top-level structure is set up for you as part of the signup process. Faculty members and organisation managers create Spaces and Instances inside it. ## Organisations An organisation is the highest level in Nuvolos. When you log in, you first choose an organisation, then select a Space to work in. By default, one customer entity (such as a university) corresponds to one organisation. In practice, a legal entity may have multiple organisations - for example, to separate different vendor dataset licenses. Organisations own all data and files created by their members. An organisation has two types of members: * **Organisation managers** oversee the organisation's assets. They can create and delete Spaces, request new vendor datasets, and invite faculty members. Managers have view access to all Instances in all Spaces, giving them read access to all data in the organisation. * **Faculty members** can create new Spaces (becoming space administrators automatically) and invite colleagues or students to Spaces where they are administrators. ## Spaces A space is a self-contained project within an organisation, encapsulating both data and software. Spaces can be created for a course, a summer school, a research project, a dataset, or any other activity. Each space contains one or more [instances](#instances), which are separate work environments that allow for access control and sharing between space members. Each space consumes resources - compute time, file storage, database storage, and optionally credits for high-performance workloads. These resources are tracked and billed through resource pools. ### Space access control Access to space contents is controlled at the instance level. Each space has one or more **space administrators** with elevated privileges: * Invite other administrators, editors, and viewers to any instance in the space. * Create new instances. * Editor rights on all instances in the space. The user who creates a space automatically becomes its administrator. ### Space visibility Spaces have visibility settings that control who can access them. This can only be set on space creation. The default setting is **Private**. * **Public** - available to all organisation members, including external members. All users automatically become viewers of the Master instance. * **Faculty-only** - accessible only to faculty members of the organisation. Faculty automatically become viewers of the master instance. Typical example: a vendor dataset with a faculty-wide licence. * **Private** - accessible only to users explicitly invited by the space administrator. Only organisation managers have automatic view access. ## Instances Instances are parallel work environments (branches) within a space. You can create as many instances as you need, allowing a project to be divided into separate experimental runs, different approaches to a codebase, or different versions of an application. Instances can be captured in [snapshots](broken://pages/yVgflisto58fGBHeNnaL) for versioning and distribution. You can transfer files, code, applications, or other data between instances, and revert to previous snapshots as needed. A main branch can hold tested results while each researcher works in their own branch. In teaching use cases, instructors and students typically use different instances, forming separate branches of the same teaching material. ### Instance access control Each space has a **Master** instance created automatically - the primary working instance that acts as the source of truth. The Master Instance can't be deleted, except by removing the entire Space. In education spaces (courses), a second special instance called **Distributed** is also created automatically. The Distributed instance is used by the [distribution process](/concepts/distribution.md) to deliver materials and collect assignments. It is only relevant in teaching workflows - research and dataset spaces do not use it. For details, see [The Distributed instance](broken://pages/ajTAoJD7kAdXEhhZPyR2). Each user can have one of the following roles per instance: * **Instance Editor** - can modify the current state (add, remove, update files, tables, and other objects) and has all viewer rights. * **Instance Viewer** - read access to all snapshots, but cannot create or delete them. * **Instance Observer** - limited to viewing the README at the root of the Workspace. Found only in dataset Spaces, where it lets users discover datasets and request access. ## Use cases for the hierarchy The three-level hierarchy supports a range of workflows: * **Institution-wide vendor data** - vendor datasets reside in the organisation. Organisation managers can see all data across all spaces. * **Teaching a course** - faculty members create a space per course and become its administrator. Students are invited as members. Separate instances can be created per student for assignments, or multi-user instances for group work. Teaching assistants can be granted the space administrator role. * **Managing a research project** - researchers create a space per collaboration and invite collaborators (including from other organisations). Each collaborator can work in their own instance and share results when ready. * **Private workflows** - faculty members create private spaces where only organisation managers have automatic view access. ## Resources and the hierarchy Resource consumption in Nuvolos is tracked through [resource pools](/billing/resource-pools-and-budgets.md), which act as cost centres. Resource pools map onto the organisational hierarchy at two levels: * **Organisation-level mapping** - an entire organisation is mapped to a resource pool. All resource usage across all spaces in the organisation is billed against that pool. There is always a default resource pool associated to every organisation and any new space created in it automatically inherits this mapping. * **Space-level mapping** - individual spaces can be mapped to a different resource pool. This allows, for example, a researcher with their own grant to bill high-performance computation against a separate budget. The resources tracked per pool include: * **Nuvolos Compute Units (NCUs)** - compute time consumed by application runs using "Included" sizes. Each subscription includes an NCU capacity; usage beyond it is charged in credits. See [NCU limits](/administration/monitoring-resource-usage/ncu-limits-and-capacities.md). * **File system storage** - total Nuvolos file system (NFS) storage used across all spaces in the pool. Exceeding the limit triggers daily credit charges. See [File system limits](/administration/monitoring-resource-usage/file-system-limits-and-capacities.md). * **Resting storage** - storage used by [rested spaces](/administration/space-management/resting-spaces.md) (inactive spaces moved to cheaper storage). See [Resting limits](/administration/monitoring-resource-usage/resting-limits-and-capacities.md). * **Credits** - used for high-performance (credit-based) application sizes, database computation, and any overage beyond CU or storage limits. {% hint style="info" %} Resource pool managers can monitor usage across all mapped spaces from the **Resources** dashboard (available in the user menu). Space administrators can see detailed usage for their own spaces. See [Monitoring resource usage](/administration/monitoring-resource-usage.md) for details. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.nuvolos.com/concepts/nuvolos-basic-concepts/organisational-hierarchy.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.