API Reference

API Reference

The compute service exposes a single gRPC service: compute.v1.ComputeService. All messages are defined in paper-board/proto/compute/v1/compute.proto. The service listens on port 50051 (ClusterIP — internal only, no public ingress).

Service definition

service ComputeService {
  rpc CreateSandbox   (CreateSandboxRequest)   returns (CreateSandboxResponse);
  rpc DestroySandbox  (DestroySandboxRequest)  returns (DestroySandboxResponse);
  rpc DescribeSandbox (DescribeSandboxRequest) returns (DescribeSandboxResponse);

  rpc ExecCommand     (ExecCommandRequest)     returns (stream ExecEvent);

  rpc ReadFile  (ReadFileRequest)  returns (ReadFileResponse);
  rpc WriteFile (WriteFileRequest) returns (WriteFileResponse);
  rpc ListFiles (ListFilesRequest) returns (ListFilesResponse);
}

A bidirectional ExecSession RPC for interactive REPL use cases is planned for Phase 5. It is not part of the v1 surface — message types, lifecycle, and cancellation semantics will be designed in the Phase 5 brainstorm.

---

Sandbox lifecycle RPCs

CreateSandbox

Provisions a gVisor pod and a workspace PVC for a session. Returns immediately with status: STARTING; the pod becomes READY asynchronously. ExecCommand blocks internally until the pod is running — callers do not need to poll DescribeSandbox before calling ExecCommand.

Lazy provisioning. The agents service calls CreateSandbox only on the first tool_use block in a session. Sessions that complete without any tool call never create a sandbox and incur no compute cost.

Request: CreateSandboxRequest

Field	Type	Required	Description
tenant_id	string	yes	Tenant UUID. Stored as pod annotation.
session_id	string	yes	Agent session UUID. One sandbox per session.
image	string	no	Container image. Defaults to SANDBOX_IMAGE env var.
workspace	WorkspaceSpec	no	PVC size, storage class, mount path. Server defaults apply if omitted.
limits	ResourceLimits	no	CPU/memory/timeout. Server defaults apply if omitted.

Response: CreateSandboxResponse

Field	Type	Description
sandbox_id	string	UUID assigned to this sandbox.
status	SandboxStatus	Always STARTING on success.
created_at	google.protobuf.Timestamp	Server-side creation timestamp.

Errors

gRPC code	Condition
INVALID_ARGUMENT	tenant_id or session_id is empty.
INTERNAL	K8s pod or PVC creation failed.

---

DescribeSandbox

Returns the current status and accumulated resource usage of a sandbox.

Request: DescribeSandboxRequest

Field	Type	Required	Description
sandbox_id	string	yes	UUID returned by CreateSandbox.

Response: DescribeSandboxResponse

Field	Type	Description
sandbox_id	string	Echo of the request sandbox_id.
status	SandboxStatus	Current lifecycle state.
created_at	google.protobuf.Timestamp	When the pod was created.
current_uptime	google.protobuf.Duration	Elapsed time since creation.
current_usage	UsageMetrics	Cumulative resource usage since creation.

Errors

gRPC code	Condition
INVALID_ARGUMENT	sandbox_id is not a valid UUID.
INTERNAL	K8s describe call failed.

---

DestroySandbox

Deletes the sandbox pod and marks the workspace PVC for soft-delete. The PVC is annotated with compute.paper-board.io/delete-after = now + 24h and physically deleted by the GC CronJob after the grace window expires.

Request: DestroySandboxRequest

Field	Type	Required	Description
sandbox_id	string	yes	UUID returned by CreateSandbox.

Response: DestroySandboxResponse

Field	Type	Description
sandbox_id	string	Echo of the request sandbox_id.
total_usage	UsageMetrics	Cumulative resource usage over the sandbox lifetime.

Errors

gRPC code	Condition
INVALID_ARGUMENT	sandbox_id is not a valid UUID.
INTERNAL	K8s delete call failed.

---

Exec RPC

ExecCommand

Server-streaming RPC. Runs a command inside the sandbox pod and streams stdout / stderr lines as they arrive. The final event is ExecCompleted, which carries the exit code, wall time, and UsageMetrics.

If the sandbox is still in STARTING state when ExecCommand is called, the server blocks on WaitForRunning before starting the exec. This means callers can call ExecCommand immediately after CreateSandbox without polling.

Cancellation. Cancelling the gRPC stream context sends SIGTERM to the in-pod process. If the process is still running after 10 seconds, SIGKILL is sent. A final ExecCompleted{ cancelled: true, exit_code: -1 } event is emitted before the stream closes.

Timeout. Maximum per-call timeout is 600 seconds (10 minutes). Requests with timeout unset or exceeding 600 s are capped at 600 s server-side.

Request: ExecCommandRequest

Field	Type	Required	Description
sandbox_id	string	yes	UUID returned by CreateSandbox.
command	string	yes	Executable path (e.g. python3, /usr/bin/env).
args	repeated string	no	Command arguments.
env	map<string, string>	no	Additional environment variables injected into the process.
working_dir	string	no	Working directory. Defaults to /workspace.
timeout	google.protobuf.Duration	no	Per-call timeout. Capped at 600 s.

Response stream: ExecEvent

Each event carries exactly one of:

Variant	Type	Description
stdout	StdoutLine	A chunk of stdout bytes (base64 in JSON transport).
stderr	StderrLine	A chunk of stderr bytes (base64 in JSON transport).
completed	ExecCompleted	Terminal event; always the last event in the stream.

ExecEvent also carries emitted_at: google.protobuf.Timestamp on every event.

ExecCompleted

Field	Type	Description
exit_code	int32	Process exit code; -1 if cancelled.
wall_time	google.protobuf.Duration	Elapsed wall time from exec start to process exit.
cancelled	bool	true if the exec was terminated by stream cancel.
usage	UsageMetrics	Resource consumption for this exec call.

Errors

gRPC code	Condition
INVALID_ARGUMENT	sandbox_id is not a valid UUID, or command is empty.
FAILED_PRECONDITION	Sandbox status is FAILED or DESTROYED.
DEADLINE_EXCEEDED	WaitForRunning timed out (sandbox still not ready).
INTERNAL	K8s exec transport failure.

---

Workspace I/O RPCs

All workspace I/O paths are validated against WorkspaceSpec.mount_path (default /workspace):

• Paths are cleaned (filepath.Clean) before use; .. segments after cleaning are rejected with INVALID_ARGUMENT.
• Symlinks inside the workspace are followed only if the resolved target is also inside mount_path; otherwise the operation is rejected with PERMISSION_DENIED.
• Per-call data cap: 16 MiB. Clients must chunk larger payloads across multiple calls.

ReadFile

Request: ReadFileRequest

Field	Type	Required	Description
sandbox_id	string	yes	UUID returned by CreateSandbox.
path	string	yes	Path relative to mount_path. Must not escape the workspace root.
offset	int64	no	Byte offset to start reading. 0 = start of file.
max_bytes	int64	no	Maximum bytes to return. 0 = read to EOF (capped at 16 MiB).

Response: ReadFileResponse

Field	Type	Description
data	bytes	File contents (base64 in JSON transport).
total_size	int64	Total file size in bytes (before offset/cap).
eof	bool	true if data extends to the end of the file.

---

WriteFile

Request: WriteFileRequest

Field	Type	Required	Description
sandbox_id	string	yes	UUID returned by CreateSandbox.
path	string	yes	Path relative to mount_path. Must not escape the workspace root.
data	bytes	yes	Content to write. Capped at 16 MiB per call.
append	bool	no	true = append; false = truncate then write (default).
mode	uint32	no	File mode bits when creating. Ignored if file already exists.

Response: WriteFileResponse

Field	Type	Description
bytes_written	int64	Number of bytes written.

---

ListFiles

Request: ListFilesRequest

Field	Type	Required	Description
sandbox_id	string	yes	UUID returned by CreateSandbox.
path	string	yes	Directory path relative to mount_path.
recursive	bool	no	true = traverse subdirectories.
max_entries	uint32	no	Result cap. 0 = default 1000. Hard cap: 10000.

Response: ListFilesResponse

Field	Type	Description
entries	repeated FileEntry	File and directory entries.
truncated	bool	true if the result was capped by max_entries.

FileEntry

Field	Type	Description
path	string	Relative to the ListFilesRequest.path.
size	uint64	File size in bytes. 0 for directories.
is_dir	bool	true for directories.
mode	uint32	Unix permission bits.
modified_at	google.protobuf.Timestamp	Last modification time.

Errors (workspace I/O)

gRPC code	Condition
INVALID_ARGUMENT	sandbox_id not a valid UUID, or path escapes mount_path after clean.
PERMISSION_DENIED	Symlink target resolves outside mount_path.
INTERNAL	K8s exec I/O transport failure.

---

Shared message types

SandboxSpec (embedded in CreateSandboxRequest)

WorkspaceSpec and ResourceLimits are the two sub-messages:

WorkspaceSpec

Field	Type	Description
storage_class	string	K8s StorageClass name. Defaults to PVC_STORAGE_CLASS env var.
size	string	PVC capacity string (e.g. "5Gi"). Defaults to PVC_WORKSPACE_SIZE.
mount_path	string	Container path where the PVC is mounted. Defaults to /workspace.

ResourceLimits

Field	Type	Description
cpu_millis	uint32	CPU limit in millicores. Default: 1000 m.
memory_bytes	uint64	Memory limit in bytes. Default: 1 GiB.
max_runtime	google.protobuf.Duration	Hard wall-time limit for the sandbox pod. Default: 15 minutes.

UsageMetrics (from common.v1)

Returned in ExecCompleted, DescribeSandboxResponse, and DestroySandboxResponse.

Field	Type	Description
cpu_ms	uint64	CPU time consumed (milliseconds).
memory_peak_bytes	uint64	Peak RSS during the measurement window.
memory_avg_bytes	uint64	Average RSS during the measurement window.
disk_read_bytes	uint64	Bytes read from the workspace PVC.
disk_write_bytes	uint64	Bytes written to the workspace PVC.
network_egress_bytes	uint64	Bytes sent to external destinations.
network_ingress_bytes	uint64	Bytes received from external destinations.

SandboxStatus enum

Value	Meaning
SANDBOX_STATUS_UNSPECIFIED	Unknown or not yet set.
SANDBOX_STATUS_STARTING	Pod is being scheduled; not yet accepting exec requests.
SANDBOX_STATUS_READY	Pod is running; ExecCommand calls proceed immediately.
SANDBOX_STATUS_FAILED	Pod exited non-zero or exceeded its deadline.
SANDBOX_STATUS_DESTROYED	Pod deleted; workspace PVC in soft-delete grace window.