omnyshell_hub library

OmnyShell Hub: run a Hub that authenticates principals, registers nodes, and brokers secure sessions.

final hub = OmnyShellHub(HubConfig(
  securityContext: context,
  authenticator: authenticator,
));
await hub.start();

Classes

ActiveSessionDetachRequest: Client → Hub: detach an active (attached) session on nodeId from another connection — e.g. when a full-screen program owns the original terminal. sessionRef is an id/short-id/prefix, or empty to target the caller's sole active session. Correlated by requestId.
ActiveSessionDetachResponse: Hub → Client: the result of an active-session detach. Correlated by requestId.
AiConfig: Immutable AI configuration: which provider/model to use, the API key, the default agent mode and loop bounds.
AiConfigDescription: A non-secret summary of the resolved AI configuration, used by omnyshell ai show to report settings and where each value came from. The API key is never included — only keySet and keyFromEnv.
AiConfigIo: Loads and persists AiConfig from the environment and ~/.omnyshell/ai.yaml.
AiConfigRequest: Client → Hub: ask for the Hub's default AI configuration (provider/model and agent defaults) so a browser embedder can offer "use the Hub default" without ever seeing an API key. Correlated by requestId.
AiConfigResponse: Hub → Client: the Hub's default AI configuration. Never carries an API key — the key stays on the Hub and is injected when proxying. available is false when the Hub has no AI provider configured. Correlated by requestId.
AuditLog: A bounded, in-memory audit log of Hub security events.
AuditRecord: A single audit entry recording a security-relevant Hub event.
Authenticator: Validates a Credential and resolves it to a Principal.
AuthFail: Failed authentication.
AuthOk: Successful authentication, carrying the resolved identity and a session token bound to this connection.
AuthorizedKey: A single authorized identity: a principal, the public key that proves it, and the roles it is granted.
AuthorizedKeysStore: An in-memory authorized_keys-style trust store consulted by PublicKeyAuthenticator.
Authorizer: Decides whether an authenticated Principal may open a session on a node.
AuthRequest: A login attempt presenting a credential.
CertGenerator: Generates the TLS certificate material an OmnyShell Hub needs to run.
CertificateIdentity: Extracts a stable public-key identity from an X.509 certificate.
Channel: One logical, bidirectional stream multiplexed over a connection.
ChannelClose: Tear down a channel.
ChannelEof: Half-close a stream (typically stdin) on the channel.
ChannelExit: Node → Client: the process exited.
ChannelId: A logical channel identifier, scoped to a single physical connection.
ChannelMultiplexer: Multiplexes logical Channels over a single OmnyShellConnection.
ChannelResize: Resize the terminal of an interactive session.
ChannelSignal: Deliver a POSIX signal to the session's process.
ChannelWindow: Backpressure credit grant for a stream on a channel.
Clock: Time source used throughout OmnyShell so tests can fix now.
CompositeAuthenticator: Combines several Authenticators, trying each in order until one succeeds.
ControlFrame: A control message frame (carried as a WebSocket text frame).
ControlMessage: Base class for every structured control message.
Credential: A credential presented during the authentication handshake.
CredentialProvider: Produces the AuthRequest a node or client sends in response to the Hub's challenge hello.
CredentialStore: On-disk store of Hub logins, keyed by Hub URL, with a remembered default.
DataFrame: A binary stream-data frame (carried as a WebSocket binary frame) with a fixed 10-byte header followed by the raw payload bytes.
DetachedSessionInfo: A user-facing view of a detached session living in a node's in-memory registry, as returned by the list API and relayed through the Hub.
DetachedSessionKillRequest: Client → Hub: terminate the caller's detached session sessionRef (an unambiguous id or prefix) on nodeId. Correlated by requestId.
DetachedSessionKillResponse: Hub → Client: the result of a detached-session kill. Correlated by requestId.
DetachedSessionsRequest: Client → Hub: list the caller's detached sessions on nodeId. Correlated to the response by requestId (a connection-level request/response RPC).
DetachedSessionsResponse: Hub → Client: the caller's detached sessions. Correlated by requestId.
DriveCredentialEntry: One masked git-credential entry returned by a list (secrets never leave the node — description is the credential's masked toString).
DriveCredentialRequest: Client → Hub: manage the caller's own git credentials on nodeId.
DriveCredentialResponse: Hub → Client: the result of a drive-credential operation. Correlated by requestId.
Ed25519PublicKey: An Ed25519 public key, used to identify users and nodes in an authorized_keys-style trust store. Equality is by key bytes.
ErrorCodes: Stable, machine-readable error codes carried in error control messages and surfaced on OmnyShellExceptions.
FrameCodec: Encodes and decodes OmnyShellFrames to and from WebSocket events.
GeneratedCertificates: The paths of the TLS files produced by CertGenerator.generate.
HeartbeatMonitor: Watches node liveness and reports nodes that have stopped heartbeating.
Hello: First frame after the WebSocket upgrade. The Hub sends hello with a single-use nonce; the peer replies with its role and capabilities.
HttpProxyRequest: Client → Hub: make an outbound HTTPS request to an AI provider on the client's behalf (the browser cannot, due to CORS). The Hub validates the target against an allowlist, optionally injects credentials, and replies with an HttpProxyResponse. Correlated by requestId.
HttpProxyResponse: Hub → Client: the result of a proxied AI request. On a transport-level failure (rejected host, timeout, DNS) error is set and statusCode is 0. Correlated by requestId.
HttpProxyService: Proxies authenticated clients' outbound HTTPS requests to AI provider APIs.
HubBroker: The brain of the Hub: authenticates peers, registers nodes, authorizes and brokers sessions, and relays session bytes between clients and nodes.
HubConfig: Configuration for an OmnyShellHub.
MachineId: Reads a stable, per-machine identifier provided by the operating system.
NodeActiveSessionDetach: Hub → Node: detach the principal's active session sessionRef.
NodeActiveSessionDetachResponse: Node → Hub: the result of an active-session detach. Correlated by requestId.
NodeCapabilities: What a node can do, advertised to the Hub after registration and relayed to clients during discovery.
NodeCapabilitiesMessage: Node → Hub: advertises capabilities after registration.
NodeDescriptor: A node's public description as registered with the Hub and returned by discovery (nodes list). Combines identity, platform, operator labels and advertised capabilities.
NodeDetachedSessionKillRequest: Hub → Node: terminate the principal's detached session sessionRef.
NodeDetachedSessionKillResponse: Node → Hub: the result of a detached-session kill. Correlated by requestId.
NodeDetachedSessionsRequest: Hub → Node: list the principal's detached sessions. Correlated by requestId.
NodeDetachedSessionsResponse: Node → Hub: the principal's detached sessions. Correlated by requestId.
NodeDriveCredentialRequest: Hub → Node: manage principal's git credentials. The principal is stamped by the hub from the authenticated peer; the node only ever mutates that principal's scope. Correlated by requestId.
NodeDriveCredentialResponse: Node → Hub: the result of a drive-credential operation. entries carries the masked credential list for list. Correlated by requestId.
NodeHeartbeat: Node → Hub: periodic liveness signal with a monotonic sequence number.
NodeHeartbeatAck: Hub → Node: acknowledges a heartbeat.
NodeId: Stable identity of a node, used by clients to address it (instead of a host:port). Equality is by value.
NodeListRequest: Client → Hub: requests the list of nodes the client may see.
NodeListResponse: Hub → Client: the discovered nodes.
NodeRegister: Node → Hub: registers the node's identity and platform.
NodeRegistered: Hub → Node: confirms registration.
NodeRegistry: Tracks the nodes registered with the Hub and answers discovery queries.
NodeSessionDetach: Hub → Node: detach the session on the node-side channel, on behalf of principal. Mirrors SessionDetachRequest across the relay.
NodeSessionDetached: Node → Hub: the session was detached and now lives in the node registry.
NodeSessionOpen: Hub → Node: instructs the node to start a session on a node-side channel.
NodeSessionOpened: Node → Hub: the node accepted and started the session.
NodeSessionRejected: Node → Hub: the node refused the session.
NodeSessionScreenRequest: Hub → Node: fetch the current screen snapshot of the principal's session sessionRef. Correlated by requestId.
NodeSessionScreenResponse: Node → Hub: the current screen snapshot of a session. The replayable bytes (the same a resume would paint) are base64-encoded in screenBase64. Correlated by requestId.
NodeTunnelConnect: Hub → exposer (node or client): a public connection arrived; adopt channel, dial targetHost:targetPort, and bridge bytes. Reply with NodeTunnelConnected or NodeTunnelConnectFailed.
NodeTunnelConnected: Exposer → Hub: the target was dialed; the Hub may relay bytes on channel.
NodeTunnelConnectFailed: Exposer → Hub: the target dial failed; the Hub closes the public socket.
OmnyShellConnection: A duplex, frame-oriented link between two OmnyShell peers.
OmnyShellFrame: A decoded unit travelling over a connection: either a structured control message (ControlFrame) or a binary stream payload (DataFrame).
OmnyShellHub: An embeddable OmnyShell Hub: a TLS WebSocket endpoint wired to a HubBroker.
OmnyUid: A deterministic, globally-stable identifier for a node or a hub.
Ping: Application-level keepalive request, used to measure round-trip latency and detect half-open connections.
PlatformInfo: Describes the operating system and architecture a node runs on, advertised to clients during discovery and shown by the :info local command.
Pong: Reply to a Ping.
PortRange: An inclusive TCP port range [start, end].
Principal: An authenticated identity, as resolved by an Authenticator.
PrincipalId: Identity of an authenticated principal (a user or a node account) as known to the Hub. Equality is by value.
ProtocolError: A connection- or channel-level error.
PtySpec: Requested pseudo-terminal geometry for an interactive shell.
PublicKeyAuthenticator: Authenticates PublicKeyCredentials against an AuthorizedKeysStore.
PublicKeyCredential: An Ed25519 public-key credential: the client proves possession of the private key by signing the connection challenge.
PublicKeyCredentialProvider: A CredentialProvider that signs the connection nonce with an Ed25519 private key.
RegisteredNode: A node currently registered with the Hub, with its live connection and liveness bookkeeping.
RoleBasedAuthorizer: A role-based Authorizer with a small, predictable policy:
Session: A domain view of a brokered session: who opened it, on which node, in what mode, and its current state and exit code.
SessionDetached: Hub → Client: the session was detached; resume it later by shortId.
SessionDetachRequest: Client → Hub: detach the live session on channel, keeping the node-side PTY/shell/processes running. Optional timeoutSeconds schedules automatic cleanup; null keeps the session indefinitely.
SessionId: Unique identity of a brokered session, minted by the Hub when a session is opened. Equality is by value.
SessionOpen: Client → Hub: opens a session on a node over a new client channel.
SessionOpened: Hub → Client: the session is open.
SessionRejected: Hub → Client (or Node → Hub via NodeSessionRejected): the session could not be opened.
SessionRoute: A live route bridging a client-side channel to a node-side channel for one brokered session. The Hub relays bytes by rewriting the channel id between the two ends.
SessionRouter: Holds the Hub's live session routes with O(1) lookup from either end and by session id.
SessionScreenRequest: Client → Hub: fetch the current screen snapshot of the caller's session sessionRef (active or detached) on nodeId, without attaching to it. Correlated by requestId.
SessionScreenResponse: Hub → Client: the current screen snapshot of a session. Correlated by requestId.
ShellBackend: Starts ShellSessions on a node in response to authorized session opens.
ShellRequest: A request to start a process or interactive shell on a node.
ShellSession: A running process or shell on the node, with byte streams wired to the session channel.
StoredSession: A persisted login to a single Hub.
SystemClock: The default Clock, backed by the system wall clock (UTC).
TokenAuthenticator: Authenticates TokenCredentials against an in-memory token store.
TokenCredential: A bearer-token credential, validated against a token store. Relies on TLS for secrecy in transit.
TokenCredentialProvider: A CredentialProvider that presents a bearer token.
TokenGrant: A token and the identity it grants.
TunnelCloseRequest: Client → Hub: close the caller's tunnel tunnelRef (a full id or unambiguous prefix). Correlated by requestId.
TunnelCloseResponse: Hub → Client: the result of a tunnel close. Correlated by requestId.
TunnelInfo: A user-facing view of an active TCP tunnel held by the Hub, as returned by the list API and relayed to the owning client.
TunnelListRequest: Client → Hub: list the caller's active tunnels. Correlated by requestId.
TunnelListResponse: Hub → Client: the caller's active tunnels. Correlated by requestId.
TunnelOpened: Hub → Client: the tunnel is open and listening. Correlated by requestId.
TunnelOpenRequest: Client → Hub: open a tunnel that exposes targetHost:targetPort (reachable by nodeId, or the requesting client's own machine when nodeId is the @local sentinel) on a public Hub port. When publicPort is set the Hub validates it against its configured range; otherwise the Hub allocates a free port in range. Correlated by requestId.
TunnelRegistration: A live tunnel held by the Hub: a public serverSocket whose accepted connections are bridged to targetHost:targetPort over the exposer's connection.
TunnelRegistry: The Hub's table of active tunnels plus the set of public ports in use, so allocation and specific-port validation are O(1).
TunnelRejected: Hub → Client: the tunnel was refused. Correlated by requestId.
UidComputer: Computes deterministic OmnyUids from identity material.
UidResolution: The outcome of resolving an entity's UID against its persisted value.
UidStore: Persists an entity's UID under ~/.omnyshell/<fileName> and detects changes.
WsServerEndpoint: A Hub-side TLS WebSocket listener.

Enums

AgentPhase: Which phase of the agent loop a model request belongs to, used to pick the model via AiConfig.modelFor.
AiProviderKind: The AI provider an AiConfig talks to.
DataOpcode: The stream a binary data frame belongs to, encoded as the msgType byte of the data-frame header.
HttpProxyCredentialMode: How the Hub should authenticate a proxied AI request.
SessionMode: How a session runs on the node.
SessionState: Lifecycle state of a session as tracked by the Hub.
ShellFamily: The command-language family of a node's interactive shell.

Constants

kMinProtocolVersion → const int: The lowest protocol version this build can interoperate with.
kProtocolVersion → const int: The wire protocol version implemented by this package.
omnyShellVersion → const String: The canonical OmnyShell package version (kept in sync with pubspec.yaml).

Functions

defaultModelFor(AiProviderKind provider) → String: The default model for provider when neither the user, env, nor ai.yaml (CLI) or the Hub (web) specified one.
isProtocolCompatible(int remoteVersion, {int? remoteMin}) → bool: Whether a peer advertising remoteVersion (with optional remoteMin) is compatible with this build.
newId() → String: Generates a new globally-unique identifier (UUID v4).
newSecureToken([int byteLength = 32]) → String: Returns byteLength cryptographically secure random bytes encoded as a URL-safe, unpadded base64 string.
shortId(String id, [int length = 8]) → String: Derives a short, human-friendly handle from a full id.

Typedefs

ControlDecoder = ControlMessage Function(int? channelId, Map<String, dynamic> data): Decodes a control-message payload (the envelope d) for a registered type.
OnConnection = void Function(WebSocketConnection connection): Called for every accepted WebSocket connection.

Exceptions / Errors

AuthException: Authentication failed: credentials missing, malformed or rejected.
AuthorizationException: The authenticated principal is not permitted to perform the action.
CertGeneratorException: Thrown when certificate generation cannot complete.
ChannelException: A logical channel was closed or referenced after teardown.
NodeUnavailableException: The requested node is unknown or offline.
OmnyShellException: Base type for every expected, classified failure raised by OmnyShell.
OmnyShellTimeoutException: An operation exceeded its deadline.
ProtocolException: A frame could not be decoded, or a message violated the protocol.
SessionRejectedException: A session could not be opened (rejected by the Hub or node).
TransportException: The underlying transport failed or closed unexpectedly.
TunnelRejectedException: A tunnel could not be opened (rejected by the Hub).

omnyshell_hub library

Classes

Enums

Constants

Functions

Typedefs

Exceptions / Errors

omnyshell package

omnyshell_hub library