[PR #322] fix(tools-image): map guest hostname in /etc/hosts

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/322 **Author:** [@LSX-s-Software](https://github.com/LSX-s-Software) **Created:** 9/27/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `fix/tools` --- ### 📝 Commits (2) - [`4773102`](https://github.com/kvcache-ai/AgentENV/commit/477310253592ee59fd8b861b76bb6cd2fc8ded5d) fix(tools-image): map guest hostname in `/etc/hosts` - [`137f99b`](https://github.com/kvcache-ai/AgentENV/commit/137f99b563ff3141995a0dacdddf8c28cc6a5bed) revert(tools-image): revert version update ### 📊 Changes **4 files changed** (+41 additions, -9 deletions) <details> <summary>View changed files</summary> 📝 `tools-image/Dockerfile` (+2 -2) 📝 `tools-image/Makefile` (+1 -1) 📝 `tools-image/README.md` (+6 -6) 📝 `tools-image/pivot-init` (+32 -0) </details> ### 📄 Description ## What Fix guest self-hostname resolution for tools-image bootstrap (issue #319). `pivot-init` now appends an idempotent `127.0.1.1 <hostname>` mapping when the existing `/etc/hosts` does not contain the guest hostname. ## Why Firecracker sets the guest hostname to `instance`, but images with a non-empty `/etc/hosts` may not contain that name. Files-only lookup and Java `InetAddress.getLocalHost()` then fail. A loopback mapping remains valid when a sandbox resumes with a different guest IP. ## Related issue Closes #319 ## Scope and non-goals The change is limited to tools-image bootstrap behavior and the immutable tools drive release metadata. It does not change host networking, the Firecracker `ip=` format, or any public API. ## Design and behavior changes `pivot-init` reads the current guest hostname, ignores empty or invalid names, checks existing hosts aliases, and appends a loopback entry only when needed. Existing image-provided hosts entries are preserved and repeated boots do not add duplicates. ## Compatibility and operations - Public API or generated protocol: N/A. - Configuration or defaults: Tools drive release bumped from `0.1.1` to immutable version `0.1.2`; the new image must be published before rollout. - Snapshot manifest, artifact layout, or storage format: No schema or snapshot layout change. Existing snapshots retain their recorded tools drive version. - Upgrade and rollback: Publish `0.1.2` before deploying the manifest update. Rollback can restore the previous manifest version; existing snapshots remain version-pinned. - Host requirements, permissions, ports, or dependencies: No new host requirements. ## Validation - [ ] `make fmt` - [ ] `make clippy` - [ ] `make test-unit` - [x] Relevant tools-image and Firecracker integration validation - [ ] `make -C services test` (not applicable; no services changes) - [ ] Generated clients/server regenerated (not applicable) - [x] Documentation updated - [ ] Benchmarks or performance comparison completed (not applicable) Commands and results: ```text make -C tools-image build TOOLS_VERSION=0.1.2 PASS sh -n tools-image/pivot-init PASS git diff --check PASS cargo run --bin server -- --setup-only (isolated state/local registry) PASS Firecracker guest cold start: hostname, files lookup, Java self-lookup PASS Firecracker guest pause/resume hostname lookup PASS ``` Skipped checks and reasons: Rust workspace format, clippy, and unit suites were not run because this PR changes only shell bootstrap code, tools-image build metadata, documentation, and the dependency manifest. The focused image build and real guest validation covered the changed behavior. ## Risks and reviewer notes The GHCR tools image tag is immutable. The release workflow is manual; `ghcr.io/kvcache-ai/agentenv-tools:0.1.2` must exist before nodes using the updated manifest are deployed. The tested guest resolved `instance` locally as `127.0.1.1` on cold start and after pause/resume. ## 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:26 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/322
Author: @LSX-s-Software
Created: 9/27/2026
Status: 🔄 Open

Base: main ← Head: fix/tools

📝 Commits (2)

4773102 fix(tools-image): map guest hostname in /etc/hosts
137f99b revert(tools-image): revert version update

📊 Changes

4 files changed (+41 additions, -9 deletions)

View changed files

📝 tools-image/Dockerfile (+2 -2)
📝 tools-image/Makefile (+1 -1)
📝 tools-image/README.md (+6 -6)
📝 tools-image/pivot-init (+32 -0)

📄 Description

What

Fix guest self-hostname resolution for tools-image bootstrap (issue #319). pivot-init now appends an idempotent 127.0.1.1 <hostname> mapping when the existing /etc/hosts does not contain the guest hostname.

Why

Firecracker sets the guest hostname to instance, but images with a non-empty /etc/hosts may not contain that name. Files-only lookup and Java InetAddress.getLocalHost() then fail. A loopback mapping remains valid when a sandbox resumes with a different guest IP.

Closes #319

Scope and non-goals

The change is limited to tools-image bootstrap behavior and the immutable tools drive release metadata. It does not change host networking, the Firecracker ip= format, or any public API.

Design and behavior changes

pivot-init reads the current guest hostname, ignores empty or invalid names, checks existing hosts aliases, and appends a loopback entry only when needed. Existing image-provided hosts entries are preserved and repeated boots do not add duplicates.

Compatibility and operations

Public API or generated protocol: N/A.
Configuration or defaults: Tools drive release bumped from 0.1.1 to immutable version 0.1.2; the new image must be published before rollout.
Snapshot manifest, artifact layout, or storage format: No schema or snapshot layout change. Existing snapshots retain their recorded tools drive version.
Upgrade and rollback: Publish 0.1.2 before deploying the manifest update. Rollback can restore the previous manifest version; existing snapshots remain version-pinned.
Host requirements, permissions, ports, or dependencies: No new host requirements.

Validation

make fmt
make clippy
make test-unit
Relevant tools-image and Firecracker integration validation
make -C services test (not applicable; no services changes)
Generated clients/server regenerated (not applicable)
Documentation updated
Benchmarks or performance comparison completed (not applicable)

Commands and results:

make -C tools-image build TOOLS_VERSION=0.1.2                         PASS
sh -n tools-image/pivot-init                                         PASS
git diff --check                                                     PASS
cargo run --bin server -- --setup-only (isolated state/local registry) PASS
Firecracker guest cold start: hostname, files lookup, Java self-lookup  PASS
Firecracker guest pause/resume hostname lookup                         PASS

Skipped checks and reasons:

Rust workspace format, clippy, and unit suites were not run because this PR changes only shell bootstrap code, tools-image build metadata, documentation, and the dependency manifest. The focused image build and real guest validation covered the changed behavior.

Risks and reviewer notes

The GHCR tools image tag is immutable. The release workflow is manual; ghcr.io/kvcache-ai/agentenv-tools:0.1.2 must exist before nodes using the updated manifest are deployed. The tested guest resolved instance locally as 127.0.1.1 on cold start and after pause/resume.

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 added the

pull-request

label

Rows
Columns

[PR #322] fix(tools-image): map guest hostname in /etc/hosts #346