[PR #329] [MERGED] feat(sandbox): request free-page reporting order 6 and add tuning guide

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/329 **Author:** [@LSX-s-Software](https://github.com/LSX-s-Software) **Created:** 9/30/2026 **Status:** ✅ Merged **Merged:** 9/30/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `feat/fpr` --- ### 📝 Commits (1) - [`1701d09`](https://github.com/kvcache-ai/AgentENV/commit/1701d09e8dcaa844fd782c1b59fb19139bfa7fbc) feat(sandbox): set free-page reporting order and add tuning guide ### 📊 Changes **2 files changed** (+2 additions, -2 deletions) <details> <summary>View changed files</summary> 📝 `config/default.toml` (+1 -1) 📝 `docs/src/configuration/reference.md` (+1 -1) </details> ### 📄 Description ## What Add `page_reporting.page_reporting_order=6` to the shipped Firecracker boot arguments. With 4 KiB guest pages, order 6 allows reporting free blocks starting at 256 KiB on kernels that honor the boot parameter. ## Why The usual order 9 threshold leaves smaller free blocks unreported. Users need a way to tune the memory/CPU tradeoff and distinguish a command-line setting from the effective runtime value. ## Scope and non-goals Update the shipped TOML configuration. No Rust implementation, guest kernel, generated API, or automatic runtime sysfs write changes. ## Compatibility and operations - Public API or generated protocol: unchanged. - Configuration or defaults: the shipped `boot_args` now requests order 6. The Rust fallback boot arguments are unchanged. The default KVM guest kernel, 6.1.175, overrides this value during balloon registration, so users must write sysfs after guest readiness or supply a kernel containing the upstream fix. Linux 6.2+ honors the explicit parameter; the default PVM guest kernel is 6.12.33. - Snapshot manifest, artifact layout, or storage format: unchanged; existing snapshots do not acquire new boot arguments. - Upgrade and rollback: restart the server to load configuration changes and cold-boot new guests to apply boot arguments. Remove or change the argument to revert the configuration; existing guests require a runtime write or replacement. - Host requirements, permissions, ports, or dependencies: unchanged. Runtime tuning requires guest root access to the sysfs parameter. ## Validation - [ ] `make fmt` - [ ] `make clippy` - [ ] `make test-unit` - [ ] Relevant Rust integration tests - [ ] `make -C services test` (required when `services/` changes) - [ ] Generated clients/server regenerated with the documented `make` target - [x] Documentation updated - [ ] Benchmarks or performance comparison completed Commands and results: ```text git diff --check 875faeec...35d90712: passed mdbook build docs: passed (mdbook-mermaid 0.5.0 / mdbook 0.5.2 compatibility warning) Python tomllib validation of HEAD:config/default.toml: passed; order=6 appears exactly once Documentation link targets: verified locally ``` Skipped checks and reasons: Rust, Go, and code-generation checks were not run because this change only touches configuration and documentation. No new VM validation or performance comparison was run for this PR. ## Risks and reviewer notes Lower reporting orders may reduce retained host memory at the cost of additional guest/VMM CPU work; no measured improvement is claimed. The configured order 6 is not the effective default on the bundled KVM 6.1.175 kernel. Review the kernel-compatibility section together with `config/default.toml`. ## Checklist - [x] The PR contains one coherent change and no unrelated formatting or refactoring. - [x] New behavior is covered by tests, or I explained why testing is impractical. - [x] Logs and examples contain no credentials, tokens, or private registry information. - [x] I did not manually edit generated code without updating its source and regenerating it. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi commented

2026-10-29 14:22:31 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/329
Author: @LSX-s-Software
Created: 9/30/2026
Status: ✅ Merged
Merged: 9/30/2026
Merged by: @yingdi-shan

Base: main ← Head: feat/fpr

📝 Commits (1)

1701d09 feat(sandbox): set free-page reporting order and add tuning guide

📊 Changes

2 files changed (+2 additions, -2 deletions)

View changed files

📝 config/default.toml (+1 -1)
📝 docs/src/configuration/reference.md (+1 -1)

📄 Description

What

Add page_reporting.page_reporting_order=6 to the shipped Firecracker boot arguments. With 4 KiB guest pages, order 6 allows reporting free blocks starting at 256 KiB on kernels that honor the boot parameter.

Why

The usual order 9 threshold leaves smaller free blocks unreported. Users need a way to tune the memory/CPU tradeoff and distinguish a command-line setting from the effective runtime value.

Scope and non-goals

Update the shipped TOML configuration. No Rust implementation, guest kernel, generated API, or automatic runtime sysfs write changes.

Compatibility and operations

Public API or generated protocol: unchanged.
Configuration or defaults: the shipped boot_args now requests order 6. The Rust fallback boot arguments are unchanged. The default KVM guest kernel, 6.1.175, overrides this value during balloon registration, so users must write sysfs after guest readiness or supply a kernel containing the upstream fix. Linux 6.2+ honors the explicit parameter; the default PVM guest kernel is 6.12.33.
Snapshot manifest, artifact layout, or storage format: unchanged; existing snapshots do not acquire new boot arguments.
Upgrade and rollback: restart the server to load configuration changes and cold-boot new guests to apply boot arguments. Remove or change the argument to revert the configuration; existing guests require a runtime write or replacement.
Host requirements, permissions, ports, or dependencies: unchanged. Runtime tuning requires guest root access to the sysfs parameter.

Validation

make fmt
make clippy
make test-unit
Relevant Rust integration tests
make -C services test (required when services/ changes)
Generated clients/server regenerated with the documented make target
Documentation updated
Benchmarks or performance comparison completed

Commands and results:

git diff --check 875faeec...35d90712: passed
mdbook build docs: passed (mdbook-mermaid 0.5.0 / mdbook 0.5.2 compatibility warning)
Python tomllib validation of HEAD:config/default.toml: passed; order=6 appears exactly once
Documentation link targets: verified locally

Skipped checks and reasons: Rust, Go, and code-generation checks were not run because this change only touches configuration and documentation. No new VM validation or performance comparison was run for this PR.

Risks and reviewer notes

Lower reporting orders may reduce retained host memory at the cost of additional guest/VMM CPU work; no measured improvement is claimed. The configured order 6 is not the effective default on the bundled KVM 6.1.175 kernel. Review the kernel-compatibility section together with config/default.toml.

Checklist

The PR contains one coherent change and no unrelated formatting or refactoring.
New behavior is covered by tests, or I explained why testing is impractical.
Logs and examples contain no credentials, tokens, or private registry information.
I did not manually edit generated code without updating its source and regenerating it.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

bsakaguchi

closed this issue
added the
pull-request
label

bsakaguchi referenced this issue

2026-10-29 14:22:43 +00:00

[PR #352] [MERGED] chore(deps): bump google.golang.org/grpc from 1.83.1 to 1.83.2 in /services #372

Rows
Columns

[PR #329] [MERGED] feat(sandbox): request free-page reporting order 6 and add tuning guide #352