Skip to content

Add the file access protocol, Linux file service and client - #340

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

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

Conversation

@SaladDay

@SaladDay SaladDay commented Sep 30, 2026 •

Copy link
Copy Markdown
Collaborator

Adds the Runtime–file service protocol: the agent host uses it to read and write the sandbox file system. The protocol is FUSE-shaped and handle-based, and phase 1 is the Uncached profile.

  • internal/sandboxfs/protocol.go defines the protocol:
    • 30 operations and every request/response type;
    • NodeRef, HandleID, Attr, DirEntry;
    • Capabilities, typed failures and the semantic Errno;
    • strict codecs on internal/sandboxwire.
  • The same package has the generic client and server:
    • The server runs requests concurrently up to a bound and handles CancelRequest itself.
    • When the transport is lost, the client fails in-flight requests with EffectPossible.
  • apps/sandboxio/internal/fileservice is the Linux service:
    • an O_PATH|O_NOFOLLOW node table and a handle table;
    • *at lookups. Symlinks, including proc magic links, stay opaque: the service never follows one, and it reopens only descriptors it holds after checking their type;
    • node identity is (mount ID, dev, ino) with generation fencing, so bind aliases never merge;
    • atomic append and exclusive create;
    • renameat2 modes, probed at startup;
    • flock on the handle's own fd, which interoperates with native processes;
    • the errno table and incarnation checks.
    • POSIX record locks are not advertised.
  • Spec amendments included:
    • Describe reports the service identity (uid/gid).
    • Export grants come from the Link binding: Attach needs a grant, and a read-only grant makes the attachment read-only.
    • Export isolation: the service serves the single export world. oac-sandbox-io roots it at /, and the Provider's sandbox setup owns the topology's isolation. There is no userspace containment probe.
    • RequestIDs strictly increase on a stream, using sandboxwire.RequestSequence.
  • docs/file-access-protocol.md documents it, with an AGENTS.md boundary row and repository-map rows for internal/sandboxfs and apps/sandboxio.

Checks:

  • go test -race on the protocol and service packages
  • FuzzDecode, 30 s
  • go vet on linux amd64, arm64 and 386; gofmt
  • darwin and windows builds

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


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 merged commit b7c9a49 into feature/agent-outside-sandbox Oct 1, 2026
12 checks passed
@SaladDay
SaladDay deleted the aos/file-protocol branch October 1, 2026 00:17
internal/sandboxfs defines the Runtime–file service protocol on
sandboxwire framing: node and handle operations shaped like FUSE,
typed failures with effects, capabilities with admission, golden
fixtures, a decoder fuzz target and a generic client and server.
Request IDs follow sandboxwire.RequestSequence. Describe reports the
service identity, and Attach is limited to the Link export grants.

apps/sandboxio/internal/fileservice implements it on Linux. It serves
the one export world from a root the caller isolates, keys nodes by
mount ID, device and inode, keeps symlinks and proc magic links opaque,
and provides handles that survive unlink, atomic append, renameat2
modes, getdents cookies, flock that interoperates with native
processes and incarnation checks.

Add docs/file-access-protocol.md and its 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