Connect to a gateway

Everything goes through one OpenShellClient (or the IOpenShellClient interface). Create one per gateway and reuse it: it holds the HTTP/2 connection. The client connects lazily, so creating it never fails because the gateway is down; call Health.CheckAsync() when startup must verify that the gateway is reachable.

There are three ways to get a client.

A registered CLI gateway

If you use the OpenShell CLI, the gateways it registered are on disk with their endpoint, authentication mode, mTLS bundle, and cached tokens. GatewayClient.Connect builds a client from one:

// The gateway the OpenShell CLI made active, with its stored credentials.
using var client = GatewayClient.Connect();

// Or a registered gateway by name.
using var staging = GatewayClient.Connect("staging");

var info = await client.Health.GetGatewayInfoAsync();
Console.WriteLine(info);

With no name it uses the active gateway: $OPENSHELL_GATEWAY, then the user's active_gateway file, then the system one. An expired OIDC token is renewed with the stored refresh token and written back, so the CLI stays signed in too. Gateway discovery describes where registrations are read from.

An explicit endpoint

Pass the address and the credentials in OpenShellClientOptions:

using var client = new OpenShellClient(new OpenShellClientOptions
{
    Address = new Uri("https://gateway.example.com"),
    Auth = Auth.StaticToken(Environment.GetEnvironmentVariable("OPENSHELL_TOKEN")!),
});

// The client connects lazily; a health check verifies that the gateway is reachable.
var health = await client.Health.CheckAsync();
Console.WriteLine($"{health.Status}: {health.Version}");

Auth takes any IAuthProvider: a static token as here, a refreshable token, OIDC client credentials, Cloudflare Access, or none. Tls takes a private CA and a client certificate for mTLS. See Authentication.

Important

The SDK refuses to send credentials over plaintext http:// to a host other than loopback, and throws OpenShellException with OpenShellErrorKind.InvalidConfig.

An ASP.NET Core or Generic Host app

The OpenShell.Net.DependencyInjection package registers a singleton IOpenShellClient, and its per-area clients such as ISandboxClient, in the service collection:

services.AddOpenShellClient()
    .WithAddress("https://gateway.example.com")
    .WithBearerToken(Environment.GetEnvironmentVariable("OPENSHELL_TOKEN")!);

// Inject IOpenShellClient (or ISandboxClient, IExecClient, ...) wherever you need it.

Options are validated when the host starts, so a bad address, an unreadable certificate, or a token headed for plaintext HTTP fails at startup instead of on the first call. Configuration binding, named gateways, and health checks are in Dependency injection.

Next

Write your first program.