# LibTmux::Server

- **Module:** LibTmux
- **Package:** libtmux
- **Language:** Ruby
- **Kind:** class
- **Source:** https://github.com/libtmux/libtmux-ruby/blob/46474e8a2f03e39fc2b0ff73b6a841777b79c4d2/gems/libtmux/lib/libtmux/terminal.rb#L47
- **Page:** https://libtmux.org/en/ruby/v0.1.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.** Binding an endpoint that already exists takes the
constructor or the open class method, and open with a block closes the
server when the block ends. Given no `endpoint:`, `socket_path:` or
`socket_name:`, both bind the socket {Endpoint#initialize Endpoint.new}
picks from `LIBTMUX_SOCKET_PATH`, `LIBTMUX_SOCKET`, `TMUX` and tmux's
default socket, in that order. Starting a private daemon instead creates no
session, and the started server owns the daemon's exit. A server answers its
{Endpoint} and whether it started its daemon, and reports the request and
control slots in use, and the limits. Closing retires the server's clients;
on an owned server it also stops the daemon. Open a {ControlConnection} to a
session.

- Bind an endpoint: {#initialize Server.new}, {Server.open}
- Start a private daemon: {Server.start}
- Read the endpoint: {#endpoint}
- Ask whether it started the daemon: {#owned?}
- Slots in use and the limits: {#diagnostics}
- Retire the clients: {#close}
- Open a control connection: {#open_control}

**Finding one thing.** Each lookup wraps 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.

- Handles: {#session}, {#window}, {#pane}, {#window_link}

**Listing everything.** Listing sessions, windows, or panes answers frozen
arrays of handles in numeric ID order, and listing window links answers
every {WindowLink}. Listing clients answers one hash per client. Taking a
snapshot captures the session, window, and pane tree, and clients with
`clients: true`, as one validated {Snapshot}.

- Handles: {#list_sessions}, {#list_windows}, {#list_panes}
- Window links: {#list_window_links}
- Clients: {#list_clients}
- One snapshot: {#snapshot}

**Querying things and getting around.** A pane search filters the panes of a
snapshot with `where:`, a hash of criteria or a {FilterExpr}, and answers a
{Selection}; explaining a search answers the plan for a query without
running tmux. A {Selection} narrows, tests whether anything matches, and
takes a single match, raising {NoMatchError} or {MultipleMatchesError}
otherwise, or takes one or nil. Build and compose criteria with
{FilterExpr}. A {Snapshot} answers relational questions without another
command. 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`. A handle reads
back as a record, and a record turns into a handle through its ref and the
server's lookups. Live handles go down one command at a time and back up
through the server.

- Search the panes of a snapshot: {#search_panes}
- Explain a search without running tmux: {#explain_panes}
- Narrow: {Selection#where}, {Selection#select}, {Selection#filter},
  {Selection#reject}
- Test: {Selection#exists?}
- Take one: {Selection#one}
- Take one or nil: {Selection#one_or_nil}
- Build criteria: {FilterExpr.build}, {FilterExpr.from_json}
- Compose criteria: {FilterExpr#and}, {FilterExpr#or}, {FilterExpr#not}
- Read a snapshot's records: {Snapshot#sessions}, {Snapshot#windows},
  {Snapshot#panes}, {Snapshot#clients}
- Read a handle back as a record: {Entity#snapshot}
- Turn a record into a handle: {CapturedRecord#ref}, {#session}, {#window},
  {#pane}
- Down: {Session#list_windows}, {Session#list_panes}, {Window#list_panes}
- Up: {Entity#server}

**Changing things.** Creating a session starts it detached, 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 closing does only for an owned server. Switching a client
points the client named by `client:` at a session.

- Create a session: {#new_session}
- Stop the tmux server: {#kill}
- Point a client at a session: {#switch_client}

**Options and hooks.** Ask for {Options} at server scope, or at the global
session or window scope, and for {Hooks} at the global session or window
scope. Read, set, and unset one variable in the server's global environment.

- Options: {#options}
- Hooks: {#hooks}
- Read a variable: {#environment}
- Set a variable: {#set_environment}
- Unset a variable: {#unset_environment}

**Everything else tmux keeps.** List, read, write, and delete paste buffers.
Load a configuration file. Display expands a tmux format; the argument is a
format, not literal text. Wait on, signal, lock, or unlock a channel, as
`action:` says.

- Paste buffers: {#list_buffers}, {#read_buffer}, {#write_buffer},
  {#delete_buffer}
- Load a configuration file: {#source_file}
- Expand a format: {#display}
- Wait on a channel: {#wait_for}

**Things that need a terminal.** Attaching 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.

- Attach a client: {#attach}

**Running a command.** Anything else tmux can do is reachable by running one
command, which takes an argv array and keeps tmux's separators and format
semantics, or by running several in one tmux invocation. A {GroupResult}
cannot attribute the client's final status to a single step.

- Run one command: {#run}
- Run several in one invocation: {#run_group}

## 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 3.3 or newer with Bundler, and tmux 3.3a or newer, on Unix with `/bin/cat` and `/bin/sh` available. In an empty directory, save this `Gemfile`:

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

gem "libtmux", "0.1.2"
```

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/46474e8a2f03e39fc2b0ff73b6a841777b79c4d2/examples/api/server.rb).

```ruby
# frozen_string_literal: true

begin
  # docs:begin main
  require "libtmux"

  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
  # docs:end main
rescue StandardError => error
  warn "#{error.class}: #{error.message}"
  exit 1
end
```

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

```console
$ bundle install && \
  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.2/reference/libtmux-server-list_sessions/) (method): Behavior: Live acquisition.
- [`list_windows`](/en/ruby/v0.1.2/reference/libtmux-server-list_windows/) (method): Behavior: Live acquisition.
- [`list_panes`](/en/ruby/v0.1.2/reference/libtmux-server-list_panes/) (method): Behavior: Live acquisition.
- [`list_clients`](/en/ruby/v0.1.2/reference/libtmux-server-list_clients/) (method): Behavior: Live acquisition.
- [`list_buffers`](/en/ruby/v0.1.2/reference/libtmux-server-list_buffers/) (method): Behavior: Buffers.
- [`snapshot`](/en/ruby/v0.1.2/reference/libtmux-server-snapshot/) (method): Behavior: Snapshot acquisition.
- [`search_panes`](/en/ruby/v0.1.2/reference/libtmux-server-search_panes/) (method): Behavior: Source query execution.

### Common operations

- [`new_session`](/en/ruby/v0.1.2/reference/libtmux-server-new_session/) (method): Behavior: Creation.
- [`kill`](/en/ruby/v0.1.2/reference/libtmux-server-kill/) (method): Behavior: Killing daemons.
- [`source_file`](/en/ruby/v0.1.2/reference/libtmux-server-source_file/) (method): Behavior: Source files.
- [`options`](/en/ruby/v0.1.2/reference/libtmux-server-options/) (method): Behavior: Options and hooks.
- [`hooks`](/en/ruby/v0.1.2/reference/libtmux-server-hooks/) (method): Behavior: Options and hooks.
- [`write_buffer`](/en/ruby/v0.1.2/reference/libtmux-server-write_buffer/) (method): Behavior: Buffers.
- [`environment`](/en/ruby/v0.1.2/reference/libtmux-server-environment/) (method): Behavior: Environment.
- [`read_buffer`](/en/ruby/v0.1.2/reference/libtmux-server-read_buffer/) (method): Behavior: Buffers.
- [`delete_buffer`](/en/ruby/v0.1.2/reference/libtmux-server-delete_buffer/) (method): Behavior: Buffers.
- [`run`](/en/ruby/v0.1.2/reference/libtmux-server-run/) (method): Raw tmux arguments retain tmux's separators and format semantics.
- [`set_environment`](/en/ruby/v0.1.2/reference/libtmux-server-set_environment/) (method): Behavior: Environment.
- [`unset_environment`](/en/ruby/v0.1.2/reference/libtmux-server-unset_environment/) (method): Behavior: Environment.
- [`wait_for`](/en/ruby/v0.1.2/reference/libtmux-server-wait_for/) (method): Retiring the client cannot remove a dispatched waiter from tmux's queue.
- [`session`](/en/ruby/v0.1.2/reference/libtmux-server-session/) (method): Behavior: Live handles.
- [`window`](/en/ruby/v0.1.2/reference/libtmux-server-window/) (method): Behavior: Live handles.
- [`pane`](/en/ruby/v0.1.2/reference/libtmux-server-pane/) (method): Behavior: Live handles.
- [`start`](/en/ruby/v0.1.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.2/reference/libtmux-server-new/) (method): Behavior: Borrowed bindings.
- [`run_group`](/en/ruby/v0.1.2/reference/libtmux-server-run_group/) (method): One nontransactional tmux command group, with literal arguments per command.

### Other members

- [`attach`](/en/ruby/v0.1.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.2/reference/libtmux-server-close/) (method): Behavior: Closing bindings.
- [`diagnostics`](/en/ruby/v0.1.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.2/reference/libtmux-server-display/) (method): Formats are intentionally executable tmux formats, not literal text.
- [`endpoint`](/en/ruby/v0.1.2/reference/libtmux-server-endpoint/) (method): Returns the value of attribute endpoint.
- [`explain_panes`](/en/ruby/v0.1.2/reference/libtmux-server-explain_panes/) (method): Behavior: Source query plans.
- [`list_window_links`](/en/ruby/v0.1.2/reference/libtmux-server-list_window_links/) (method): Behavior: Live acquisition.
- [`open`](/en/ruby/v0.1.2/reference/libtmux-server-open/) (method): Behavior: Borrowed bindings.
- [`open_control`](/en/ruby/v0.1.2/reference/libtmux-server-open_control/) (method): Behavior: Control connections.
- [`owned?`](/en/ruby/v0.1.2/reference/libtmux-server-owned/) (method): Behavior: Borrowed bindings.
- [`supports_control?`](/en/ruby/v0.1.2/reference/libtmux-server-supports_control/) (method): True when the checked daemon accepts control clients (tmux 3.7 and newer).
- [`switch_client`](/en/ruby/v0.1.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.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.2/reference/libtmux-server-window_link/) (method): Behavior: Live handles.

## In other ports

A tmux server

| Language | Equivalent |
| --- | --- |
| Python | [`libtmux.Server`](/en/py/latest/reference/libtmux-server/) (class) |
| Lua | [`libtmux.Server`](/en/lua/latest/reference/libtmux-server/) (class) |
| 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`. |
| Elixir | [`LibTmux.Server`](/en/elixir/latest/reference/libtmux-server/) (struct). `Server` describes an existing server by executable and socket. It neither connects nor reserves the server’s identity. |
| 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`](/en/java/latest/reference/io-github-libtmux-server-server/) (class) |
| 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) |
| C# | [`LibTmux.Server`](/en/csharp/latest/reference/libtmux-server/) (class) |
| F# | [`LibTmux.FSharp.Server`](/en/fsharp/latest/reference/libtmux-fsharp-server/) (module). This F# module provides functions over the shared .NET `LibTmux.Server` type. |
| C++ | [`libtmux::Server`](/en/cxx/latest/reference/libtmux-server/) (class) |
| Swift | [`Server`](/en/swift/latest/reference/server/) (struct) |