Skip to content

Add the sandbox link protocol, relay core and Sandbox I/O bootstrap - #338

Merged
SaladDay merged 1 commit into
feature/agent-outside-sandboxfrom
aos/link-protocol
Oct 1, 2026
Merged

SaladDay merged 1 commit into
feature/agent-outside-sandboxfrom
aos/link-protocol

Conversation

@SaladDay

@SaladDay SaladDay commented Sep 30, 2026 •

Copy link
Copy Markdown
Collaborator

Adds the Link protocol. Agent-host Runtimes (attach peers) and Sandbox I/O services (serve peers) use it to reach each other through a relay. The relay authenticates both sides, authorizes each service stream and splices it opaquely. It also adds the Provider–Sandbox I/O startup input.

  • internal/sandboxlink/protocol.go defines the protocol:
    • the handshake: ServeHello, AttachHello, HelloAccepted;
    • opening a stream: Open/Opened from the attacher, Bind/Bound to the serve peer;
    • the control messages;
    • typed failures;
    • the Authority interface;
    • ServiceNetwork and the egress rules;
    • the file export grant: File binds carry Exports, a list of ExportGrant{ID, ReadOnly}.
  • Transport: libp2p/go-yamux/v5 over a binary WebSocket over TLS. Streams keep FIN (CloseWrite) distinct from abort (Reset).
    • The dialers enforce TLS: wss://, or ws:// to a loopback host. Core serves the relay behind the installation's HTTPS ingress.
  • internal/sandboxwire gains RequestSequence: RequestIDs strictly increase on a stream, per sender.
  • Peers and relay:
    • the serve peer reconnects with the same ServerInstanceID;
    • the attach peer;
    • the relay/ core, which Core embeds in M2. It handles leases, generation staleness, RevokeAttachment and RevokeResource.
  • sandboxlinktest is a fixture Authority plus a TLS relay, used by the M1 lanes.
  • internal/sandboxbootstrap is the strict startup file: version, link_url, credential, resource. The File service serves the single export world, rooted at the sandbox's /.
  • Docs: docs/sandbox-link-protocol.md owns the shared ## Framing section, and docs/sandbox-bootstrap.md covers the startup file. Both have AGENTS.md boundary rows and repository-map rows.

Out of scope: Core's route and database authority (M2), and the oac-sandbox-io binary (a later lane).

Checks:

  • go test -race over the link, relay and bootstrap packages; the relay package also ran with -count=20
  • FuzzDecode, 30 s
  • go vet, gofmt
  • darwin and windows builds

Part of the agent-outside-sandbox work, milestone M1, lane L3.


View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.

@SaladDay
SaladDay force-pushed the aos/link-protocol branch 2 times, most recently from 8be23cd to 87896c1 Compare October 1, 2026 00:06
@SaladDay
SaladDay merged commit f8d72fd into feature/agent-outside-sandbox Oct 1, 2026
12 checks passed
@SaladDay
SaladDay deleted the aos/link-protocol branch October 1, 2026 00:07
Define the Link protocol between the agent-host Runtime, the Sandbox I/O
service and the relay in internal/sandboxlink: sandboxwire-framed control
messages, typed failures, the Authority interface, serve and attach peer
libraries over yamux on WebSocket, and a relay that authorizes, binds and
splices service streams with leases, generations and revocation. File
binds carry export grants and Network binds carry egress rules. Peers
dial only wss:// or loopback ws:// relay URLs.

Add sandboxwire.RequestSequence, the strictly increasing request ID rule
the sandbox I/O protocols share, and use it for Link control streams.

Add internal/sandboxbootstrap for the Provider-to-service startup file,
the two protocol documents and their AGENTS.md and development.md rows.
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.

1 participant