---
title: "Size the runtime's memory to the box · Agent Wranglers"
url: https://agentwranglers.se/playbook/operations/capacity-and-resilience/runtime-memory-limits
id: OPS-41
level: Required
applies: servers
risk: outage
updated: 2026-10-27
build: a2a6bdfed830
tokens: 1088
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Size the runtime's memory to the box

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Capacity and resilience](https://agentwranglers.se/playbook/operations/capacity-and-resilience.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: OPS-41
- Level: Required
- Chapter: [Capacity and resilience](https://agentwranglers.se/playbook/operations/capacity-and-resilience.md)
- Rule: When the language runtime manages memory itself, as Java, Node, .NET and Go do, cap its heap below the container or service limit. It then frees memory before the system kills it.
- Check: For a runtime with a garbage collector, the start command sets the heap cap at no more than half the service limit. Send staging twice the expected peak traffic. Peak memory stays below 80 percent of the service limit, and the process is never killed. The 95th percentile response time is unchanged by the caps.
- Risk: The app down or unusable
- Applies when: The project runs its own servers, virtual machines or containers.
- How: Java and Node read the container limit but take a fixed default share of it, which rarely fits the service. Languages without a garbage collector, such as Rust or C, skip the heap cap and keep the service limit alone. Go sets no memory limit unless told. All keep freed memory reserved. Cap the main heap at about half the service limit. On small boxes, also shrink the young generation, which can reserve tens of megabytes. Examples are Node's `--max-old-space-size` and `--max-semi-space-size`, Java's `-XX:MaxRAMPercentage` and Go's `GOMEMLIMIT`. Read files on request instead of loading every one at start. Measure peak memory under the [load test](https://agentwranglers.se/playbook/testing/performance-tests/load-tests.md) after each change. Set the service limit itself as [Set limits on memory and processes](https://agentwranglers.se/playbook/operations/running-the-service/resource-limits.md) says.
- Measured: On a reference site with a 260 MB service limit, shrinking the young generation took peak memory under load from 190 to 139 MB. Response times stayed at 42 ms.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### INI example

```ini
# systemd drop-in for a Node service with a 260 MB limit
[Service]
Environment="NODE_OPTIONS=--max-old-space-size=128 --max-semi-space-size=4"
MemoryHigh=200M
MemoryMax=260M
```

### Shell example

```sh
# Java in a container: heap as a share of the container limit
java -XX:MaxRAMPercentage=50 -jar app.jar
# Go: a soft limit the garbage collector works to stay under
GOMEMLIMIT=200MiB ./app
```

## Sources

- [Node.js command-line options, --max-old-space-size](https://nodejs.org/api/cli.html)
- [Go garbage collector guide, memory limit](https://go.dev/doc/gc-guide)

## Related rules

- TST-36 [Test load against a budget](https://agentwranglers.se/playbook/testing/performance-tests/load-tests.md) in Testing
- OPS-34 [Set limits on memory and processes](https://agentwranglers.se/playbook/operations/running-the-service/resource-limits.md) in Operations and observability
- INF-79 [Set resource requests and a memory limit on every container](https://agentwranglers.se/playbook/infrastructure/containers-and-orchestration/kubernetes-requests-and-limits.md) in Infrastructure and environments

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/operations/capacity-and-resilience/runtime-memory-limits">Agent Wranglers operations and observability playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Stop calling a failing service with a circuit breaker](https://agentwranglers.se/playbook/operations/capacity-and-resilience/circuit-breakers.md)
- Next: [Warn before resources run out](https://agentwranglers.se/playbook/operations/capacity-and-resilience/exhaustion-alerts.md)
- [Capacity and resilience](https://agentwranglers.se/playbook/operations/capacity-and-resilience.md)