Skip to content

feat(sdk): add orchestration API for multi-box messaging#206

Merged
DorianZheng merged 2 commits intomainfrom
feat/orchestration-api
Feb 4, 2026
Merged

feat(sdk): add orchestration API for multi-box messaging#206
DorianZheng merged 2 commits intomainfrom
feat/orchestration-api

Conversation

@DorianZheng
Copy link
Copy Markdown
Member

@DorianZheng DorianZheng commented Feb 4, 2026 •
edited
Loading

Summary

  • Add BoxRuntime orchestration API with decorator syntax
  • Cloudpickle serialization for closures (auto-installed via pip in guest)
  • Auto-detected Python version for image selection (no image param needed)
  • Point-to-point messaging (send_message) and pub/sub events (publish_event)
  • Minimal implementation (~400 lines, down from initial ~1200)

Key Features

from boxlite.orchestration import BoxRuntime

async with BoxRuntime() as runtime:
    worker = await runtime.create_box(name="worker")
    
    multiplier = 2  # Closure captured!
    
    @worker.on_message
    def handle(sender, data):
        return {"result": data["value"] * multiplier}
    
    await worker.run()

Changes

Component Change
sdks/python/boxlite/orchestration/ New orchestration module
guest/src/main.rs Boot logging (info level default)
boxlite/src/vmm/ RUST_BACKTRACE forwarding
examples/python/ai_pipeline/ Pipeline example (Coder→Reviewer→Tester)
examples/python/multi_agent/ Multi-agent messaging example

Test plan

  • python examples/python/multi_agent/host.py - passes
  • python examples/python/ai_pipeline/host.py - passes

@DorianZheng
feat(sdk): add Ray-style orchestration API for multi-box messaging
76864c7 
Add BoxRuntime orchestration API with:
- Ray-style decorator API (@box.task, @box.on_message, @box.on_event)
- Cloudpickle serialization for closures (auto-installed via pip)
- Auto-detected Python version for image selection
- Point-to-point messaging and pub/sub events between boxes
- Minimal implementation (~400 lines total)

Also includes:
- Guest boot logging improvements (info level default)
- RUST_BACKTRACE forwarding to guest
- Two comprehensive examples (ai_pipeline, multi_agent)
@DorianZheng DorianZheng changed the title feat(sdk): add Ray-style orchestration API for multi-box messaging feat(sdk): add orchestration API for multi-box messaging Feb 4, 2026
@DorianZheng DorianZheng merged commit 7e7c943 into main Feb 4, 2026
20 checks passed
@DorianZheng DorianZheng deleted the feat/orchestration-api branch February 4, 2026 22:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@DorianZheng