# io.github.libtmux.kotlin.Server

- **Module:** io.github.libtmux.kotlin
- **Package:** io.github.libtmux:libtmux-kotlin
- **Language:** Kotlin
- **Kind:** class
- **Source:** https://github.com/libtmux/libtmux-java/blob/f56392b5d9bc7f1f9c1631842333fb90f3d82d40/libtmux-kotlin/src/main/kotlin/io/github/libtmux/kotlin/Server.kt#L32
- **Page:** https://libtmux.org/en/kotlin/latest/reference/io-github-libtmux-kotlin-server/

```
public class Server  : AutoCloseable
```

Manages sessions, windows, and panes on a tmux server.

Use [open] with a [ServerConfig] to select a server by socket name or path. From this object,
create sessions or query the server's existing sessions, windows, and panes. Each [Session]
contains windows, and each [Window] contains panes.

Operations that contact tmux are `suspend` functions dispatched through [policy]. Call [close]
after the last operation to release resources owned by this object. The tmux server and its
sessions keep running.

[asJava] exposes the underlying [JavaServer] for interoperability. Both objects share the same
resources, so closing either closes both.

## Examples

Connect to a private tmux server. Use JDK 25, Git, and tmux 3.2a through 3.7c on Linux, with /bin/cat and /bin/sh available. In an empty directory, fetch the documented library revision:

```console
$ git clone https://github.com/libtmux/libtmux-java.git libtmux-source && \
  git -C libtmux-source checkout f56392b5d9bc7f1f9c1631842333fb90f3d82d40
```

Save this consumer setup as settings.gradle.kts:

[Source example](https://github.com/libtmux/libtmux-java/blob/f56392b5d9bc7f1f9c1631842333fb90f3d82d40/examples/api/kotlin/settings.gradle.kts).

```kotlin
rootProject.name = "api-example"

includeBuild("libtmux-source")
```

Save this consumer setup as build.gradle.kts:

[Source example](https://github.com/libtmux/libtmux-java/blob/f56392b5d9bc7f1f9c1631842333fb90f3d82d40/examples/api/kotlin/build.gradle.kts).

```kotlin
plugins {
    kotlin("jvm") version "2.4.10"
    application
}

repositories { mavenCentral() }

dependencies {
    implementation("io.github.libtmux:libtmux-kotlin:0.0.1-alpha.17-SNAPSHOT")
}

java { toolchain { languageVersion.set(JavaLanguageVersion.of(25)) } }
kotlin { jvmToolchain(25) }

application { mainClass.set(providers.gradleProperty("exampleMain")) }
```

Save this consumer setup as gradle.properties:

[Source example](https://github.com/libtmux/libtmux-java/blob/f56392b5d9bc7f1f9c1631842333fb90f3d82d40/examples/api/gradle.properties).

```properties
org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=768m -Dfile.encoding=UTF-8
kotlin.daemon.jvmargs=-Xmx2g
org.gradle.workers.max=2
```

Save this launcher as run.sh. It creates and stops a private tmux server, including after program failure. A shutdown failure retains its socket directory and exits unsuccessfully.

[Source example](https://github.com/libtmux/libtmux-java/blob/f56392b5d9bc7f1f9c1631842333fb90f3d82d40/examples/api/run.sh).

```sh
#!/bin/sh
set -eu

if [ "$#" -eq 0 ]; then
    printf 'Usage: sh run.sh program [arguments...]\n' >&2
    exit 2
fi
binary=$(command -v "${TMUX_BIN:-tmux}")
mkdir -p /tmp/libtmux-java-dev
directory=$(mktemp -d /tmp/libtmux-java-dev/api.XXXXXX)
socket="$directory/tmux.sock"
config="$directory/tmux.conf"

alive() {
    "$binary" -S "$socket" display-message -p '#{pid}' >/dev/null 2>&1
}

cleanup() {
    status=$?
    trap - 0 HUP INT TERM
    if alive; then
        if ! "$binary" -S "$socket" kill-server; then
            printf 'Cannot stop tmux; kept %s\n' "$directory" >&2
            exit 1
        fi
        attempts=0
        while alive && [ "$attempts" -lt 100 ]; do
            sleep 0.05
            attempts=$((attempts + 1))
        done
        if alive; then
            printf 'tmux is still responding; kept %s\n' "$directory" >&2
            exit 1
        fi
    fi
    rm -rf "$directory" || exit 1
    exit "$status"
}
trap cleanup 0
trap 'exit 1' HUP INT TERM

unset TMUX TMUX_PANE
printf 'set-option -g default-shell /bin/sh\n' > "$config"
"$binary" -S "$socket" -f "$config" new-session -d -s work-one -n editor /bin/cat
"$binary" -S "$socket" split-window -h -t '=work-one:editor' /bin/cat
"$binary" -S "$socket" new-window -d -t '=work-one' -n logs /bin/cat
"$binary" -S "$socket" new-session -d -s work-two -n editor /bin/cat
"$@" "$binary" "$socket" "$config"
"$binary" -S "$socket" has-session -t '=work-one'
"$binary" -S "$socket" has-session -t '=work-two'
```

Save this complete program as src/main/kotlin/Connect.kt. It opens an ordinary client for the launcher's server; closing the client releases its transport.

[Source example](https://github.com/libtmux/libtmux-java/blob/f56392b5d9bc7f1f9c1631842333fb90f3d82d40/examples/src/main/kotlin/io/github/libtmux/examples/api/kotlin/Connect.kt).

```kotlin
package io.github.libtmux.examples.api.kotlin

import io.github.libtmux.ServerConfig
import io.github.libtmux.ServerEndpoint
import io.github.libtmux.kotlin.*
import java.nio.file.Path
import kotlin.system.exitProcess
import kotlinx.coroutines.runBlocking

/** Connect to a private tmux server. */
fun main(args: Array<String>) {
    try {
        require(args.size == 3) { "expected: tmux-binary socket-path config-file" }
        val config = ServerConfig.builder()
            .binary(args[0])
            .endpoint(ServerEndpoint.socketPath(Path.of(args[1])))
            .configFile(Path.of(args[2]))
            .build()
        runBlocking {
            withServer(config) { server ->
                println("connected=${server.isAlive()}")
            }
        }
    } catch (error: Exception) {
        if (error is InterruptedException) Thread.currentThread().interrupt()
        System.err.println("Example failed: ${error.message}")
        exitProcess(1)
    }
}
```

Build the minimal consumer and run the saved program with the private fixture. An operation or cleanup error makes the command exit unsuccessfully:

```console
$ ./libtmux-source/gradlew --project-dir . --console=plain --quiet \
    installDist -PexampleMain=io.github.libtmux.examples.api.kotlin.ConnectKt && \
  sh run.sh build/install/api-example/bin/api-example
```

Expected output:

```text
connected=true
```

## Members

### Collections and queries

- `sessions` (method): Every session, captured now.
- `windows` (method): Captures every winlink, preserving each session and index placement.
- `panes` (method): Captures every pane on the server.
- `clients` (method): Captures every attached client.
- `buffers` (method): The server's paste buffers, which every session shares.
- `snapshot` (method): Captures the whole hierarchy in at most four listings, retrying once if the server is replaced.

### Common operations

- `newSession` (method): Creates a detached session and returns that exact session.
- `killServer` (method): Ends the tmux server and every session on it.
- `hooks` (method): The global hooks every session inherits.
- `keys` (method): The server's key bindings: `prefix` when binding, every table when listing.
- `liveState` (method): A live, continuously rebuilt view of [server], as a [StateFlow].
- `batch` (method): Collects several commands to run in one tmux invocation.
- `chain` (method): Starts a chain of commands where each one acts on what the last one made.
- `commands` (method): The commands this tmux knows.
- `messageLog` (method): The server's message log.
- `prompt` (method): The command prompt's history.
- `session` (method): The one session this expression matches, captured now.
- `sessionOrNull` (method): The one session this expression matches, or null when none does.
- `shell` (method): Shell commands run by tmux, and tmux commands chosen by a shell exit status.
- `withLiveState` (method): As [liveState], scoped to [block]: opens the live view, runs [block] against it, and cancels the background pump before returning — the same `withServer`/`withControl` shape, for the one resource [liveState] itself cannot close on its own.

### Other members

- `admissionBound` (property): How many tmux commands this server's transport runs at once, from [ExecutionPolicy.default].
- `asJava` (property): The Java server this wraps, for an operation this class does not mirror or a Java API that takes one. The same object, not a copy: closing either closes both.
- `attachedSessions` (method): Captures every session a client is attached to.
- `channel` (method): One of this server's wait-for channels, which is where a signal is sent and waited for.
- `close` (method): Releases an owned transport. Idempotent, and never kills tmux.
- `cmd` (method): Runs one tmux command against this server.
- `Companion` (module)
- `config` (property): How this server was configured.
- `control` (method): Attaches a control client to this session's server, and only to the process this capture named.
- `environment` (method): The server's environment, which every session inherits and every new process is given.
- `expand` (method): Expands a tmux format against the server, and answers with what it came to.
- `globalOptions` (method): The global session options every session inherits unless it sets its own.
- `hasSession` (method): Whether a session with this name exists.
- `identity` (property): Which server this is. Every handle taken from it is scoped by this.
- `isAlive` (method): Whether the server is running and answering.
- `killSession` (method): Ends the session with this name, and everything in it.
- `lock` (method): Locks every client attached to this server.
- `options` (method): The server-wide options, the ones tmux keeps once per server.
- `pane` (method): The one pane this expression matches, captured now.
- `paneFields` (method): Chosen fields for every pane on the server, from one listing.
- `paneOrNull` (method): The one pane this expression matches, or null when none does.
- `policy` (property)
- `requireAlive` (method): Requires a running tmux daemon that answers the liveness probe.
- `run` (method): Runs a command that is expected to work, and raises when it did not.
- `sourceFile` (method): Runs a file of tmux commands, as a configuration file would be run.
- `variables` (method): Reads only validated tmux variable names, never caller-authored format syntax.
- `version` (method): Which tmux this server is running.
- `window` (method): The one window link this expression matches, captured now.
- `windowOrNull` (method): The one window link this expression matches, or null when none does.