ClientRuntime class

An embeddable OmnyShell client: authenticates with the Hub, discovers nodes, and opens exec / interactive sessions.

final client = OmnyShellClient(config);
await client.connect();
final result = await client.execute(nodeId: 'web-01', command: 'uname -a');

Constructors

ClientRuntime(ClientConfig config)
Creates a client runtime from config.

Properties

config → ClientConfig
The client configuration.
final
hashCode → int
The hash code for this object.
no setterinherited
isConnected → bool
Whether the client is connected and authenticated.
no setter
principal → Principal?
The authenticated principal (available after connect).
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

close() → Future<void>
Disconnects from the Hub and releases resources.
closeTunnel(String tunnelRef) → Future<TunnelCloseResult>
Closes the caller's tunnel tunnelRef (a full id or unambiguous prefix).
connect() → Future<void>
Connects to the Hub and authenticates.
detachActiveSession({required String nodeId, String sessionRef = '', Duration? timeout}) → Future<ActiveSessionDetachResult>
Detaches one of the caller's active sessions on nodeId from this connection — used to leave a session whose terminal is busy with a full-screen program. sessionRef is a full id, short handle or prefix; leave it empty to detach the sole active session. The attached client is disconnected by the node.
driveCredentialAdd({required String nodeId, required String host, required Map<String, dynamic> credential}) → Future<DriveCredentialResult>
Adds/overwrites the caller's own git credential for host on nodeId. credential is an omnydrive GitCredential JSON map.
driveCredentialList({required String nodeId}) → Future<DriveCredentialResult>
Lists the caller's own git credentials on nodeId (secrets masked).
driveCredentialRemove({required String nodeId, required String host}) → Future<DriveCredentialResult>
Removes the caller's own git credential for host on nodeId.
execute({required String nodeId, required String command, List<String> args = const [], Map<String, String> env = const {}, String? cwd, ShellFamily? shellFamily}) → Future<ExecResult>
Runs command to completion on nodeId, capturing its output.
executeStreaming({required String nodeId, required String command, List<String> args = const [], Map<String, String> env = const {}, String? cwd, ShellFamily? shellFamily, required void onStdout(List<int> chunk), required void onStderr(List<int> chunk)}) → Future<int>
Runs command on nodeId and forwards its output live: each stdout/stderr chunk is delivered to onStdout/onStderr as it arrives, rather than being buffered until the command exits. Returns the process exit code.
fetchHubAiConfig() → Future<HubAiConfig>
Fetches the Hub's default AI configuration (provider/model, never a key), so a browser embedder can offer "use the Hub default". Returns a HubAiConfig with available == false when the Hub has none configured.
killDetachedSession({required String nodeId, required String sessionRef}) → Future<DetachedSessionKillResult>
Deprecated alias for killSession (which now also terminates running sessions, not just detached ones).
killSession({required String nodeId, required String sessionRef}) → Future<DetachedSessionKillResult>
Terminates one of the caller's sessions on nodeId — running (attached) or detached — named by sessionRef (a full id, short handle, or unambiguous prefix). Killing a running session disconnects its attached client; the node enforces that the caller owns the session.
listDetachedSessions({required String nodeId}) → Future<List<DetachedSessionInfo>>
Lists only the caller's detached sessions on nodeId.
listNodes({Map<String, String> filter = const {}}) → Future<List<NodeDescriptor>>
Lists the nodes visible to this client, with an optional label filter.
listSessions({required String nodeId}) → Future<List<DetachedSessionInfo>>
Lists the caller's sessions on nodeId — both active (attached) and detached. The node filters by owner, so only the authenticated user's sessions are returned.
listTunnels() → Future<List<TunnelInfo>>
Lists the caller's active tunnels held by the Hub.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
openSession({required String nodeId, SessionMode mode = SessionMode.exec, String? command, List<String> args = const [], Map<String, String> env = const {}, String? cwd, PtySpec? pty, String? resumeSessionId, ShellFamily? shellFamily}) → Future<RemoteSession>
Opens a session on nodeId.
openTunnel({required int targetPort, String nodeId = '', String targetHost = 'localhost', int? publicPort, bool local = false, bool secure = false}) → Future<TunnelHandle>
Opens a tunnel that exposes targetPort — reachable by nodeId, or this client's own machine when local is set — on a public Hub port. When publicPort is given the Hub validates it against its configured range; otherwise the Hub allocates one in range. Completes once the Hub confirms, or throws TunnelRejectedException if refused.
peekSession({required String nodeId, required String sessionRef}) → Future<SessionScreenResult>
Fetches the current screen snapshot of one of the caller's sessions on nodeId — running (attached) or detached — named by sessionRef (a full id, short handle, or unambiguous prefix), without attaching to it. The returned bytes are exactly what a resume would paint; no input is ever delivered to the session. The node enforces that the caller owns it.
ping() → Future<Duration>
Measures round-trip latency to the Hub.
proxyHttp({required String method, required String url, Map<String, String> headers = const {}, String body = '', HttpProxyCredentialMode credentialMode = HttpProxyCredentialMode.none, String? provider}) → Future<HttpProxyResponse>
Asks the Hub to perform an outbound AI HTTPS request on the caller's behalf — used by the browser client, which cannot reach provider APIs directly (CORS). The Hub enforces an https + host allowlist and, when credentialMode is HttpProxyCredentialMode.hubDefault, injects its own key for provider; otherwise headers (with the caller's key) are forwarded verbatim. Completes with the provider's reply, or an HttpProxyResponse whose error is set on a rejected target / transport failure.
resumeSession({required String nodeId, required String sessionId, PtySpec? pty}) → Future<RemoteSession>
Resumes a previously detached interactive session on nodeId, identified by sessionId (a full id, short handle, or unambiguous prefix). The returned session continues exactly where it was detached; the node enforces that the caller owns it.
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited