> For the complete documentation index, see [llms.txt](https://docs.kinesis.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kinesis.network/getting-started/running-llms-with-kinesis-network/understanding-grids.md).

# Grids and shared capacity

Organize the organization's compute and control how people share capacity.

A grid groups servers that applications can target. It belongs to an organization. Its admins manage the machines, policies, visibility and sharing; developers deploy apps to grids they can access, and viewers inspect them.

## Use or build a grid

Choose one or more grids in an app's **Resources** settings. Check the hardware, available capacity and the app creator's quota before launch. An app targets a grid through `config.grids.ids` in the public API.

Admins provision dedicated machines in **Servers** or attach the organization's existing infrastructure, then add them to a grid. They can also configure marketplace capacity in the portal. Only admins change grid composition or policies. Shared access is for use, not management.

A grid can be **Private** or visible to **Everyone at your organization**. Admins add members through Share. See [Sharing and visibility](/organizations/sharing.md).

## Quotas belong to people

Grid quotas count against **the person who created the app**, whoever starts or changes it. Everyone is counted, including admins, unless an admin explicitly exempts a person or app.

| Limit     | What is counted on the grid                                                 |
| --------- | --------------------------------------------------------------------------- |
| GPUs      | GPU capacity held by one person's apps; a GPU slice counts as one GPU       |
| Apps      | Distinct apps with live placements; an app counts once on each grid it uses |
| Instances | Running containers on that grid's machines                                  |

Stopped apps do not count. An app targeting several grids can place containers across grids with remaining room. The portal pre-check refuses configurations that cannot run at all: no targeted grid has app room, or their combined instance room is below the app's **minimum** instances. Runtime limits apply to live placements, not the declared maximum scale.

Admins configure **Policies → Quotas** in the portal. Each cap has its own switch. The public API and MCP do not expose quota-policy management.

## Read quota and scheduling signals

| Signal                             | Meaning and next step                                                                            |
| ---------------------------------- | ------------------------------------------------------------------------------------------------ |
| `START_BLOCKED` / `QUOTA_EXCEEDED` | The creator has no room under a quota; free capacity, lower the minimum or ask an admin          |
| `UpdateDeferred`                   | A larger GPU request is on hold until quota permits it                                           |
| `ScaleCapped`                      | The app runs on fewer instances than it requires because app or instance quota limits placement  |
| `EvictionPending`                  | Newest placements exceed a lowered cap and will stop after the grace period                      |
| `OverCapKept`                      | A stateful or restart-disabled app exceeds a cap but is warned rather than automatically stopped |

Lowering a cap can stop newer over-limit placements after the configured grace period, default ten minutes. Zero means the next check. Stateful and restart-disabled apps are warned rather than stopped automatically.

**Fair share** gives people turns when a grid is full, counting by app creator. Apps queue, give up placements after their turn and can queue again. **Idle reclaim** can remove idle workloads after a warning. **Hold behavior** determines whether idle marketplace capacity is retained or released.

Separate **Container Limits** apply to every container, including quota-exempt people and apps. Some changes restart containers, and lowering memory below usage can stop an app. Review the portal's affected-app confirmation when changing those limits.

## Move a grid

Admins of both organizations can move an unused grid from its **Settings**. A server can move from its actions menu only when it is in no grid. The dialog shows blockers and the complete transfer. See [Move resources](/organizations/move-resources.md).

## Operate and inspect

Grids show their creator and machine counts, with filters remembered per organization. Servers are grouped by grid by default, with an **In use by** column and filters for source, state and whose apps are running. Admin server actions appear in the organization's audit log.

Inspect an app's quota lines, runtime errors, queue position and History when placement stalls. The [monitoring guide](/getting-started/running-llms-with-kinesis-network/monitoring-apps.md) explains where to look.

Deleting a grid can stop apps that have no remaining target. Apps with other usable grids can continue there. Review the affected apps and retarget them before removing capacity.

[Grids API](/api/grids.md) · [Servers API](/api/servers.md)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kinesis.network/getting-started/running-llms-with-kinesis-network/understanding-grids.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.