gRPC API reference

AWC exposes two gRPC surfaces. Neither is the public HTTPS JSON API; for that, see REST API (v1).

Surface	Package	Served by	Transport	Caller
HostService	awc.host.v1	awcd	Unix-domain socket	awcctl, sandbox adapters
LeaseService	awc.control.v1	awc-control	TCP, mTLS in production	awcd
CheckpointService	awc.control.v1	awc-control	TCP, mTLS in production	awcd

The proto definitions are the authority for message shapes.

Transports and authentication

Host API (Unix socket)

Property	Value
Wire format	gRPC over HTTP/2
Listen address	Unix-domain socket
Override	Second positional argument to awcd, or the AWCD_SOCKET env var
TLS	None (file-system permissions gate the socket)

Control-plane API (mTLS TCP)

Property	Value
Wire format	gRPC over HTTP/2
Override	AWC_CONTROL_GRPC_LISTEN
Production TLS	Mutual TLS (server + client cert)
Dev plaintext	Set AWC_DEV_MODE=1

mTLS environment variables, server side:

Variable	Required unless dev	Purpose
AWC_CONTROL_TLS_CERT	Yes	Server certificate (PEM)
AWC_CONTROL_TLS_KEY	Yes	Server private key (PEM)
AWC_CONTROL_TLS_CLIENT_CA	Yes	CA that signs client certificates

mTLS environment variables, client side:

Variable	Required for https://	Purpose
AWC_CONTROL_TLS_CA	Yes	CA that signs the control-plane server cert
AWC_CONTROL_TLS_CERT	Yes	Client certificate (PEM)
AWC_CONTROL_TLS_KEY	Yes	Client private key (PEM)
control_plane_endpoint	Config	Control-plane URI, for example https://control.example

Every control-plane handler binds the client certificate fingerprint to the registered host that owns the mount session. A request with no client certificate returns UNAUTHENTICATED, except in dev mode.

HostService

Served by awcd on the Unix socket. Package awc.host.v1.

RPC	Request	Response
MountWorkspace	MountWorkspaceRequest	MountWorkspaceResponse
UnmountWorkspace	UnmountWorkspaceRequest	UnmountWorkspaceResponse
CheckpointWorkspace	CheckpointWorkspaceRequest	stream CheckpointEvent
GetHostStatus	HostStatusRequest	HostStatusResponse

MountWorkspace

Mounts a workspace snapshot onto an authorized target. The host verifies the signed ticket without a synchronous control-plane call.

MountWorkspaceRequest

Field	Type	Required	Notes
signed_ticket	string	Yes	Short-lived signed mount ticket
target_path	string	Yes	Must fall under an allow-listed root
namespace_target	string	No	Namespace bind target; empty means none
mount_options	map<string, string>	No	Read root_digest and labels here

MountWorkspaceResponse

Field	Type	Notes
mount_session_id	string	New session id
internal_merged_path	string	Per-session merged overlay view
bound_target_path	string	Host path bound for the caller
lease_generation	uint64	Writer-lease fencing generation; 0 for read-only
root_digest	string	Snapshot root digest the mount is pinned to
cache_warmth_summary	string	Cache warmth summary

UnmountWorkspace

Unmounts a previously mounted session.

UnmountWorkspaceRequest

Field	Type	Required	Notes
mount_session_id	string	Yes	Session to unmount
disposition	MountDisposition	No	On-unmount disposition
idempotency_key	string	No	Deduplicates the unmount

UnmountWorkspaceResponse

Field	Type	Notes
mount_session_id	string	Session that was unmounted
checkpoint_result	CheckpointResult	Present only when disposition is CHECKPOINT

CheckpointWorkspace

Server-streaming. Streams CheckpointProgress events, then one final CheckpointResult.

CheckpointWorkspaceRequest

Field	Type	Required	Notes
mount_session_id	string	Yes	Session to checkpoint
message	string	No	Checkpoint message
mode	CheckpointMode	No	QUIESCED or COOPERATIVE
idempotency_key	string	No	Deduplicates the checkpoint
labels	map<string, string>	No	Provenance labels

CheckpointEvent is a oneof of progress or result.

Field	Type	Notes
progress	CheckpointProgress	Progress update
result	CheckpointResult	Final result; terminates the stream

CheckpointProgress

Field	Type	Notes
stage	string	Current stage name
completed_bytes	uint64	Bytes processed so far
total_bytes	uint64	Total bytes expected

CheckpointResult

Field	Type	Notes
snapshot_id	string	New snapshot id
snapshot_digest	string	Snapshot digest
workspace_version	uint64	Workspace version after publish
logical_bytes	uint64	Logical bytes in the change set
uploaded_unique_bytes	uint64	New bytes uploaded to the CAS
reused_object_bytes	uint64	Bytes reused from the CAS
changed_path_count	uint64	Number of changed paths
quiesce_duration_ms	uint64	Quiesce duration in milliseconds

GetHostStatus

Typed host lifecycle and mount state.

HostStatusRequest is empty.

HostStatusResponse

Field	Type	Notes
state	HostState	Daemon lifecycle state
base_mount_state	BaseMountState	Shared read-only base filesystem state
base_mount_path	string	Path of the base filesystem mount
active_mount_count	uint32	Number of active mount sessions
host_id	string	Registered host id
version	string	Daemon version
started_at_rfc3339	string	Daemon start time, RFC 3339 UTC
detail	string	Free-form detail, for example a degradation reason

Host enums

MountDisposition

Value	Meaning
MOUNT_DISPOSITION_UNSPECIFIED	Not set
DISCARD_LOCAL	Discard the upper layer
CHECKPOINT	Checkpoint before unmount
PRESERVE_LOCAL	Preserve the upper layer locally

CheckpointMode

Value	Meaning
CHECKPOINT_MODE_UNSPECIFIED	Not set
QUIESCED	Freeze writes, then cut
COOPERATIVE	Best-effort, no freeze

HostState

Value	Meaning
HOST_STATE_UNSPECIFIED	Not set
STARTING	Starting up
HEALTHY	Operating normally
DEGRADED	Operating with reduced function
STOPPING	Shutting down
STOPPED	Stopped

BaseMountState

Value	Meaning
BASE_MOUNT_STATE_UNSPECIFIED	Not set
NOT_MOUNTED	Base filesystem not mounted
MOUNTING	Base filesystem mounting
MOUNTED	Base filesystem mounted
UNMOUNTING	Base filesystem unmounting
FAILED	Base filesystem failed to mount or unmount

LeaseService

Served by awc-control over mTLS. Package awc.control.v1.

RPC	Request	Response
ActivateWorkspaceLease	ActivateWorkspaceLeaseRequest	ActivateWorkspaceLeaseResponse
RenewWorkspaceLease	RenewWorkspaceLeaseRequest	RenewWorkspaceLeaseResponse
ReleaseWorkspaceLease	ReleaseWorkspaceLeaseRequest	ReleaseWorkspaceLeaseResponse

ActivateWorkspaceLease

Confirms that the host completed the kernel mount and makes the writer lease publish-capable. An empty lease_id activates a read-only session.

ActivateWorkspaceLeaseRequest

Field	Type	Required	Notes
workspace_id	string	Yes	ws_<ulid>
lease_id	string	No	Empty means read-only activation
generation	uint64	Yes	Fencing generation
mount_session_id	string	Yes	Session being activated

ActivateWorkspaceLeaseResponse

Field	Type	Notes
lease_state	string	ACTIVE for a writer; NONE for read-only
mount_session_state	string	MOUNTED

RenewWorkspaceLease

Renews or learns the fate of a writer lease. The control plane sets the new expiry from its own TTL, so a holder with a skewed clock still gets a coherent extension.

RenewWorkspaceLeaseRequest

Field	Type	Required	Notes
workspace_id	string	Yes	ws_<ulid>
lease_id	string	Yes	lease_<ulid>
generation	uint64	Yes	Fencing generation
mount_session_id	string	No	Optional session id

RenewWorkspaceLeaseResponse

Field	Type	Notes
action	RenewAction	Verdict for this lease
expires_at_rfc3339	string	New expiry, RFC 3339 UTC, when action is EXTEND
generation	uint64	Generation known to the control plane
detail	string	Free-form reason

RenewAction

Value	Host action
RENEW_ACTION_UNSPECIFIED	Not set
EXTEND	Lease extended; the mount may continue writing
REMOUNT_READ_ONLY	Writer lease gone; remount read-only to keep serving
REVOKE	Mount revoked; unmount immediately
WORKSPACE_GONE	Workspace deleted or administratively locked

ReleaseWorkspaceLease

Closes the authoritative mount session and releases its writer lease. An empty lease_id closes a read-only session.

ReleaseWorkspaceLeaseRequest

Field	Type	Required	Notes
workspace_id	string	Yes	ws_<ulid>
lease_id	string	No	Empty means read-only release
generation	uint64	Yes	Fencing generation
mount_session_id	string	Yes	Session being closed

ReleaseWorkspaceLeaseResponse

Field	Type	Notes
lease_state	string	RELEASED for a writer; NONE for read-only
mount_session_state	string	CLOSED

CheckpointService

Served by awc-control over mTLS. Package awc.control.v1.

RPC	Request	Response
PublishCheckpoint	PublishCheckpointRequest	PublishCheckpointResponse

PublishCheckpoint

Atomically publishes a finished checkpoint as the new workspace head. The control plane completes every mutable update in one transaction. It validates expected_workspace_version, expected_prior_head_snapshot_id, and the lease fence inside that transaction.

PublishCheckpointRequest

Field	Type	Required	Notes
workspace_id	string	Yes	ws_<ulid>
expected_workspace_version	uint64	Yes	Optimistic-concurrency guard
expected_prior_head_snapshot_id	string	Yes	Head the publisher believes it replaces
lease_id	string	Yes	Lease under which the publish runs
lease_generation	uint64	Yes	Lease fencing generation
mount_session_id	string	No	Session that produced the checkpoint
snapshot_manifest_digest	string	Yes	Content-addressed manifest digest
idempotency_key	string	No	Deduplicates the publish
provenance	CheckpointProvenance	No	Where the checkpoint came from
statistics	CheckpointStatistics	No	Byte and change accounting
root_tree_digest	string	No	New snapshot root tree digest; falls back to snapshot_manifest_digest if empty

PublishCheckpointResponse

Field	Type	Notes
workspace_version	uint64	Workspace version after publication
head_snapshot_id	string	Snapshot id now recorded as head
snapshot_manifest_digest	string	Manifest digest recorded
published_at_rfc3339	string	Publication time, RFC 3339 UTC

CheckpointProvenance

Field	Type	Notes
parent_snapshot_id	string	Parent snapshot; falls back to expected_prior_head_snapshot_id
message	string	Checkpoint message
mode	string	QUIESCED or COOPERATIVE
created_by	string	Principal; defaults to checkpoint if empty
labels	map<string, string>	Provenance labels

CheckpointStatistics

Field	Type	Notes
logical_bytes	uint64	Logical bytes in the change set
uploaded_unique_bytes	uint64	New bytes uploaded
reused_object_bytes	uint64	Bytes reused from the CAS
changed_path_count	uint64	Changed path count
quiesce_duration_ms	uint64	Quiesce duration in milliseconds

gRPC status codes

Both surfaces return standard gRPC status codes. The control plane uses UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND, ABORTED, FAILED_PRECONDITION, and INTERNAL. The host API uses INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, UNIMPLEMENTED, RESOURCE_EXHAUSTED, and FAILED_PRECONDITION.

Current scope

The following behaviors are partial or absent in the current build:

• MountWorkspace ignores namespace_target and returns UNIMPLEMENTED if the field is set.
• MountWorkspace returns a fixed cache_warmth_summary of "cold"; it does not compute a real warmth summary.
• UnmountWorkspace always returns checkpoint_result as None. The CHECKPOINT disposition is not honored as a combined unmount-plus-checkpoint operation.
• CheckpointWorkspace returns UNIMPLEMENTED when no checkpoint runner is configured at daemon startup.
• PublishCheckpoint records file_count as 0; CheckpointStatistics carries no file count, and the host client sets uploaded_unique_bytes, reused_object_bytes, and quiesce_duration_ms to 0.
• The control-plane gRPC listener serves plaintext TCP when AWC_DEV_MODE=1 is set, with no client certificate check. Use dev mode only on a loopback or isolated network.