# LibTmux::Server

- **Module:** LibTmux
- **Package:** libtmux
- **Language:** Ruby
- **Kind:** class
- **Source:** https://github.com/libtmux/libtmux-ruby/blob/dcc9f8b5a6970144a9e7d80cd5f381d8f6198372/gems/libtmux/lib/libtmux/terminal.rb#L47
- **Page:** https://libtmux.org/en/ruby/v0.1.0.alpha.2/reference/libtmux-server/

Connects to an existing endpoint. Closing retires clients, never the daemon.

A server is bound to one tmux executable and one Unix socket. It keeps a
private link to the socket it bound, so commands never reach a different
daemon that later takes over the same path. An {EntityRef} is valid only on
the server that issued it; another server raises {TargetNotFoundError}.

Methods that run a tmux command take `timeout:` and `cancel:`. The typed
methods raise {CommandError} when tmux rejects a command, and a listing
that fails raises, so an empty array means tmux answered with nothing to
list. {#run} and {#run_group} answer their result whatever tmux's exit
status. `max_requests:` bounds concurrent commands and `max_controls:`
bounds control connections; a call past either limit raises
{CapacityError} instead of waiting. After {#close} the server refuses new
requests with {ClosedError}, and {#diagnostics} still answers. A forked
child can close an inherited server but cannot use it.

# What is on here

The methods fall into the groups below. A {Session}, {Window}, or {Pane}
carries the operations on that one thing.

**Connecting.** {#initialize Server.new} and {Server.open} bind an endpoint
that already exists; {Server.open} with a block closes the server when the
block ends. {Server.start} starts a private daemon instead, creates no
session, and owns the daemon's exit. {#endpoint} answers the {Endpoint}
and {#owned?} says whether this server started its daemon. {#diagnostics}
reports the request and control slots in use, and the limits. {#close}
retires the server's clients; on an owned server it also stops the daemon.
{#open_control} opens a {ControlConnection} to a session.

**Finding one thing.** {#session}, {#window}, {#pane}, and {#window_link}
wrap an {EntityRef} in a handle without running a command. Take the ref
from a handle or a snapshot record. A ref of the wrong kind raises
{TargetNotFoundError}; one whose entity has gone fails at its first
command.

**Listing everything.** {#list_sessions}, {#list_windows}, and
{#list_panes} answer frozen arrays of handles in numeric ID order, and
{#list_window_links} answers every {WindowLink}. {#list_clients} answers
one hash per client. {#snapshot} captures the session, window, and pane
tree, and clients with `clients: true`, as one validated {Snapshot}.

**Querying things and getting around.** {#search_panes} filters the panes
of a snapshot with `where:`, a hash of criteria or a {FilterExpr}, and
answers a {Selection}; {#explain_panes} answers the plan for a query
without running tmux. A {Selection} narrows with {Selection#where},
{Selection#select}, {Selection#filter}, and {Selection#reject}, tests with
{Selection#exists?}, and takes a single match with {Selection#one}, which
raises {NoMatchError} or {MultipleMatchesError} otherwise, or
{Selection#one_or_nil}. Build and compose criteria with
{FilterExpr.build}, {FilterExpr#and}, {FilterExpr#or}, {FilterExpr#not},
and {FilterExpr.from_json}.

A {Snapshot} answers relational questions without another command:
{Snapshot#sessions}, {Snapshot#windows}, {Snapshot#panes}, and
{Snapshot#clients}. Its records follow relations by name: a
{SessionSnapshot} reaches `windows`, `panes`, and `current_window`, a
{WindowSnapshot} reaches `panes` and `active_pane`, and a {PaneSnapshot}
reaches its `window`. {Entity#snapshot} reads one handle back as a record,
and {CapturedRecord#ref} with {#session}, {#window}, or {#pane} turns a
record into a handle. Live handles go down one command at a time with
{Session#list_windows}, {Session#list_panes}, and {Window#list_panes}, and
back up with {Entity#server}.

**Changing things.** {#new_session} starts a detached session running
`command:`, an argv array rather than a shell string, and answers the
{Session} or, with `receipt: true`, a {CreationReceipt}. {#kill} stops the
tmux server, which {#close} does only for an owned server.
{#switch_client} points the client named by `client:` at a session.

**Options and hooks.** {#options} answers {Options} at server scope, or at
the global session or window scope. {#hooks} answers {Hooks} at the global
session or window scope. {#environment}, {#set_environment}, and
{#unset_environment} read, set, and unset one variable in the server's
global environment.

**Everything else tmux keeps.** Paste buffers: {#list_buffers},
{#read_buffer}, {#write_buffer}, and {#delete_buffer}. {#source_file}
loads a configuration file. {#display} expands a tmux format; the argument
is a format, not literal text. {#wait_for} waits on, signals, locks, or
unlocks a channel, as `action:` says.

**Things that need a terminal.** {#attach} runs an interactive client on a
TTY the caller supplies and keeps, blocks until that client exits, and
answers a {TerminalResult}. Cancelling detaches the client and does not
stop pane commands.

Anything else tmux can do is reachable through {#run}, which runs one
command from an argv array and keeps tmux's separators and format
semantics, or {#run_group}, which runs several in one tmux invocation. A
{GroupResult} cannot attribute the client's final status to a single step.

## Examples

Connect a Server client to an existing endpoint and close it without stopping the daemon. The outer Server.start block owns the private demonstration server. Use Ruby 4.0.7, Bundler, Git and tmux 3.2a or newer on Unix, with /bin/cat and /bin/sh available. In an empty directory, fetch the documented library revision:

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

Save this dependency file as Gemfile:

```ruby
source "https://rubygems.org"

gem "libtmux", path: "libtmux-source/gems/libtmux"
```

Save this complete program as server.rb. Its Server.start block owns a private tmux server and stops it on exit, including after an error.

[Source example](https://github.com/libtmux/libtmux-ruby/blob/dcc9f8b5a6970144a9e7d80cd5f381d8f6198372/examples/api/server.rb).

```ruby
# frozen_string_literal: true

require "libtmux"

begin
  LibTmux::Server.start do |owner|
    owner.new_session(name: "work", command: ["/bin/cat"])
    server = LibTmux::Server.new(endpoint: owner.endpoint)
    begin
      puts "connected sessions: #{server.list_sessions.length}"
    ensure
      server.close
    end
    puts "sessions after client close: #{owner.list_sessions.length}"
  end
rescue StandardError => error
  warn "#{error.class}: #{error.message}"
  exit 1
end
```

Install the runtime dependencies and run the saved program. An operation or cleanup error makes it exit unsuccessfully:

```console
$ bundle config set --local path vendor/bundle && \
  bundle install --jobs 2 && \
  bundle exec ruby server.rb
```

Expected output:

```text
connected sessions: 1
sessions after client close: 1
```

## Members

### Collections and queries

- [`list_sessions`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-list_sessions/) (method): Behavior: Live acquisition.
- [`list_windows`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-list_windows/) (method): Behavior: Live acquisition.
- [`list_panes`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-list_panes/) (method): Behavior: Live acquisition.
- [`list_clients`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-list_clients/) (method): Behavior: Live acquisition.
- [`list_buffers`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-list_buffers/) (method): Behavior: Buffers.
- [`snapshot`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-snapshot/) (method): Behavior: Snapshot acquisition.
- [`search_panes`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-search_panes/) (method): Behavior: Source query execution.

### Common operations

- [`new_session`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-new_session/) (method): Behavior: Creation.
- [`kill`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-kill/) (method): Behavior: Killing daemons.
- [`source_file`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-source_file/) (method): Behavior: Source files.
- [`options`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-options/) (method): Behavior: Options and hooks.
- [`hooks`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-hooks/) (method): Behavior: Options and hooks.
- [`write_buffer`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-write_buffer/) (method): Behavior: Buffers.
- [`environment`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-environment/) (method): Behavior: Environment.
- [`read_buffer`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-read_buffer/) (method): Behavior: Buffers.
- [`delete_buffer`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-delete_buffer/) (method): Behavior: Buffers.
- [`run`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-run/) (method): Raw tmux arguments retain tmux's separators and format semantics.
- [`set_environment`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-set_environment/) (method): Behavior: Environment.
- [`unset_environment`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-unset_environment/) (method): Behavior: Environment.
- [`wait_for`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-wait_for/) (method): Retiring the client cannot remove a dispatched waiter from tmux's queue.
- [`session`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-session/) (method): Behavior: Live handles.
- [`window`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-window/) (method): Behavior: Live handles.
- [`pane`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-pane/) (method): Behavior: Live handles.
- [`open`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-open/) (method): Behavior: Borrowed bindings.
- [`start`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-start/) (method): Starts a foreground daemon on a new private endpoint. Close owns its exit.
No session is created; the default config is empty. Startup blocks.
- [`new`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-new/) (method): Behavior: Borrowed bindings.

### Other members

- [`attach`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-attach/) (method): Blocks until the owned interactive client exits. The caller supplies and
retains its TTY. Cancellation detaches this client, not pane commands.
- [`close`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-close/) (method): Behavior: Closing bindings.
- [`diagnostics`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-diagnostics/) (method): Returns a frozen local snapshot, including after close. Slots are admitted
requests; control connections are retained registrations, not OS clients.
- [`display`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-display/) (method): Formats are intentionally executable tmux formats, not literal text.
- [`endpoint`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-endpoint/) (method): Returns the value of attribute endpoint.
- [`explain_panes`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-explain_panes/) (method): Behavior: Source query plans.
- [`list_window_links`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-list_window_links/) (method): Behavior: Live acquisition.
- [`open_control`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-open_control/) (method): Behavior: Control connections.
- [`owned?`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-owned/) (method): Behavior: Borrowed bindings.
- [`run_group`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-run_group/) (method): One nontransactional tmux command group, with literal arguments per command.
- [`switch_client`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-switch_client/) (method): Resolves the literal selector at dispatch; it is not a client reference.
- [`tmux_version`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-tmux_version/) (method): The daemon's release text, such as "3.7d" or "next-3.9".
- [`window_link`](/en/ruby/v0.1.0.alpha.2/reference/libtmux-server-window_link/) (method): Behavior: Live handles.

## In other ports

### A tmux server

- PowerShell: [`LibTmux\New-TmuxServer`](/en/powershell/latest/reference/libtmux-new-tmuxserver/) (cmdlet). This cmdlet constructs a shared .NET `LibTmux.Server` handle without contacting tmux.
- Julia: [`LibTmux.Server`](/en/julia/latest/reference/libtmux-server/) (struct). `Server` describes an endpoint without contacting tmux. Read its hierarchy with `snapshot`.
- Python: [`libtmux.Server`](/en/py/latest/reference/libtmux-server/) (class)
- Lua: [`libtmux.Server`](/en/lua/latest/reference/libtmux-server/) (class)
- TypeScript: [`server.Server`](/en/ts/latest/reference/server-server/) (class)
- Rust: [`server.Server`](/en/rs/latest/reference/server-server/) (struct)
- Go: [`tmux.Server`](/en/go/latest/reference/tmux-server/) (struct)
- Java: [`io.github.libtmux.Server.Server`](/en/java/latest/reference/io-github-libtmux-server-server/) (class)
- C#: [`LibTmux.Server`](/en/csharp/latest/reference/libtmux-server/) (class)
- C++: [`libtmux::Server`](/en/cxx/latest/reference/libtmux-server/) (class)
- Swift: [`Server`](/en/swift/latest/reference/server/) (struct)
- Kotlin: [`io.github.libtmux.kotlin.Server`](/en/kotlin/latest/reference/io-github-libtmux-kotlin-server/) (class)
- Scala: [`io.github.libtmux.scaladsl.Server`](/en/scala/latest/reference/io-github-libtmux-scaladsl-server/) (typealias)
- F#: [`LibTmux.FSharp.Server`](/en/fsharp/latest/reference/libtmux-fsharp-server/) (module). This F# module provides functions over the shared .NET `LibTmux.Server` type.