# LibTmux.Server.CreateOwnedAsync

- **Module:** LibTmux
- **Package:** LibTmux
- **Language:** C#
- **Kind:** method
- **Source:** https://github.com/libtmux/libtmux-dotnet/blob/cf34b255c896d19a97e7d7fabea58609c916012d/src/LibTmux/Server.Lifecycle.cs#L250
- **Page:** https://libtmux.org/en/csharp/latest/reference/libtmux-server-createownedasync/

```
LibTmux.Server.CreateOwnedAsync(options: ServerConnectionOptions?, cancellationToken: CancellationToken) -> Task<OwnedServerScope>
```

Starts a server and takes ownership of it.

The scope holds an endpoint rather than a materialized server, because
a tmux server with no sessions exits at once. <see cref="OwnedServerScope.Value" />
stays that endpoint after a session is created through it; its session,
window, and pane listings and <see cref="CaptureSnapshotAsync(SnapshotDepth, CancellationToken)" />
discover the live server on each call, and the objects they return
carry the discovered handle.

On the default socket, the one a caller gets by naming none, a server
already listening is refused rather than adopted: disposing the scope
stops the server, and on a developer's machine the default socket holds
the one they are using. A named socket or path stays the caller's to
adopt deliberately. The check and the start are two tmux calls, so two
callers that own the default socket at the same moment can both pass
it; give each owned server a socket of its own.

A call that fails or is cancelled after starting a server stops it, since
no scope reaches the caller to do so; a server it found running is left.

## Examples

Distinguish an endpoint handle from a discovered server. Connection discovery returns an immutable replacement without capturing child relations. Use Linux or macOS with Git, tmux 3.2a or newer, .NET SDK 10.0.303, and the .NET 8 and 10 runtimes. In an empty directory, fetch the documented library revision:

```console
$ git clone https://github.com/libtmux/libtmux-dotnet.git libtmux-source && \
  git -C libtmux-source checkout --detach cf34b255c896d19a97e7d7fabea58609c916012d
```

Save this complete consumer setup as global.json:

[Source example](https://github.com/libtmux/libtmux-dotnet/blob/cf34b255c896d19a97e7d7fabea58609c916012d/global.json).

```json
{
  "sdk": {
    "version": "10.0.303",
    "rollForward": "disable",
    "allowPrerelease": false
  },
  "test": {
    "runner": "Microsoft.Testing.Platform"
  }
}
```

Save this complete consumer setup as NuGet.config:

[Source example](https://github.com/libtmux/libtmux-dotnet/blob/cf34b255c896d19a97e7d7fabea58609c916012d/examples/api/NuGet.config).

```xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="libtmux-source" value="libtmux-source/artifacts/api-example-packages" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <clear />
    <packageSource key="libtmux-source">
      <package pattern="LibTmux" />
      <package pattern="LibTmux.*" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>
```

Save this complete consumer setup as Example.csproj:

[Source example](https://github.com/libtmux/libtmux-dotnet/blob/cf34b255c896d19a97e7d7fabea58609c916012d/examples/api/csharp/Example.csproj).

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFrameworks>net8.0;net10.0</TargetFrameworks>
    <LangVersion>12.0</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>disable</ImplicitUsings>
    <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <AnalysisLevel>10-recommended</AnalysisLevel>
  </PropertyGroup>
  <ItemGroup>
    <Compile Include="Program.cs" />
    <PackageReference Include="LibTmux" Version="[0.0.0-alpha.20]" />
  </ItemGroup>
</Project>
```

Save this complete program as Program.cs. It creates a private server; await using disposes its owned scopes after success, cancellation or failure. The complete file contains explicit imports, a top-level async entry point and a cancellation deadline.

[Source example](https://github.com/libtmux/libtmux-dotnet/blob/cf34b255c896d19a97e7d7fabea58609c916012d/examples/LibTmux.Examples/Programs/ServerConstruction.cs).

```csharp
using System;
using System.Threading;
using LibTmux;

if (OperatingSystem.IsWindows())
{
    throw new PlatformNotSupportedException("This example requires tmux on Linux or macOS.");
}

using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10));
CancellationToken token = deadline.Token;
string binary = Environment.GetEnvironmentVariable("LIBTMUX_TMUX") ?? "tmux";
string socketName = "csharp-serverconstruction-" + Guid.NewGuid().ToString("N");
ServerConnectionOptions options = new()
{
    SocketName = socketName,
    ConfigurationFile = "/dev/null",
    TmuxBinaryPath = binary,
};

// Open records the endpoint without running tmux or reading its state.
Server endpoint = Server.Open(options);
if (endpoint.IsMaterialized)
{
    throw new InvalidOperationException("Open must not discover a server.");
}

await using OwnedServerScope owned = await Server.CreateOwnedAsync(options, token);
await using OwnedSessionScope session = await owned.Value.CreateOwnedSessionAsync(
    new NewSessionRequest { Name = "demo", Command = "/bin/cat" }, token);

// Connect discovers the live daemon and returns a new materialized handle.
Server connected = await endpoint.ConnectAsync(token);
Server sameEndpoint = await Server.ConnectAsync(options, token);
if (!connected.IsMaterialized || !sameEndpoint.IsMaterialized || endpoint.IsMaterialized)
{
    throw new InvalidOperationException("Connecting must leave the original handle unchanged.");
}
if (connected.Generation != sameEndpoint.Generation || connected.Sessions.IsCaptured)
{
    throw new InvalidOperationException("Connection discovery must not capture the hierarchy.");
}

Console.WriteLine("Open records an endpoint; Connect discovers the running server.");
Console.WriteLine("The original handle stays unmaterialized; relations remain uncaptured.");
```

Build the exact source package and the saved consumer, then run both supported frameworks. The local package feed prevents an unrelated published package from satisfying the restore. Each program checks its result and exits unsuccessfully after an unhandled error:

```console
$ export NUGET_PACKAGES="$PWD/packages" && \
  dotnet restore libtmux-source/src/LibTmux/LibTmux.csproj --locked-mode && \
  dotnet pack libtmux-source/src/LibTmux/LibTmux.csproj \
    --configuration Release --no-restore -p:ContinuousIntegrationBuild=true \
    --output "$PWD/libtmux-source/artifacts/api-example-packages" && \
  dotnet restore Example.csproj --configfile NuGet.config && \
  dotnet build Example.csproj --configuration Release --no-restore --warnaserror && \
  export LIBTMUX_TMUX="$(command -v tmux)" && \
  export TMUX_TMPDIR=/tmp/libtmux-dotnet-dev && \
  mkdir -p "$TMUX_TMPDIR" && \
  unset TMUX TMUX_PANE && \
  dotnet bin/Release/net8.0/Example.dll && \
  dotnet bin/Release/net10.0/Example.dll
```

Expected program output from each framework:

```text
Open records an endpoint; Connect discovers the running server.
The original handle stays unmaterialized; relations remain uncaptured.
```

## Parameters

- `options` (`ServerConnectionOptions?`): Connection options.
- `cancellationToken` (`CancellationToken`): Cancels the tmux commands.

## Returns

A scope that stops the server when disposed.

## Raises

- [`InvalidOperationException`](https://learn.microsoft.com/dotnet/api/system.invalidoperationexception): A server is already listening on the default socket.
- [`TmuxCommandException`](/en/csharp/latest/reference/libtmux-tmuxcommandexception/): tmux failed to say whether a server is listening, such as on a socket it may not open.