diff --git a/packages/orchestrator/cmd/copy-build/main.go b/packages/orchestrator/cmd/copy-build/main.go
index c2bca116df..b4b0f293db 100644
--- a/packages/orchestrator/cmd/copy-build/main.go
+++ b/packages/orchestrator/cmd/copy-build/main.go
@@ -1,3 +1,7 @@
+// copy-build requires Linux. The template metadata package imports
+// sandbox/block which uses Linux-only syscalls (userfaultfd, memfd).
+// Darwin support is blocked on separating the cross-platform data types
+// from the Linux-only implementation; tracked in issue #3316.
 package main
 
 import (
diff --git a/packages/orchestrator/pkg/template/metadata/prefetch.go b/packages/orchestrator/pkg/template/metadata/prefetch.go
index 5d61e9bafe..dcd3746125 100644
--- a/packages/orchestrator/pkg/template/metadata/prefetch.go
+++ b/packages/orchestrator/pkg/template/metadata/prefetch.go
@@ -1,3 +1,6 @@
+//go:build linux
+
+// See template_metadata.go for why this file is restricted to Linux.
 package metadata
 
 import (
diff --git a/packages/orchestrator/pkg/template/metadata/template_metadata.go b/packages/orchestrator/pkg/template/metadata/template_metadata.go
index 4160e52201..b6747ed5bf 100644
--- a/packages/orchestrator/pkg/template/metadata/template_metadata.go
+++ b/packages/orchestrator/pkg/template/metadata/template_metadata.go
@@ -1,3 +1,9 @@
+//go:build linux
+
+// The build tag above restricts this file to Linux because it imports
+// sandbox/block, which depends on Linux-only syscalls. Once the cross-platform
+// data types are separated from the Linux-only block implementation (issue #3316),
+// this tag can be removed.
 package metadata
 
 import (