Namespace Openshell.V1

Classes

AddWorkspaceMemberRequest: Add workspace member request.

AddWorkspaceMemberResponse: Add workspace member response.

ApproveAllDraftChunksRequest

ApproveAllDraftChunksResponse

ApproveDraftChunkRequest: Approve a single draft chunk.

ApproveDraftChunkResponse

AttachSandboxProviderRequest: Attach provider to sandbox request.

AttachSandboxProviderResponse: Attach provider to sandbox response.

BeginRootfsTarStagingRequest: Request a gateway-owned staging slot for a local rootfs tar archive.

BeginRootfsTarStagingResponse: Gateway-issued staging slot.

ClearDraftChunksRequest: Clear all pending draft chunks for a sandbox.

ClearDraftChunksResponse

ComputeDriverCapabilities: Public compute driver capability snapshot.

ComputeDriverInfo: Info for one initialized compute driver runtime.

ConfigApplyFailure: Sanitized application failure. Messages must not contain configuration payloads, credentials, or provider values.

ConfigSnapshotRevision: Identifies one component snapshot revision. Revisions are equality tokens, not members of one shared ordering domain.

ConfigUpdate: Complete gateway-owned configuration for a supervisor session. Each update replaces the previous one. The supervisor applies the two parts together and answers every update with one ConfigUpdateResult before the gateway sends the next.

ConfigUpdateOperation: Durable progress for one sandbox-scoped desired-state mutation. Snapshot contents and credentials are never stored in this resource.

ConfigUpdateResult: Application result for one ConfigUpdate, including the bootstrap.

ConfigureProviderRefreshRequest

ConfigureProviderRefreshResponse

CpuResourceCapabilities

CreateProviderRequest: Create provider request.

CreateSandboxRequest: Create sandbox request.

CreateSandboxTemplateRequest

CreateSshSessionRequest: Create SSH session request.

CreateSshSessionResponse

Create SSH session response.

Fields are interpolated into an SSH ProxyCommand string that OpenSSH executes through /bin/sh -c on the caller's workstation. Servers MUST uphold the charset contract below; clients MUST reject responses that violate it. The client's own escaping provides defense-in-depth, but narrow charsets close injection vectors at the trust boundary.

CreateWorkspaceRequest: Create workspace request.

CreateWorkspaceResponse: Create workspace response.

DeleteProviderProfileRequest: Delete custom provider profile request.

DeleteProviderProfileResponse: Delete custom provider profile response.

DeleteProviderRefreshRequest

DeleteProviderRefreshResponse

DeleteProviderRequest: Delete provider request.

DeleteProviderResponse: Delete provider response.

DeleteSandboxRequest: Delete sandbox request.

DeleteSandboxResponse: Delete sandbox response.

DeleteSandboxTemplateRequest

DeleteSandboxTemplateResponse

DeleteServiceRequest: Request to delete an exposed sandbox service endpoint.

DeleteServiceResponse: Response for deleting an exposed sandbox service endpoint.

DeleteWorkspaceRequest: Delete workspace request.

DeleteWorkspaceResponse: Delete workspace response.

DenialGroupCount: Count of denied actions grouped only by sanitized telemetry category.

DenialSummary: Structured denial summary from sandbox aggregator.

DetachSandboxProviderRequest: Detach provider from sandbox request.

DetachSandboxProviderResponse: Detach provider from sandbox response.

DraftChunkApproval: Approve all pending chunks.

DraftHistoryEntry

DraftPolicyUpdate: Notification that the draft policy was updated.

EditDraftChunkRequest: Edit a pending chunk in-place.

EditDraftChunkResponse

EndpointFailure: Bounded cause of a failed endpoint observation, including failures before any request reaches the endpoint. No field carries remote text: code and stage come from the domain's closed sets, provider and credential_key are configured names, and request_id is an opaque random ID.

EndpointObservation: One redacted endpoint result in a supervisor's complete status report.

EndpointStatus: A configured endpoint and its last accepted network result in one record. Address fields contain policy selectors, never request URLs or credentials.

ExchangeProviderSubjectTokenRequest

ExchangeProviderSubjectTokenResponse

ExecSandboxEvent: One event in a sandbox exec stream.

ExecSandboxExit: Final exit status for a sandbox exec.

ExecSandboxInput: Client-to-server message for interactive exec.

ExecSandboxRequest: Execute command request.

ExecSandboxStderr: One stderr chunk from a sandbox exec.

ExecSandboxStdout: One stdout chunk from a sandbox exec.

ExecSandboxWindowResize: Terminal window resize event for interactive exec.

ExposeServiceRequest: Request to expose an HTTP service running inside a sandbox.

ExtensionServiceCredential: Short-lived credential for one policy-authorized extension service. Kept at the end of the file so adding it does not renumber existing generated message descriptors.

FinalizeMainProcessExitRequest: Terminal-delivery completion reported after all expected foreground SSH attachments close. A successful response permits ephemeral cleanup.

FinalizeMainProcessExitResponse

GatewayHeartbeat: Gateway heartbeat.

GatewayMessage: Envelope for gateway-to-supervisor messages on the ConnectSupervisor stream.

GetCurrentUserRequest: Current-user request. The identity comes from the authenticated request.

GetCurrentUserResponse: Authenticated user identity as validated by the gateway.

GetDraftHistoryRequest: Get decision history for a sandbox's draft policy.

GetDraftHistoryResponse

GetDraftPolicyRequest: Get draft policy for a sandbox.

GetDraftPolicyResponse

GetGatewayInfoRequest: Gateway info request.

GetGatewayInfoResponse: Gateway info response.

GetProviderCredentialsRequest: Retrieve selected runtime credentials from one provider in one workspace. Refresh side effects can persist even when the complete request fails.

GetProviderCredentialsResponse

GetProviderProfileRequest: Fetch provider type profile request.

GetProviderRefreshStatusRequest

GetProviderRefreshStatusResponse

GetProviderRequest: Get provider request.

GetSandboxLogsRequest: Get sandbox logs request (one-shot fetch).

GetSandboxLogsResponse: Get sandbox logs response.

GetSandboxPolicyStatusRequest: Get sandbox policy status request.

GetSandboxPolicyStatusResponse: Get sandbox policy status response.

GetSandboxProviderEnvironmentRequest: Get sandbox provider environment request.

GetSandboxProviderEnvironmentResponse: Polling projection of ProviderEnvironmentSnapshot. The parallel maps below are keyed by the same environment variable names. Removed with the polling RPCs; new provider environment fields belong on the snapshot first.

GetSandboxProviderStatusRequest: Query an immutable receipt, or reconstruct the current desired state when receipt_id is empty. The sandbox identity must match the receipt.

GetSandboxProviderStatusResponse

GetSandboxRequest: Get sandbox request.

GetSandboxTemplateRequest

GetServiceRequest: Request to fetch an exposed sandbox service endpoint.

GetWorkspaceRequest: Get workspace request.

GetWorkspaceResponse: Get workspace response.

GpuResourceCapabilities

GpuResourceRequirements: Public GPU resource requirements.

HealthRequest: Health check request.

HealthResponse: Health check response.

ImportProviderProfilesRequest: Import custom provider profiles request.

ImportProviderProfilesResponse: Import custom provider profiles response.

IssueSandboxTokenRequest: IssueSandboxToken request. Empty body; identity is established by the authentication credentials carried in the request headers (a projected Kubernetes ServiceAccount JWT in the K8s driver path).

IssueSandboxTokenResponse: IssueSandboxToken response. The supervisor caches the returned token in memory and presents it as Authorization: Bearer on every subsequent gateway RPC.

L7RequestSample: Observed HTTP method+path pattern from L7 inspection.

L7RuleTarget: Exact endpoint and complete authorization scope affected by an L7 append. All ports and binaries must match the stored target; omitted scope is invalid.

LintProviderProfilesRequest: Lint provider profiles request.

LintProviderProfilesResponse: Lint provider profiles response.

ListProviderProfilesRequest: List provider type profiles request.

ListProviderProfilesResponse: List provider profiles response.

ListProvidersRequest: List providers request.

ListProvidersResponse: List providers response.

ListSandboxPoliciesRequest: List sandbox policies request.

ListSandboxPoliciesResponse: List sandbox policies response.

ListSandboxProvidersRequest: List providers attached to a sandbox request.

ListSandboxProvidersResponse: List providers attached to a sandbox response.

ListSandboxTemplatesRequest

ListSandboxTemplatesResponse

ListSandboxesRequest: List sandboxes request.

ListSandboxesResponse: List sandboxes response.

ListServicesRequest: Request to list exposed sandbox service endpoints.

ListServicesResponse: Response containing exposed sandbox service endpoints.

ListWorkspaceMembersRequest: List workspace members request.

ListWorkspaceMembersResponse: List workspace members response.

ListWorkspacesRequest: List workspaces request.

ListWorkspacesResponse: List workspaces response.

MemoryResourceCapabilities

NegotiatedExtensionInfo: Public, non-secret snapshot of one successful startup negotiation.

NetworkActivitySummary: Anonymous sandbox network activity counters. This intentionally excludes hosts, paths, binaries, raw deny reasons, sandbox IDs, and user content.

OpenShell

OpenShell service provides sandbox, provider, and runtime management capabilities.

Conventions:

This file owns the public API resource model exposed to OpenShell clients.
Sandbox, SandboxSpec, SandboxStatus, and SandboxPhase are gateway-owned public types. Internal compute drivers must not import or return them directly.
The gateway translates internal compute-driver observations into these public resource messages before persisting or returning them to clients.

OpenShell.OpenShellClient: Client for OpenShell

OpenshellReflection: Holder for reflection information generated from openshell.proto

PeerConfigProviderTarget: Sandboxes in a workspace that attach the named provider.

PeerConfigSandboxTarget

PeerNotifyConfigUpdateRequest

PeerNotifyConfigUpdateResponse

PeerRelayFrame: A single frame on the gateway-to-gateway peer relay RPC.

PeerRelayInit: Initial frame for gateway peer relay forwarding.

PlatformEvent: Public platform event exposed on the sandbox watch stream.

PolicyChunk: A proposed policy rule with rationale and approval status.

PolicyLoadResult: Load result of one sandbox policy revision.

PolicyMergeOperation

ProviderCredentialRefresh

ProviderCredentialRefreshMaterial

ProviderCredentialRefreshOutput: Declares that a single refresh operation mints more than one credential. The refresh is attached to a primary credential; each additional output maps a strategy-defined semantic output id to a sibling credential whose env_vars receive the minted value.

ProviderCredentialRefreshStatus

ProviderCredentialTokenGrant

ProviderCredentialTokenGrantAudienceOverride: Endpoint selector for token grant audience overrides.

ProviderCredentialTokenGrantSubjectToken

ProviderCredentialValue: Usable runtime value, never gateway-only minting material.

ProviderDesiredIdentity: Exact desired authority. Revisions are opaque identities, never ordered.

ProviderEnvironmentSnapshot: Complete provider environment state delivered to a supervisor. This is the canonical provider environment shape; GetSandboxProviderEnvironmentResponse is its polling projection and is removed with the polling RPCs. Dynamic credentials are endpoint selectors rather than environment values and stay in their own collection.

ProviderEnvironmentValue: One environment value and all metadata that shares its key. Names are unique within a snapshot. static_credential_binding is present exactly when classification is STATIC_CREDENTIAL. Snapshots that violate either rule are invalid.

ProviderMutationReceipt: Immutable, secret-free record of one sandbox's intended provider mutation.

ProviderProfile: Provider type profile metadata exposed to clients.

ProviderProfileCredential: Provider credential declaration.

ProviderProfileDiagnostic: Provider profile validation diagnostic.

ProviderProfileDiscovery: Provider profile local discovery declaration.

ProviderProfileFile: EXPERIMENTAL: Provider file templates may change or be removed.

ProviderProfileImportItem: Provider profile payload with optional source metadata for diagnostics.

ProviderProfileResponse: Provider profile response.

ProviderReadinessObservation: Installed state reported by the current supervisor. Process installation is acknowledged by the authenticated sandbox boundary after replacing its environment for future process launches.

ProviderReadinessStatus: Operator view of desired and observed state; contains no credential material.

ProviderResponse: Provider response.

PushSandboxLogsRequest: Batch of log lines pushed from sandbox to server.

PushSandboxLogsResponse: Push sandbox logs response.

RefreshSandboxTokenRequest: RefreshSandboxToken request. The calling principal must already be a sandbox principal (i.e. the request carries a still-valid gateway-minted JWT in its Authorization header). Extension service names are resolved against server-owned registrations and the sandbox's effective policy; callers never choose token audiences directly.

RefreshSandboxTokenResponse: RefreshSandboxToken response. The new token replaces the supervisor's in-memory bearer credential.

RejectDraftChunkRequest: Reject a single draft chunk.

RejectDraftChunkResponse

RelayClose: Either side requests closure of a relay channel.

RelayFrame

A single frame on the RelayStream RPC.

The supervisor MUST send init as the first frame. All subsequent frames in either direction carry raw bytes in data.

RelayInit: Initial RelayStream frame sent by the supervisor to claim a pending relay.

RelayOpen

Gateway requests the supervisor to open a relay channel.

On receiving this, the supervisor should initiate a RelayStream RPC to the gateway, sending a RelayInit in the first RelayFrame to associate the new HTTP/2 stream with the pending relay slot. The supervisor bridges that stream to the requested local target.

RelayOpenResult: Supervisor reports the result of a relay open request.

RemoveNetworkBinary

RemoveNetworkEndpoint

RemoveNetworkRule

RemoveWorkspaceMemberRequest: Remove workspace member request.

RemoveWorkspaceMemberResponse: Remove workspace member response.

ReportEndpointStatusRequest: Complete endpoint status report for the caller's current configuration.

ReportEndpointStatusResponse: Empty acknowledgement for a persisted endpoint status report.

ReportMainProcessExitRequest: Terminal result reported before the supervisor shuts down. A successful RPC response confirms that the result was durably handled by the gateway.

ReportMainProcessExitResponse

ReportPolicyStatusRequest: Report policy load status (called by sandbox runtime after reload attempt).

ReportPolicyStatusResponse: Report policy status response.

ReportProviderReadinessRequest: Installation evidence from the authenticated supervisor for this sandbox. A caller-provided instance identifier alone never establishes authority.

ReportProviderReadinessResponse: Acknowledges accepted evidence without granting a separate session authority. Identical retries do not extend the evidence's original acceptance time.

ReportSandboxConfigurationRequest

ReportSandboxConfigurationResponse

ResourceCapabilities: Static portable resource request forms reported by a compute driver. An omitted domain means the driver does not report that domain.

ResourceRequirements

ResumeSandboxRequest: Resume sandbox request.

RevokeSshSessionRequest: Revoke SSH session request.

RevokeSshSessionResponse: Revoke SSH session response.

RotateProviderCredentialRequest

RotateProviderCredentialResponse

Sandbox

Public sandbox resource exposed by the OpenShell API.

This is the canonical gateway-owned view of a sandbox. It merges user intent (spec) with gateway-managed metadata and status derived from internal compute-driver observations.

Note: The namespace field has been removed from the public API. It remains in the internal DriverSandbox message as a compute-driver implementation detail.

SandboxCommandUpdate: Presence selects replacement, including an explicitly empty list.

SandboxCondition: User-facing sandbox condition derived from platform or gateway observations.

SandboxConfigRevision: Identity needed to correlate effective sandbox configuration with the policy-history row whose apply status the gateway records.

SandboxConfigurationAdmission

SandboxLogLine: Log line correlated to a sandbox.

SandboxMapUpdate: Presence selects replacement, including an explicitly empty map.

SandboxPolicyRevision: A versioned policy revision with metadata.

SandboxProvisioning: Durable provisioning attempt, independent of supervisor registration and polling.

SandboxResources

SandboxResponse: Sandbox response.

SandboxServiceExposure: Create-time request to expose one loopback HTTP service in a sandbox.

SandboxServiceLevel

SandboxSpec: Desired sandbox configuration provided through the public API.

SandboxStartup

SandboxStatus

User-facing sandbox status derived by the gateway from compute-driver observations.

Public status does not embed driver-only flags such as deleting.

SandboxStreamEvent: One event in a sandbox watch stream.

SandboxStreamWarning: Recoverable loss notification on a watch stream. Emitted when the server skips ahead after a broadcast lag instead of terminating; the stream keeps running. Cursors are opaque, so this message is the only signal that events were skipped. Unrecoverable loss (a trimmed or foreign resume cursor) is reported as an OUT_OF_RANGE stream status, not this message.

SandboxTemplate

Historical inline compute template mapped onto compute-driver template inputs.

Despite its name, this is not a reusable named sandbox template resource. It is an inline part of SandboxSpec kept for v1 compatibility. A future breaking API cleanup may rename this message to free SandboxTemplate for the reusable template resource now represented by SandboxWorkloadTemplate.

SandboxTemplateResponse

SandboxUpdates: Optional sandbox mutations are separate from OpenShell so existing generated OpenShell server implementations remain source-compatible.

SandboxUpdates.SandboxUpdatesClient: Client for SandboxUpdates

SandboxWorkloadConfig

SandboxWorkloadTemplate

Reusable named sandbox workload template resource.

This is the actual workspace-scoped template resource used to create sandboxes by reference. It uses the longer name in v1 to avoid colliding with the historical inline SandboxTemplate message. A future breaking API cleanup may rename this resource to SandboxTemplate.

SandboxWorkloadTemplateProvenance

SandboxWorkloadTemplateSpec

ServiceEndpoint: Persisted sandbox service endpoint.

ServiceEndpointResponse: Response containing a service endpoint and, when available, its local URL.

SessionAccepted: Gateway accepts the supervisor session.

SessionRedirect

Gateway declines to own this session and names the replica that should.

Sent instead of SessionAccepted when the placement ring puts the sandbox on a different live replica, and to established sessions when their gateway shuts down. The supervisor reconnects to peer_endpoint once with SupervisorHello.redirected set, and falls back to its configured gateway address if that fails.

SessionRejected: Gateway rejects the supervisor session.

SshRelayTarget: Built-in SSH relay target.

SshSession: SSH session record stored in persistence.

StartSandboxRequest: Start sandbox request.

StaticCredentialBinding: Endpoint allowlist for one static provider credential environment variable.

StaticCredentialEndpointBinding: One network endpoint at which a static provider credential may be resolved.

StopSandboxRequest: Stop sandbox request.

SubmitPolicyAnalysisRequest: Submit analysis results from sandbox to gateway.

SubmitPolicyAnalysisResponse

SupervisorHeartbeat: Supervisor heartbeat.

SupervisorHello: Supervisor identifies itself and the sandbox it manages.

SupervisorMessage: Envelope for supervisor-to-gateway messages on the ConnectSupervisor stream.

SuspendSandboxRequest: Suspend sandbox request.

TcpForwardFrame: A single frame on the CLI-to-gateway TCP forward stream.

TcpForwardInit: Initial frame for one TCP forward stream.

TcpRelayTarget: TCP target dialed by the supervisor from inside the sandbox.

TokenGrantFailureObservation: A refused grant and its destination, without request paths or remote text. This describes the failed attempt, not the destination's current health.

TokenGrantStatus: Latest token-grant state sent by the authenticated supervisor.

UndoDraftChunkRequest: Reverse an approval (remove merged rule from active policy).

UndoDraftChunkResponse

UpdateConfigRequest: Update sandbox policy request.

UpdateConfigResponse: Update sandbox policy response.

UpdateProviderProfilesRequest: Update one custom provider profile request.

UpdateProviderProfilesResponse: Update one custom provider profile response.

UpdateProviderRequest: Update provider request.

UpdateSandboxRequest: Update selected configuration of a stopped sandbox. Omitted fields are unchanged. Start explicitly after a successful update. With no fields selected, resume the pending operation stored by the gateway using the current resource version.

WatchSandboxRequest: Watch sandbox request.

WorkspaceMember: Workspace membership record.

Enums

ConfigApplyOutcome: Result of applying a component revision at its owning runtime boundary.

ConfigComponent: Component whose desired state is tracked by a durable update operation.

ConfigSnapshotRevision.ComponentOneofCase: Enum of possible cases for the "component" oneof.

ConfigUpdateOperationState: Durable lifecycle of one desired-state update operation.

ConfigurationAdmissionState

DeletionOutcome: Result of a public delete, membership removal, or session revocation. Default requests return NOT_FOUND for a missing target. With allow_missing, only a missing target becomes ALREADY_ABSENT; parent lookup, authorization, validation, precondition, and backend errors retain their normal status. These results describe the targeted resource, not a same-name replacement.

EndpointFailureDomain: Subsystem whose closed code set explains an endpoint failure. Each domain defines its codes, stages, recovery actions, and the endpoint results it can explain. Kept at the end of the file so adding it does not renumber existing generated descriptors.

EndpointResult: Last observed network result for a configured external tool endpoint. Results describe accepted traffic observations, not present availability.

ExecSandboxEvent.PayloadOneofCase: Enum of possible cases for the "payload" oneof.

ExecSandboxInput.PayloadOneofCase: Enum of possible cases for the "payload" oneof.

ExtensionKind

GatewayMessage.PayloadOneofCase: Enum of possible cases for the "payload" oneof.

PeerNotifyConfigUpdateRequest.ScopeOneofCase: Enum of possible cases for the "scope" oneof.

PeerRelayFrame.PayloadOneofCase: Enum of possible cases for the "payload" oneof.

PolicyMergeOperation.OperationOneofCase: Enum of possible cases for the "operation" oneof.

PolicyStatus: Policy load status.

ProviderCredentialRefreshRecoveryAction: Stable recovery action for the most recent provider credential refresh failure. Kept after the pre-existing enums so adding it does not renumber their generated descriptors. Clients should use this field instead of parsing last_error.

ProviderCredentialRefreshStrategy

ProviderCredentialTokenGrantType: Provider credential token grant configuration. When present, the credential is obtained dynamically via OAuth2 grant when needed.

ProviderEnvironmentValueClassification: Receivers treat UNSPECIFIED and unknown values as secret.

ProviderMutationKind: Operation whose installed authority is tracked by a receipt.

ProviderProfileCategory: Stable provider profile categories used by clients for grouping and filtering.

ProviderReadinessReason: Closed reason categories are safe to display. Raw installation errors are never part of the readiness protocol.

ProviderReadinessState: Readiness states describe persisted intent separately from installed state.

RelayFrame.PayloadOneofCase: Enum of possible cases for the "payload" oneof.

RelayOpen.TargetOneofCase: Enum of possible cases for the "target" oneof.

SandboxPhase

High-level sandbox lifecycle phase derived by the gateway.

Clients should rely on this normalized lifecycle summary for readiness and deletion decisions instead of interpreting raw conditions.

SandboxRestartPolicy: Policy applied when the canonical main process exits outside an intentional stop or delete operation. Kept after existing enums so generated enum descriptors remain stable.

SandboxStreamEvent.PayloadOneofCase: Enum of possible cases for the "payload" oneof.

ServiceAuthorizationMode: Controls whether an exposed service receives the request's application Authorization header.

ServiceStatus: Service status enum.

SupervisorMessage.PayloadOneofCase: Enum of possible cases for the "payload" oneof.

TcpForwardFrame.PayloadOneofCase: Enum of possible cases for the "payload" oneof.

TcpForwardInit.TargetOneofCase: Enum of possible cases for the "target" oneof.

WorkspaceRole: Workspace-scoped role for members.

Table of Contents

Namespace Openshell.V1

Classes

Enums