[PR #268] [MERGED] fix(tools-image): fall back to BusyBox sh for images without /bin/sh

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/AgentENV/pull/268 **Author:** [@zlzGithub-0801](https://github.com/zlzGithub-0801) **Created:** 9/9/2026 **Status:** ✅ Merged **Merged:** 9/10/2026 **Merged by:** [@yingdi-shan](https://github.com/yingdi-shan) **Base:** `main` ← **Head:** `fix/guest-binsh-fallback` --- ### 📝 Commits (1) - [`f8c2a23`](https://github.com/kvcache-ai/AgentENV/commit/f8c2a2328c87ef8ab567a852686422be789cbc91) fix(tools-image): improve compatibility with minimal and Ubuntu images ### 📊 Changes **4 files changed** (+9 additions, -4 deletions) <details> <summary>View changed files</summary> 📝 `tools-image/Dockerfile` (+1 -1) 📝 `tools-image/Makefile` (+1 -1) 📝 `tools-image/init` (+0 -1) 📝 `tools-image/pivot-init` (+7 -1) </details> ### 📄 Description ## What Improve tools-image compatibility with minimal and Ubuntu-based guest images: - provide a BusyBox-backed `/bin/sh` when the guest image does not include one; - initialize `/etc/hosts` when it is missing or empty; - defer `/var/run` handling until after `pivot_root`. ## Why Some OCI images do not provide `/bin/sh` or rely on the container runtime to populate an empty `/etc/hosts`. Ubuntu-based images also define `/var/run` as an absolute symlink to `/run`, which is resolved against the tools drive before `pivot_root`. These cases can prevent command execution, break `localhost` resolution, or produce a pre-pivot directory creation error. ## Related issue Closes #202. ## Scope and non-goals This PR only updates guest bootstrap behavior in the tools image. It does not change public APIs, snapshot formats, or the tools-image upgrade mechanism. ## Design and behavior changes After pivoting into the guest rootfs: - link `/bin/sh` to the bundled BusyBox when `/bin/sh` is unavailable; - populate `/etc/hosts` with IPv4 and IPv6 localhost mappings when the file is missing or empty; - preserve an existing executable `/bin/sh` and non-empty `/etc/hosts`. Before `pivot_root`, avoid accessing `/mnt/user/var/run`. The existing post-pivot initialization handles `/var/run` after absolute symlinks resolve within the guest rootfs. ## Compatibility and operations - Public API or generated protocol: Unchanged. - Configuration or defaults: Unchanged. - Snapshot manifest, artifact layout, or storage format: Unchanged. - Upgrade and rollback: Requires a new tools-image release. Existing snapshots retain their recorded tools version. - Host requirements, permissions, ports, or dependencies: No new requirements. ## Validation  - [ ] `make fmt` - [ ] `make clippy` - [ ] `make test-unit` - [x] 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 Skipped checks and reasons: Rust, services, generation, and benchmark checks were not run because this change only adds a shell bootstrap fallback. ## Risks and reviewer notes N/A ## Checklist - [x] The PR contains one coherent change and no unrelated formatting or refactoring. - [x] New behavior is covered by manual testing. - [x] Logs and examples contain no credentials, tokens, or private registry information. - [x] No generated code was changed. --- <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:00 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/AgentENV/pull/268
Author: @zlzGithub-0801
Created: 9/9/2026
Status: ✅ Merged
Merged: 9/10/2026
Merged by: @yingdi-shan

Base: main ← Head: fix/guest-binsh-fallback

📝 Commits (1)

f8c2a23 fix(tools-image): improve compatibility with minimal and Ubuntu images

📊 Changes

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

View changed files

📝 tools-image/Dockerfile (+1 -1)
📝 tools-image/Makefile (+1 -1)
📝 tools-image/init (+0 -1)
📝 tools-image/pivot-init (+7 -1)

📄 Description

What

Improve tools-image compatibility with minimal and Ubuntu-based guest images:

provide a BusyBox-backed /bin/sh when the guest image does not include one;
initialize /etc/hosts when it is missing or empty;
defer /var/run handling until after pivot_root.

Why

Some OCI images do not provide /bin/sh or rely on the container runtime to populate an empty /etc/hosts. Ubuntu-based images also define /var/run as an absolute symlink to /run, which is resolved against the tools drive before pivot_root.

These cases can prevent command execution, break localhost resolution, or produce a pre-pivot directory creation error.

Closes #202.

Scope and non-goals

This PR only updates guest bootstrap behavior in the tools image. It does not change public APIs, snapshot formats, or the tools-image upgrade mechanism.

Design and behavior changes

After pivoting into the guest rootfs:

link /bin/sh to the bundled BusyBox when /bin/sh is unavailable;
populate /etc/hosts with IPv4 and IPv6 localhost mappings when the file is missing or empty;
preserve an existing executable /bin/sh and non-empty /etc/hosts.

Before pivot_root, avoid accessing /mnt/user/var/run. The existing post-pivot initialization handles /var/run after absolute symlinks resolve within the guest rootfs.

Compatibility and operations

Public API or generated protocol: Unchanged.
Configuration or defaults: Unchanged.
Snapshot manifest, artifact layout, or storage format: Unchanged.
Upgrade and rollback: Requires a new tools-image release. Existing snapshots retain their recorded tools version.
Host requirements, permissions, ports, or dependencies: No new requirements.

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

Skipped checks and reasons: Rust, services, generation, and benchmark checks were not run because this change only adds a shell bootstrap fallback.

Risks and reviewer notes

N/A

Checklist

The PR contains one coherent change and no unrelated formatting or refactoring.
New behavior is covered by manual testing.
Logs and examples contain no credentials, tokens, or private registry information.
No generated code was changed.

_{🔄 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:16 +00:00

[PR #303] [MERGED] fix(overlaybd): dispatch remote image I/O onto a dedicated remote-io runtime #331

Rows
Columns

[PR #268] [MERGED] fix(tools-image): fall back to BusyBox sh for images without /bin/sh #303