docs: add HOST_FUNCTIONS.md for guest host surface

[cachebag]

Document __dispatch tools, CLI flags, limits, and security model.

Closes #42.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a comprehensive reference document describing the Hyperlight host tool/host-function surface exposed to Unikraft guests, including defaults, opt-in flags, wire format, and security boundaries.

Changes:

• Documents the __dispatch JSON request/response envelope and debug behavior.
• Enumerates filesystem (fs_*) and network (net_*) tools, resource limits, and enablement flags.
• Summarizes security posture/attack surface and provides a small programmatic API example.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[danbugs]

Thank you so much for the contribution! Just some comments here and there :)

[cachebag]

hey! @danbugs sorry for some of the slop :p the same session i used to debug building the examples i used to write/understand the docs.

Would also be good to make an issue to expand --enable-tools to actually allow a CLI user to provide different host functions.

Agreed definitely. I'm still getting my bearings but we could probably run the handler in a wasm runtime? I guess it would be something like --tool greet=./foo.wasm. adds a bit of overhead but in my mind it seems nicer than spawning a subprocess or plugin or something.

[danbugs]

hey! @danbugs sorry for some of the slop :p the same session i used to debug building the examples i used to write/understand the docs.

No worries--thank you for taking the time to run the examples and understand the host function mechanism and attack surface :)

Agreed definitely. I'm still getting my bearings but we could probably run the handler in a wasm runtime? I guess it would be something like --tool greet=./foo.wasm. adds a bit of overhead but in my mind it seems nicer than spawning a subprocess or plugin or something.

I'm not sure. Wasm does seem like a good format to distribute host functions and getting the sandboxing for free is nice, but it will inevitably restrict what the host function can do. If we're going that route, maybe a scripting language like Lua/Rhai works best (i.e., to remove the compilation step) and then hyperlight-unikraft can just have an embedded lightweight Lua/Rhai interpreter behind a feature flag? I created an issue tracking this w/ some of my thoughts: #84

[danbugs]

LGTM--again, thanks for contributing!!