Add minimal control plane with REST API, database, and reconciler

- REST API (chi router): sandbox CRUD, exec, pause/resume, file write/read - PostgreSQL persistence via pgx/v5 + sqlc (sandboxes table with goose migration) - Connect RPC client to host agent for all VM operations - Reconciler syncs host agent state with DB every 30s (detects TTL-reaped sandboxes) - OpenAPI 3.1 spec served at /openapi.yaml, Swagger UI at /docs - Added WriteFile/ReadFile RPCs to hostagent proto and implementations - File upload via multipart form, download via JSON body POST - sandbox_id propagated from control plane to host agent on create
2026-03-10 16:50:12 +06:00
parent d7b25b0891
commit ec3360d9ad
46 changed files with 2210 additions and 33 deletions
--- a/proto/envd/gen/filesystem.pb.go
+++ b/proto/envd/gen/filesystem.pb.go
@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+
 // Code generated by protoc-gen-go. DO NOT EDIT.
 // versions:
 // 	protoc-gen-go v1.36.11
--- a/proto/envd/gen/genconnect/filesystem.connect.go
+++ b/proto/envd/gen/genconnect/filesystem.connect.go
@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+
 // Code generated by protoc-gen-connect-go. DO NOT EDIT.
 //
 // Source: filesystem.proto
--- a/proto/envd/gen/genconnect/process.connect.go
+++ b/proto/envd/gen/genconnect/process.connect.go
@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+
 // Code generated by protoc-gen-connect-go. DO NOT EDIT.
 //
 // Source: process.proto
--- a/proto/envd/gen/process.pb.go
+++ b/proto/envd/gen/process.pb.go
@ -1,3 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+
 // Code generated by protoc-gen-go. DO NOT EDIT.
 // versions:
 // 	protoc-gen-go v1.36.11
--- a/proto/hostagent/gen/hostagent.pb.go
+++ b/proto/hostagent/gen/hostagent.pb.go
@ -23,6 +23,8 @@ const (

 type CreateSandboxRequest struct {
 	state protoimpl.MessageState `protogen:"open.v1"`
+	// Sandbox ID assigned by the control plane. If empty, the host agent generates one.
+	SandboxId string `protobuf:"bytes,5,opt,name=sandbox_id,json=sandboxId,proto3" json:"sandbox_id,omitempty"`
 	// Template name (e.g., "minimal", "python311"). Determines base rootfs.
 	Template string `protobuf:"bytes,1,opt,name=template,proto3" json:"template,omitempty"`
 	// Number of virtual CPUs (default: 1).
@ -66,6 +68,13 @@ func (*CreateSandboxRequest) Descriptor() ([]byte, []int) {
 	return file_hostagent_proto_rawDescGZIP(), []int{0}
 }

+func (x *CreateSandboxRequest) GetSandboxId() string {
+	if x != nil {
+		return x.SandboxId
+	}
+	return ""
+}
+
 func (x *CreateSandboxRequest) GetTemplate() string {
 	if x != nil {
 		return x.Template
@ -711,12 +720,206 @@ func (x *SandboxInfo) GetTimeoutSec() int32 {
 	return 0
 }

+type WriteFileRequest struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	SandboxId     string                 `protobuf:"bytes,1,opt,name=sandbox_id,json=sandboxId,proto3" json:"sandbox_id,omitempty"`
+	Path          string                 `protobuf:"bytes,2,opt,name=path,proto3" json:"path,omitempty"`
+	Content       []byte                 `protobuf:"bytes,3,opt,name=content,proto3" json:"content,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *WriteFileRequest) Reset() {
+	*x = WriteFileRequest{}
+	mi := &file_hostagent_proto_msgTypes[13]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *WriteFileRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*WriteFileRequest) ProtoMessage() {}
+
+func (x *WriteFileRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_hostagent_proto_msgTypes[13]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use WriteFileRequest.ProtoReflect.Descriptor instead.
+func (*WriteFileRequest) Descriptor() ([]byte, []int) {
+	return file_hostagent_proto_rawDescGZIP(), []int{13}
+}
+
+func (x *WriteFileRequest) GetSandboxId() string {
+	if x != nil {
+		return x.SandboxId
+	}
+	return ""
+}
+
+func (x *WriteFileRequest) GetPath() string {
+	if x != nil {
+		return x.Path
+	}
+	return ""
+}
+
+func (x *WriteFileRequest) GetContent() []byte {
+	if x != nil {
+		return x.Content
+	}
+	return nil
+}
+
+type WriteFileResponse struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *WriteFileResponse) Reset() {
+	*x = WriteFileResponse{}
+	mi := &file_hostagent_proto_msgTypes[14]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *WriteFileResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*WriteFileResponse) ProtoMessage() {}
+
+func (x *WriteFileResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_hostagent_proto_msgTypes[14]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use WriteFileResponse.ProtoReflect.Descriptor instead.
+func (*WriteFileResponse) Descriptor() ([]byte, []int) {
+	return file_hostagent_proto_rawDescGZIP(), []int{14}
+}
+
+type ReadFileRequest struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	SandboxId     string                 `protobuf:"bytes,1,opt,name=sandbox_id,json=sandboxId,proto3" json:"sandbox_id,omitempty"`
+	Path          string                 `protobuf:"bytes,2,opt,name=path,proto3" json:"path,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ReadFileRequest) Reset() {
+	*x = ReadFileRequest{}
+	mi := &file_hostagent_proto_msgTypes[15]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ReadFileRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ReadFileRequest) ProtoMessage() {}
+
+func (x *ReadFileRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_hostagent_proto_msgTypes[15]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ReadFileRequest.ProtoReflect.Descriptor instead.
+func (*ReadFileRequest) Descriptor() ([]byte, []int) {
+	return file_hostagent_proto_rawDescGZIP(), []int{15}
+}
+
+func (x *ReadFileRequest) GetSandboxId() string {
+	if x != nil {
+		return x.SandboxId
+	}
+	return ""
+}
+
+func (x *ReadFileRequest) GetPath() string {
+	if x != nil {
+		return x.Path
+	}
+	return ""
+}
+
+type ReadFileResponse struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Content       []byte                 `protobuf:"bytes,1,opt,name=content,proto3" json:"content,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ReadFileResponse) Reset() {
+	*x = ReadFileResponse{}
+	mi := &file_hostagent_proto_msgTypes[16]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ReadFileResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ReadFileResponse) ProtoMessage() {}
+
+func (x *ReadFileResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_hostagent_proto_msgTypes[16]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ReadFileResponse.ProtoReflect.Descriptor instead.
+func (*ReadFileResponse) Descriptor() ([]byte, []int) {
+	return file_hostagent_proto_rawDescGZIP(), []int{16}
+}
+
+func (x *ReadFileResponse) GetContent() []byte {
+	if x != nil {
+		return x.Content
+	}
+	return nil
+}
+
 var File_hostagent_proto protoreflect.FileDescriptor

 const file_hostagent_proto_rawDesc = "" +
 	"\n" +
-	"\x0fhostagent.proto\x12\fhostagent.v1\"\x86\x01\n" +
-	"\x14CreateSandboxRequest\x12\x1a\n" +
+	"\x0fhostagent.proto\x12\fhostagent.v1\"\xa5\x01\n" +
+	"\x14CreateSandboxRequest\x12\x1d\n" +
+	"\n" +
+	"sandbox_id\x18\x05 \x01(\tR\tsandboxId\x12\x1a\n" +
 	"\btemplate\x18\x01 \x01(\tR\btemplate\x12\x14\n" +
 	"\x05vcpus\x18\x02 \x01(\x05R\x05vcpus\x12\x1b\n" +
 	"\tmemory_mb\x18\x03 \x01(\x05R\bmemoryMb\x12\x1f\n" +
@ -764,14 +967,28 @@ const file_hostagent_proto_rawDesc = "" +
 	"\x0fcreated_at_unix\x18\a \x01(\x03R\rcreatedAtUnix\x12-\n" +
 	"\x13last_active_at_unix\x18\b \x01(\x03R\x10lastActiveAtUnix\x12\x1f\n" +
 	"\vtimeout_sec\x18\t \x01(\x05R\n" +
-	"timeoutSec2\x93\x04\n" +
+	"timeoutSec\"_\n" +
+	"\x10WriteFileRequest\x12\x1d\n" +
+	"\n" +
+	"sandbox_id\x18\x01 \x01(\tR\tsandboxId\x12\x12\n" +
+	"\x04path\x18\x02 \x01(\tR\x04path\x12\x18\n" +
+	"\acontent\x18\x03 \x01(\fR\acontent\"\x13\n" +
+	"\x11WriteFileResponse\"D\n" +
+	"\x0fReadFileRequest\x12\x1d\n" +
+	"\n" +
+	"sandbox_id\x18\x01 \x01(\tR\tsandboxId\x12\x12\n" +
+	"\x04path\x18\x02 \x01(\tR\x04path\",\n" +
+	"\x10ReadFileResponse\x12\x18\n" +
+	"\acontent\x18\x01 \x01(\fR\acontent2\xac\x05\n" +
 	"\x10HostAgentService\x12X\n" +
 	"\rCreateSandbox\x12\".hostagent.v1.CreateSandboxRequest\x1a#.hostagent.v1.CreateSandboxResponse\x12[\n" +
 	"\x0eDestroySandbox\x12#.hostagent.v1.DestroySandboxRequest\x1a$.hostagent.v1.DestroySandboxResponse\x12U\n" +
 	"\fPauseSandbox\x12!.hostagent.v1.PauseSandboxRequest\x1a\".hostagent.v1.PauseSandboxResponse\x12X\n" +
 	"\rResumeSandbox\x12\".hostagent.v1.ResumeSandboxRequest\x1a#.hostagent.v1.ResumeSandboxResponse\x12=\n" +
 	"\x04Exec\x12\x19.hostagent.v1.ExecRequest\x1a\x1a.hostagent.v1.ExecResponse\x12X\n" +
-	"\rListSandboxes\x12\".hostagent.v1.ListSandboxesRequest\x1a#.hostagent.v1.ListSandboxesResponseB\xb0\x01\n" +
+	"\rListSandboxes\x12\".hostagent.v1.ListSandboxesRequest\x1a#.hostagent.v1.ListSandboxesResponse\x12L\n" +
+	"\tWriteFile\x12\x1e.hostagent.v1.WriteFileRequest\x1a\x1f.hostagent.v1.WriteFileResponse\x12I\n" +
+	"\bReadFile\x12\x1d.hostagent.v1.ReadFileRequest\x1a\x1e.hostagent.v1.ReadFileResponseB\xb0\x01\n" +
 	"\x10com.hostagent.v1B\x0eHostagentProtoP\x01Z;git.omukk.dev/wrenn/sandbox/proto/hostagent/gen;hostagentv1\xa2\x02\x03HXX\xaa\x02\fHostagent.V1\xca\x02\fHostagent\\V1\xe2\x02\x18Hostagent\\V1\\GPBMetadata\xea\x02\rHostagent::V1b\x06proto3"

 var (
@ -786,7 +1003,7 @@ func file_hostagent_proto_rawDescGZIP() []byte {
 	return file_hostagent_proto_rawDescData
 }

-var file_hostagent_proto_msgTypes = make([]protoimpl.MessageInfo, 13)
+var file_hostagent_proto_msgTypes = make([]protoimpl.MessageInfo, 17)
 var file_hostagent_proto_goTypes = []any{
 	(*CreateSandboxRequest)(nil),   // 0: hostagent.v1.CreateSandboxRequest
 	(*CreateSandboxResponse)(nil),  // 1: hostagent.v1.CreateSandboxResponse
@ -801,6 +1018,10 @@ var file_hostagent_proto_goTypes = []any{
 	(*ListSandboxesRequest)(nil),   // 10: hostagent.v1.ListSandboxesRequest
 	(*ListSandboxesResponse)(nil),  // 11: hostagent.v1.ListSandboxesResponse
 	(*SandboxInfo)(nil),            // 12: hostagent.v1.SandboxInfo
+	(*WriteFileRequest)(nil),       // 13: hostagent.v1.WriteFileRequest
+	(*WriteFileResponse)(nil),      // 14: hostagent.v1.WriteFileResponse
+	(*ReadFileRequest)(nil),        // 15: hostagent.v1.ReadFileRequest
+	(*ReadFileResponse)(nil),       // 16: hostagent.v1.ReadFileResponse
 }
 var file_hostagent_proto_depIdxs = []int32{
 	12, // 0: hostagent.v1.ListSandboxesResponse.sandboxes:type_name -> hostagent.v1.SandboxInfo
@ -810,14 +1031,18 @@ var file_hostagent_proto_depIdxs = []int32{
 	6,  // 4: hostagent.v1.HostAgentService.ResumeSandbox:input_type -> hostagent.v1.ResumeSandboxRequest
 	8,  // 5: hostagent.v1.HostAgentService.Exec:input_type -> hostagent.v1.ExecRequest
 	10, // 6: hostagent.v1.HostAgentService.ListSandboxes:input_type -> hostagent.v1.ListSandboxesRequest
-	1,  // 7: hostagent.v1.HostAgentService.CreateSandbox:output_type -> hostagent.v1.CreateSandboxResponse
-	3,  // 8: hostagent.v1.HostAgentService.DestroySandbox:output_type -> hostagent.v1.DestroySandboxResponse
-	5,  // 9: hostagent.v1.HostAgentService.PauseSandbox:output_type -> hostagent.v1.PauseSandboxResponse
-	7,  // 10: hostagent.v1.HostAgentService.ResumeSandbox:output_type -> hostagent.v1.ResumeSandboxResponse
-	9,  // 11: hostagent.v1.HostAgentService.Exec:output_type -> hostagent.v1.ExecResponse
-	11, // 12: hostagent.v1.HostAgentService.ListSandboxes:output_type -> hostagent.v1.ListSandboxesResponse
-	7,  // [7:13] is the sub-list for method output_type
-	1,  // [1:7] is the sub-list for method input_type
+	13, // 7: hostagent.v1.HostAgentService.WriteFile:input_type -> hostagent.v1.WriteFileRequest
+	15, // 8: hostagent.v1.HostAgentService.ReadFile:input_type -> hostagent.v1.ReadFileRequest
+	1,  // 9: hostagent.v1.HostAgentService.CreateSandbox:output_type -> hostagent.v1.CreateSandboxResponse
+	3,  // 10: hostagent.v1.HostAgentService.DestroySandbox:output_type -> hostagent.v1.DestroySandboxResponse
+	5,  // 11: hostagent.v1.HostAgentService.PauseSandbox:output_type -> hostagent.v1.PauseSandboxResponse
+	7,  // 12: hostagent.v1.HostAgentService.ResumeSandbox:output_type -> hostagent.v1.ResumeSandboxResponse
+	9,  // 13: hostagent.v1.HostAgentService.Exec:output_type -> hostagent.v1.ExecResponse
+	11, // 14: hostagent.v1.HostAgentService.ListSandboxes:output_type -> hostagent.v1.ListSandboxesResponse
+	14, // 15: hostagent.v1.HostAgentService.WriteFile:output_type -> hostagent.v1.WriteFileResponse
+	16, // 16: hostagent.v1.HostAgentService.ReadFile:output_type -> hostagent.v1.ReadFileResponse
+	9,  // [9:17] is the sub-list for method output_type
+	1,  // [1:9] is the sub-list for method input_type
 	1,  // [1:1] is the sub-list for extension type_name
 	1,  // [1:1] is the sub-list for extension extendee
 	0,  // [0:1] is the sub-list for field type_name
@ -834,7 +1059,7 @@ func file_hostagent_proto_init() {
 			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
 			RawDescriptor: unsafe.Slice(unsafe.StringData(file_hostagent_proto_rawDesc), len(file_hostagent_proto_rawDesc)),
 			NumEnums:      0,
-			NumMessages:   13,
+			NumMessages:   17,
 			NumExtensions: 0,
 			NumServices:   1,
 		},
--- a/proto/hostagent/gen/hostagentv1connect/hostagent.connect.go
+++ b/proto/hostagent/gen/hostagentv1connect/hostagent.connect.go
@ -50,6 +50,12 @@ const (
 	// HostAgentServiceListSandboxesProcedure is the fully-qualified name of the HostAgentService's
 	// ListSandboxes RPC.
 	HostAgentServiceListSandboxesProcedure = "/hostagent.v1.HostAgentService/ListSandboxes"
+	// HostAgentServiceWriteFileProcedure is the fully-qualified name of the HostAgentService's
+	// WriteFile RPC.
+	HostAgentServiceWriteFileProcedure = "/hostagent.v1.HostAgentService/WriteFile"
+	// HostAgentServiceReadFileProcedure is the fully-qualified name of the HostAgentService's ReadFile
+	// RPC.
+	HostAgentServiceReadFileProcedure = "/hostagent.v1.HostAgentService/ReadFile"
 )

 // HostAgentServiceClient is a client for the hostagent.v1.HostAgentService service.
@ -66,6 +72,10 @@ type HostAgentServiceClient interface {
 	Exec(context.Context, *connect.Request[gen.ExecRequest]) (*connect.Response[gen.ExecResponse], error)
 	// ListSandboxes returns all sandboxes managed by this host agent.
 	ListSandboxes(context.Context, *connect.Request[gen.ListSandboxesRequest]) (*connect.Response[gen.ListSandboxesResponse], error)
+	// WriteFile writes content to a file inside a sandbox.
+	WriteFile(context.Context, *connect.Request[gen.WriteFileRequest]) (*connect.Response[gen.WriteFileResponse], error)
+	// ReadFile reads a file from inside a sandbox.
+	ReadFile(context.Context, *connect.Request[gen.ReadFileRequest]) (*connect.Response[gen.ReadFileResponse], error)
 }

 // NewHostAgentServiceClient constructs a client for the hostagent.v1.HostAgentService service. By
@ -115,6 +125,18 @@ func NewHostAgentServiceClient(httpClient connect.HTTPClient, baseURL string, op
 			connect.WithSchema(hostAgentServiceMethods.ByName("ListSandboxes")),
 			connect.WithClientOptions(opts...),
 		),
+		writeFile: connect.NewClient[gen.WriteFileRequest, gen.WriteFileResponse](
+			httpClient,
+			baseURL+HostAgentServiceWriteFileProcedure,
+			connect.WithSchema(hostAgentServiceMethods.ByName("WriteFile")),
+			connect.WithClientOptions(opts...),
+		),
+		readFile: connect.NewClient[gen.ReadFileRequest, gen.ReadFileResponse](
+			httpClient,
+			baseURL+HostAgentServiceReadFileProcedure,
+			connect.WithSchema(hostAgentServiceMethods.ByName("ReadFile")),
+			connect.WithClientOptions(opts...),
+		),
 	}
 }

@ -126,6 +148,8 @@ type hostAgentServiceClient struct {
 	resumeSandbox  *connect.Client[gen.ResumeSandboxRequest, gen.ResumeSandboxResponse]
 	exec           *connect.Client[gen.ExecRequest, gen.ExecResponse]
 	listSandboxes  *connect.Client[gen.ListSandboxesRequest, gen.ListSandboxesResponse]
+	writeFile      *connect.Client[gen.WriteFileRequest, gen.WriteFileResponse]
+	readFile       *connect.Client[gen.ReadFileRequest, gen.ReadFileResponse]
 }

 // CreateSandbox calls hostagent.v1.HostAgentService.CreateSandbox.
@ -158,6 +182,16 @@ func (c *hostAgentServiceClient) ListSandboxes(ctx context.Context, req *connect
 	return c.listSandboxes.CallUnary(ctx, req)
 }

+// WriteFile calls hostagent.v1.HostAgentService.WriteFile.
+func (c *hostAgentServiceClient) WriteFile(ctx context.Context, req *connect.Request[gen.WriteFileRequest]) (*connect.Response[gen.WriteFileResponse], error) {
+	return c.writeFile.CallUnary(ctx, req)
+}
+
+// ReadFile calls hostagent.v1.HostAgentService.ReadFile.
+func (c *hostAgentServiceClient) ReadFile(ctx context.Context, req *connect.Request[gen.ReadFileRequest]) (*connect.Response[gen.ReadFileResponse], error) {
+	return c.readFile.CallUnary(ctx, req)
+}
+
 // HostAgentServiceHandler is an implementation of the hostagent.v1.HostAgentService service.
 type HostAgentServiceHandler interface {
 	// CreateSandbox boots a new microVM with the given configuration.
@ -172,6 +206,10 @@ type HostAgentServiceHandler interface {
 	Exec(context.Context, *connect.Request[gen.ExecRequest]) (*connect.Response[gen.ExecResponse], error)
 	// ListSandboxes returns all sandboxes managed by this host agent.
 	ListSandboxes(context.Context, *connect.Request[gen.ListSandboxesRequest]) (*connect.Response[gen.ListSandboxesResponse], error)
+	// WriteFile writes content to a file inside a sandbox.
+	WriteFile(context.Context, *connect.Request[gen.WriteFileRequest]) (*connect.Response[gen.WriteFileResponse], error)
+	// ReadFile reads a file from inside a sandbox.
+	ReadFile(context.Context, *connect.Request[gen.ReadFileRequest]) (*connect.Response[gen.ReadFileResponse], error)
 }

 // NewHostAgentServiceHandler builds an HTTP handler from the service implementation. It returns the
@ -217,6 +255,18 @@ func NewHostAgentServiceHandler(svc HostAgentServiceHandler, opts ...connect.Han
 		connect.WithSchema(hostAgentServiceMethods.ByName("ListSandboxes")),
 		connect.WithHandlerOptions(opts...),
 	)
+	hostAgentServiceWriteFileHandler := connect.NewUnaryHandler(
+		HostAgentServiceWriteFileProcedure,
+		svc.WriteFile,
+		connect.WithSchema(hostAgentServiceMethods.ByName("WriteFile")),
+		connect.WithHandlerOptions(opts...),
+	)
+	hostAgentServiceReadFileHandler := connect.NewUnaryHandler(
+		HostAgentServiceReadFileProcedure,
+		svc.ReadFile,
+		connect.WithSchema(hostAgentServiceMethods.ByName("ReadFile")),
+		connect.WithHandlerOptions(opts...),
+	)
 	return "/hostagent.v1.HostAgentService/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		switch r.URL.Path {
 		case HostAgentServiceCreateSandboxProcedure:
@ -231,6 +281,10 @@ func NewHostAgentServiceHandler(svc HostAgentServiceHandler, opts ...connect.Han
 			hostAgentServiceExecHandler.ServeHTTP(w, r)
 		case HostAgentServiceListSandboxesProcedure:
 			hostAgentServiceListSandboxesHandler.ServeHTTP(w, r)
+		case HostAgentServiceWriteFileProcedure:
+			hostAgentServiceWriteFileHandler.ServeHTTP(w, r)
+		case HostAgentServiceReadFileProcedure:
+			hostAgentServiceReadFileHandler.ServeHTTP(w, r)
 		default:
 			http.NotFound(w, r)
 		}
@ -263,3 +317,11 @@ func (UnimplementedHostAgentServiceHandler) Exec(context.Context, *connect.Reque
 func (UnimplementedHostAgentServiceHandler) ListSandboxes(context.Context, *connect.Request[gen.ListSandboxesRequest]) (*connect.Response[gen.ListSandboxesResponse], error) {
 	return nil, connect.NewError(connect.CodeUnimplemented, errors.New("hostagent.v1.HostAgentService.ListSandboxes is not implemented"))
 }
+
+func (UnimplementedHostAgentServiceHandler) WriteFile(context.Context, *connect.Request[gen.WriteFileRequest]) (*connect.Response[gen.WriteFileResponse], error) {
+	return nil, connect.NewError(connect.CodeUnimplemented, errors.New("hostagent.v1.HostAgentService.WriteFile is not implemented"))
+}
+
+func (UnimplementedHostAgentServiceHandler) ReadFile(context.Context, *connect.Request[gen.ReadFileRequest]) (*connect.Response[gen.ReadFileResponse], error) {
+	return nil, connect.NewError(connect.CodeUnimplemented, errors.New("hostagent.v1.HostAgentService.ReadFile is not implemented"))
+}
--- a/proto/hostagent/hostagent.proto
+++ b/proto/hostagent/hostagent.proto
@ -22,9 +22,18 @@ service HostAgentService {

  // ListSandboxes returns all sandboxes managed by this host agent.
  rpc ListSandboxes(ListSandboxesRequest) returns (ListSandboxesResponse);
+
+  // WriteFile writes content to a file inside a sandbox.
+  rpc WriteFile(WriteFileRequest) returns (WriteFileResponse);
+
+  // ReadFile reads a file from inside a sandbox.
+  rpc ReadFile(ReadFileRequest) returns (ReadFileResponse);
 }

 message CreateSandboxRequest {
+  // Sandbox ID assigned by the control plane. If empty, the host agent generates one.
+  string sandbox_id = 5;
+
  // Template name (e.g., "minimal", "python311"). Determines base rootfs.
  string template = 1;

@ -94,3 +103,20 @@ message SandboxInfo {
  int64 last_active_at_unix = 8;
  int32 timeout_sec = 9;
 }
+
+message WriteFileRequest {
+  string sandbox_id = 1;
+  string path = 2;
+  bytes content = 3;
+}
+
+message WriteFileResponse {}
+
+message ReadFileRequest {
+  string sandbox_id = 1;
+  string path = 2;
+}
+
+message ReadFileResponse {
+  bytes content = 1;
+}