Skip to content

feat(runtime): switch shim config to file path and harden env delivery#260

Open
shayne-snap wants to merge 4 commits intoboxlite-ai:mainfrom
shayne-snap:refactor/core-envs-to-file
Open

feat(runtime): switch shim config to file path and harden env delivery#260
shayne-snap wants to merge 4 commits intoboxlite-ai:mainfrom
shayne-snap:refactor/core-envs-to-file

Conversation

@shayne-snap
Copy link
Copy Markdown
Contributor

@shayne-snap shayne-snap commented Feb 13, 2026

Fix #227 (comment). Moving large configuration from command-line arguments to a file (--config-file) aligns with the Docker/Podman approach of using OCI config.json.

Key changes

  • write InstanceSpec to per-box shim-config.json and spawn shim with --config-file to avoid oversized argv payloads
  • keep shim compatible with legacy --config while preferring file-based config loading
  • make guest entrypoint env overrides atomic and keep user container env delivery on the ContainerInit/gRPC path
  • add unit and integration tests for env visibility and large env payload delivery

Testing

@shayne-snap shayne-snap changed the title feat(runtime): switch shim config to file path and harden env delivery feat(shim): switch shim config to file path and harden env delivery Feb 13, 2026
@shayne-snap shayne-snap changed the title feat(shim): switch shim config to file path and harden env delivery feat(runtime): switch shim config to file path and harden env delivery Feb 13, 2026
@shayne-snap shayne-snap marked this pull request as ready for review February 13, 2026 12:12
@DorianZheng
Copy link
Copy Markdown
Member

Hi @shayne-snap. The initial design is to make BoxOptions as the ground truth of box definition. And there is a plan to serialize and persistent BoxOptions as a file for future conflict check. So I'm not sure we need to serialize shim args as a file.

@shayne-snap
Copy link
Copy Markdown
Contributor Author

Hi @shayne-snap. The initial design is to make BoxOptions as the ground truth of box definition. And there is a plan to serialize and persistent BoxOptions as a file for future conflict check. So I'm not sure we need to serialize shim args as a file.

Oh, I see. I agree that BoxOptions should be the the ground truth of box definitions.

The new shim config file is NOT a second source of truth; it mainly avoids argv size/quoting limits when spawning the shim and is not used for recovery or conflict checks.

Should reduce the scope?(write less info into the file) or wait until things become more clear?

@DorianZheng
Copy link
Copy Markdown
Member

Hi @shayne-snap. The initial design is to make BoxOptions as the ground truth of box definition. And there is a plan to serialize and persistent BoxOptions as a file for future conflict check. So I'm not sure we need to serialize shim args as a file.

Oh, I see. I agree that BoxOptions should be the the ground truth of box definitions.

The new shim config file is NOT a second source of truth; it mainly avoids argv size/quoting limits when spawning the shim and is not used for recovery or conflict checks.

Should reduce the scope?(write less info into the file) or wait until things become more clear?

Got it. Does this PR solve the silent exit issue of passing process.env?

@shayne-snap
Copy link
Copy Markdown
Contributor Author

Hi @shayne-snap. The initial design is to make BoxOptions as the ground truth of box definition. And there is a plan to serialize and persistent BoxOptions as a file for future conflict check. So I'm not sure we need to serialize shim args as a file.

Oh, I see. I agree that BoxOptions should be the the ground truth of box definitions.
The new shim config file is NOT a second source of truth; it mainly avoids argv size/quoting limits when spawning the shim and is not used for recovery or conflict checks.
Should reduce the scope?(write less info into the file) or wait until things become more clear?

Got it. Does this PR solve the silent exit issue of passing process.env?

Yes. Works on my laptop.

for (key, value) in &guest_rootfs.env {
builder.with_env(key, value);
}
for (key, value) in &options.env {
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @shayne-snap. We add this to the guest because we allow the user to exec command in the guest vm directly through env BOXLITE_EXECUTOR=guest.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch!

For BOXLITE_EXECUTOR=guest, I merge BoxOptions.env into the exec-time env (with BoxCommand.env taking precedence), so guest-direct exec keeps the previous semantics without reintroducing cmdline-length risk.

write InstanceSpec to per-box shim-config.json and spawn shim with --config-file to avoid oversized argv payloads

keep shim compatible with legacy --config while preferring file-based config loading

make guest entrypoint env overrides atomic and keep user container env delivery on the ContainerInit/gRPC path

add unit and integration tests for env visibility and large env payload delivery
@shayne-snap shayne-snap force-pushed the refactor/core-envs-to-file branch from 21575b1 to 1cd5803 Compare February 20, 2026 05:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants