Provider plugin

Third parties integrate macOS (or other external) desktops without API changes by implementing ExternalDesktopProvider and registering a catalog kind. Windows VMs use the built-in ec2-vm backend; this plugin path is for driver_hint: external.

Flow

Port: sandboxes_service/ports/external_desktop_provider.py

Checklist for a new kind

1. Implement ExternalDesktopProvider in sandboxes_service/infrastructure/external_desktop/providers/<kind>.py
2. Register with @register_external_desktop_provider("<kind>")
3. Add catalog profile YAML with driver_hint: external and desktop_provider.kind
4. Add GSM secret + Helm secret_ref mapping
5. Unit tests with a mocked vendor API
6. Extend verify-viewer-macos-dev.sh --kind <kind> or add a dedicated verify script
7. Document operator notes in docs/sandbox/desktop/PROVIDERS.md

Auth rules (non-negotiable)

• Provider credentials via secret_ref only — never on public POST /v1
• Adapter receives tenant_id / project_id for naming and storage prefixes
• Stream must be proxyable through sandboxes (private network path documented)
• No provider-specific fields on the trainer-facing create body — catalog selects the plugin

Registration example

from sandboxes_service.infrastructure.external_desktop.registry import (
    register_external_desktop_provider,
)

@register_external_desktop_provider("macstadium")
class MacStadiumProvider:
    kind = "macstadium"
    ...

Reference implementations

Out of scope (v1)

• Daytona (Harbor worker environment override — not this plugin)
• Remote webhook control plane (see ADR 0002)

Related

• Providers
• Desktop architecture
• Operations