> ## Documentation Index > Fetch the complete documentation index at: https://docs.nonce.app/llms.txt > Use this file to discover all available pages before exploring further. # Rack groups, templates and layouts > How Nonce models containers, the racks inside them, and where they sit in a farm > [!NOTE] > > Rack groups, templates and layouts are in beta and available through [Nonce MCP](https://docs.nonce.app/api-guide/mcp/index.md) only. Their operations do not appear in the API Reference. ## Overview A farm describes its physical layout with three objects: | Object | What it describes | | - | - | | **Rack group** | A container or similar unit, identified by its subnets | | **Template** | The racks in a rack group, the rows and columns of each rack, and how miners take slots | | **Layout** | Where each rack group sits in the farm: rows, positions, stacking, and aisles | Nonce places each miner in a slot from its IP address. The farm must give its miners fixed IP addresses; when a miner's IP changes, its slot changes with it. *** ## Rack groups A rack group has its own `id`. Its `subnets` are an attribute: one or more IPv4 subnets from /16 to /24 that hold the miners of the rack group. | Field | Description | | - | - | | `id` | Rack group ID | | `name` | Unique within the farm; `null` until someone names it | | `subnets` | Subnets of the rack group in CIDR notation | | `template_id` | Template the rack group uses; `null` without one | | `start_offset` | Offset within the subnets of slot 1, for templates that assign slots in IP order | | `miner_count` | Miners in the subnets, stale miners included | | `summary` | Real-time health of the miners, counted the same way as `QueryFarmMinerMetrics` counts a farm | Every /24 subnet that has miners but no rack group gets a new unnamed rack group the next time rack groups are read. Rack groups therefore cover every IPv4 miner of the farm, and setup starts by naming and configuring the rack groups Nonce already created. To list the miners of a rack group, search miners with `ip_ranges` set to its subnets. ### Changing subnets When a container spans more than one /24 subnet, replace the subnets of one rack group with the full range. > [!WARNING] > > New subnets absorb every other rack group whose subnets all fall within them. The absorbed rack groups are deleted together with their names and templates. A subnet that only partly overlaps another rack group is rejected. Review the affected rack groups before you change subnets. *** ## Templates A template sets the number of racks in a rack group, the rows and columns of each rack, and how miners take slots. | Field | Range | Description | | - | - | - | | `racks` | 1–20 | Racks in the rack group | | `rows` | 1–50 | Rows in each rack | | `columns` | 1–50 | Columns in each rack | | `mode` | `sequential` or `dynamic` | How miners take slots | ### Slot modes | Mode | Behavior | | - | - | | `sequential` | Each IP has a fixed slot. Slot 1 holds the miner at `start_offset` within the subnets, and each following IP takes the next slot. Missing miners leave empty slots. | | `dynamic` | Miners fill slots in IP order without gaps. | For a rack group with a single /24 subnet, `start_offset` is the last octet of the first miner's IP. For example, with `start_offset` set to `11`, the miner at `x.x.x.11` takes slot 1. ### System and farm templates | Type | Description | | - | - | | System templates | Describe common container models. Shared by every farm and read-only. | | Farm templates | Created by the farm for models that no system template describes. Names are unique within the farm. | Use `ListRackGroupTemplates` to see the templates available to a farm. Changing a farm template changes every rack group that uses it. Deleting a farm template leaves those rack groups without a template. *** ## Layouts A layout places rack groups in the farm. It is saved as a whole. * **Rows** run from the front of the farm to the back. * **Positions** run along each row. A position is empty or stacks one or two rack groups, listed from the floor up. * **Aisles**: each row can be followed by a `cold` or `hot` aisle, or none. * A rack group takes at most one position. `rows` is `null` until someone arranges the farm. A saved layout may still refer to rack groups that were deleted since, for example after a subnet change absorbed them; skip those when you read it. ### Concurrent edits Pass the `updated_at` you read with `GetFarmLayout` as `expected_updated_at` when you save with `UpdateFarmLayout`, or `null` if no layout was saved. If someone else saved the layout in between, the save is rejected with `409`. Read the layout again, reapply your change, and save. *** ## Legacy racks Rack groups replace the earlier rack model. | Item | Status | | - | - | | `ListRacks` | Deprecated. Still returns racks; use `ListRackGroups` instead. | | Miner `rack` field | Kept and readable. | | `CreateRackUpdateTaskBatch` | Removed. | There is no operation that writes a slot for an individual miner. Slots follow from IP addresses, the rack group template, and `start_offset`. *** ## Permissions | Operation | Permission | | - | - | | Reading rack groups, templates and layouts | `miner.read` | | Changing rack groups, templates and layouts | `miner.manage` | Both are checked against the target farm. These writes change farm configuration only; they do not send commands to miners. ## Operations | Operation | Description | | - | - | | `ListRackGroups` | List all rack groups of a farm with their miner summaries. Not paginated. | | `UpdateRackGroups` | Name rack groups, set their template and start offset, or replace their subnets, in one transaction. | | `ListRackGroupTemplates` | List system templates and farm templates. | | `CreateRackGroupTemplate` | Create a farm template. | | `UpdateRackGroupTemplate` | Change a farm template. | | `DeleteRackGroupTemplate` | Delete a farm template. | | `GetFarmLayout` | Get the layout of a farm. | | `UpdateFarmLayout` | Replace the layout of a farm. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.