OpenShell Documentation

The openshell-providers crate is responsible for the discovery and normalization of credentials required by sandboxes at runtime. It isolates provider-specific logic (such as parsing rules and discovery mechanisms) from the main CLI and gateway control flows.

Key Responsibilities

• Discovery: Locating local credentials within environment variables and known configuration files.
• Normalization: Converting discovered data into standardized provider records.
• Encapsulation: Maintaining provider-specific parsing rules within dedicated provider modules.
• Security: Ensuring credential values are not logged during the discovery process.

Architecture Integration

• The Gateway is responsible for persisting provider records.
• The Sandbox Supervisor fetches the resolved provider environment from the gateway and injects credentials into agent child processes.
• The Router handles routing inference requests.

Gateway Interceptors are a first-class extension system in OpenShell designed to allow operators and external integrators to customize gateway API behavior. They enable the observation, modification, validation, rejection, or auditing of gateway operations at well-defined phases.

Key Use Cases:

• Enforcing tenancy and quotas (e.g., limiting the number of running sandboxes per user).
• Enforcing naming conventions.
• Verifying policy writes against an external authority.
• Syncing policies and providers from an external source of truth.
• Restricting driver configuration payloads to approved schemas or fixed values.

Distinction from Drivers:

• Drivers: Provide or replace platform-specific implementations (e.g., how sandboxes are provisioned on Docker, Kubernetes, or VMs).
• Gateway Interceptors: Provide gateway-level governance and business logic around API operations (e.g., tenancy, quotas, and policy authority).

The OpenShell Gateway API is structured around platform objects and operational streams. It provides interfaces for managing the lifecycle of sandboxes, interacting with infrastructure providers, managing security policies, configuring inference settings, and handling observability data. All domain objects include shared metadata such as stable server-generated IDs, human-readable names, creation timestamps, and labels.

| Area | Examples |
|---|---|
| Sandbox lifecycle | Create, list, delete, watch, exec, SSH session bootstrap, ForwardTcp service forwarding. |
| Providers | Store provider records, discover credentials, resolve runtime environment. |
| Policy and settings | Get effective sandbox config, update sandbox policy, manage global settings. |
| Inference | Set gateway-level model/provider config and resolve sandbox route bundles. |
| Observability | Push sandbox logs, stream sandbox status and logs to clients. |

The OpenShell gateway uses a protobuf object store for persistence. Domain services store typed protobuf messages as opaque binary payloads, while the database maintains indexed metadata for lookup, versioning, and workflow state.

Supported Backends:

• SQLite: The default local store. The adapter automatically sets file permissions to 0o600 for security.
• Postgres: Supported for high-availability (HA) deployments requiring external databases or multi-replica coordination.

Core Schema Columns:

• id: Stable gateway-generated primary key.
• object_type: Logical resource kind (e.g., sandbox, provider, ssh_session, inference_route, sandbox_policy).
• name: Unique human-readable name within an object type.
• resource_version: Monotonically increasing counter used for Optimistic Concurrency Control (CAS).
• payload: The Prost-encoded protobuf payload.
• labels: JSON object for Kubernetes-style filtering.
• scope & version: Used for scoped/versioned records like policy revisions.

The Gateway serves as the OpenShell control plane. Its primary functions include:

• API Serving: Exposes gRPC APIs for sandbox lifecycle, provider management, policy updates, settings, inference configuration, logs, watch streams, and relay forwarding. It also serves HTTP endpoints for health, WebSocket tunnels, and edge-auth flows.
• Authentication: Authenticates clients (CLI, SDK, TUI) and sandbox callbacks.
• State Management: Persists platform state in SQLite or Postgres and manages provider credentials and inference configuration.
• Workload Coordination: Instructs compute runtimes (Docker, Kubernetes, etc.) to create or delete sandbox workloads and coordinates supervisor relay sessions (connect, exec, file sync, service forwarding).

Note: The gateway does not enforce agent network policy at request time; enforcement occurs inside the sandbox via the supervisor and proxy.