# tmux_server

- **Package:** libtmux_erlang
- **Language:** Erlang
- **Kind:** module
- **Source:** https://github.com/libtmux/libtmux-erlang/blob/d1b6308440cf9eb8f6647e7ae434bce60e849368/apps/libtmux_erlang/src/tmux_server.erl#L1
- **Page:** https://libtmux.org/en/erlang/latest/reference/tmux_server/

Open tmux endpoints and execute explicit command values.

`open/1` validates an absolute socket path and the
executable/server versions. It never creates a tmux server or attaches a
control client. Each command rechecks the observed Linux process incarnation
before dispatch. Replacement between that observation and a later client
connection remains possible; same_connection requests are rejected until
persistent dispatch qualifies.

`start_owned/1` creates a separate private daemon and returns an ownership
token for `stop_owned/1`. The [ownership guide](ownership.md) explains caller
death, application shutdown and namespace cleanup.

Use `with_server/2` or `with_owned/2` for a callback scope. They attempt cleanup
after its return or exception and preserve both outcomes if cleanup fails.

The calling process owns the endpoint. `close/1` cancels queued
work, retires its one-shot clients and preserves the borrowed server. Cleanup
failure remains explicit and keeps the supervised owner alive. Successful close is
idempotent during the 60-second handle retention period. Separate
`m:tmux_control` attachments receive an invalidation notice and begin their
own retirement. Close those attachments explicitly to prove their native
cleanup. Command results preserve stdout, stderr and status; cancellation
after dispatch cannot undo
remote effects. Clients explicitly select tmux's UTF-8 mode so Unicode and the
identity probe's tab do not depend on the caller's locale. Command-specific
escaping still applies to raw command output.

Use `snapshot/1` to capture a graph for `m:tmux_snapshot` and
`m:tmux_select`. Use `m:tmux_operation` for non-blocking submission and
explicit waits; the [job guide](jobs.md) explains ownership and cleanup.

## Members

### Collections and queries

- [`snapshot/1`](/en/erlang/latest/reference/tmux_server-snapshot-1/) (function): Capture a complete immutable graph with default capture limits. Performs I/O. See `snapshot/2` for bounds, consistency and conflict errors.

### Common operations

- [`stop_owned/1`](/en/erlang/latest/reference/tmux_server-stop_owned-1/) (function): Stop the daemon and endpoint associated with a `t:ownership/0` token. Performs I/O and returns ok only after endpoint/client/helper retirement and namespace cleanup are proved. It never sends kill-server to a socket path.
- [`command/3`](/en/erlang/latest/reference/tmux_server-command-3/) (function): Execute one validated command and await its result. Performs I/O. The result preserves stdout, stderr, exit status and cleanup certainty. Use `tmux_operation:start/3` to submit without blocking this caller. A timeout or cancellation cannot reverse effects that may already have reached tmux. Values from domain command builders keep their captured endpoint origin. Another endpoint returns different_owner with submitted = false before any native preflight or execution. Raw commands do not carry that origin.
- [`version/1`](/en/erlang/latest/reference/tmux_server-version-1/) (function): Return the daemon version observed when the endpoint opened. This reads owner state and does not execute a fresh version command or qualify another tmux release.
- [`start_owned/1`](/en/erlang/latest/reference/tmux_server-start_owned-1/) (function): Start an empty owned daemon in a fresh private Linux socket directory. Performs I/O and waits for bounded startup; no session or attached observer is created. Returns an ordinary endpoint and a separate `t:ownership/0` token. The caller owns the daemon lifetime: caller death or `stop_owned/1` retires its helper tree. `close/1` only closes the endpoint and preserves the daemon.
- [`bind/2`](/en/erlang/latest/reference/tmux_server-bind-2/) (function): Explicitly read current fields from this server and register the new value. For sessions, physical windows and panes, the read uses the stable ID and discards the supplied field observations. This explicit call accepts an edited target; ordinary actions require its captured target association to match and reject mismatches before dispatch. The returned row carries a new private observation association; see `m:tmux_model`. It provides no atomic identity check. Window-link binding checks its session/index and expected physical window. A replaced or missing membership returns stale_link. This observed preflight does not make a later action atomic.
- [`with_owned/2`](/en/erlang/latest/reference/tmux_server-with_owned-2/) (function): Start an owned daemon, run a callback in the calling process, then stop it. Performs `start_owned/1` and token-based `stop_owned/1` around the callback. With successful cleanup, returns {ok, Value} or re-raises the original callback exception. A returned error tuple is an ordinary callback value. Startup failure passes through without invoking the callback.
- [`close/1`](/en/erlang/latest/reference/tmux_server-close-1/) (function): Retire this endpoint's operations and one-shot clients, preserving the borrowed tmux server. Returns ok only after their cleanup completes; incomplete cleanup remains an explicit error. Closing an already closed retained handle is idempotent. The initiator controls endpoint lifetime. Separate control attachments are invalidated and asked to retire; use `tmux_control:close/1` before this call to verify those clients' cleanup too.
- [`with_server/2`](/en/erlang/latest/reference/tmux_server-with_server-2/) (function): Open a borrowed endpoint, run a callback in the calling process, then close it. Performs the same I/O as `open/1` and `close/1`; the borrowed daemon survives. Startup failure passes through without invoking the callback.
- [`open/1`](/en/erlang/latest/reference/tmux_server-open-1/) (function): Open a borrowed socket endpoint and start its supervised library owner. The caller owns that handle. This probes the executable, daemon version and observed Linux process incarnation; it never starts a tmux server or attaches a control client. Pass an absolute socket_path and optionally an executable.
- [`scope_failure/0`](/en/erlang/latest/reference/t-tmux_server-scope_failure-0/) (typealias): Both callback and cleanup evidence when a scope cannot prove retirement. primary is the callback value or its exception class, reason and original stack. cleanup preserves the operational error or a separate cleanup exception. server permits `close/1` reconciliation; owned scopes also include ownership for `stop_owned/1`. Retain these handles until cleanup is resolved.
- [`snapshot/2`](/en/erlang/latest/reference/tmux_server-snapshot-2/) (function): Capture the server's sessions, physical windows, window links and panes.

### Other members

- [`capture_options/0`](/en/erlang/latest/reference/t-tmux_server-capture_options-0/) (typealias): Capture bounds, hydration strategy and consistency request. Atomic capture is unsupported.
- [`command_options/0`](/en/erlang/latest/reference/t-tmux_server-command_options-0/) (typealias): Command options: deadline_ms defaults to 2500, max_stdout to 1 MiB, max_stderr to 64 KiB, stdin to an empty binary and identity to observed. The deadline includes admission, preflight and execution. stdin is limited to 256 KiB; stdin plus the rendered argument reservation must also fit 256 KiB. Each endpoint admits at most 64 operations and 256 KiB of command payload; exhaustion returns busy. same_connection is recognized but unsupported.
- [`hydration/0`](/en/erlang/latest/reference/t-tmux_server-hydration-0/) (typealias): Capture text/bytes with one framed scan per entity (batched, the default), or one field per physical row (isolated). Both retain complete graph coverage and interval semantics. Each command has the same 1 MiB stdout bound; isolated can distribute large entity output across commands at greater source cost. See `snapshot/2` and `tmux_query:explain/1`.
- [`open_options/0`](/en/erlang/latest/reference/t-tmux_server-open_options-0/) (typealias): An explicit absolute socket endpoint and optional absolute tmux executable path.
- [`origin/1`](/en/erlang/latest/reference/tmux_server-origin-1/) (function): Return the registered opaque origin for this open endpoint. The token provides library provenance and generation checks, not authorization against trusted Erlang code. It is not a portable identifier.
- [`owned_options/0`](/en/erlang/latest/reference/t-tmux_server-owned_options-0/) (typealias): Owned startup options. The finite startup budget defaults to 2500 milliseconds.
- [`ownership/0`](/en/erlang/latest/reference/t-tmux_server-ownership-0/) (typealias): Opaque ownership token for `stop_owned/1`. An ordinary endpoint or row origin does not convey this token. Trusted code can pass it to another process.
- [`state/0`](/en/erlang/latest/reference/t-tmux_server-state-0/) (typealias): Endpoint resource summary. owner is the supervised endpoint process, not its initiating caller. operations and command_bytes count active admission leases; active_bytes reserves output capacity. Retired results are bounded separately by retained_results and result_bytes. These are accounting limits, not VM heap measurements. generation identifies this endpoint handle's lifetime.
- [`status/1`](/en/erlang/latest/reference/tmux_server-status-1/) (function): Read the endpoint owner's lifecycle and resource summary. This contacts the library owner, not tmux, and does not refresh captured rows.
- [`t/0`](/en/erlang/latest/reference/t-tmux_server-t-0/) (typealias): A supervised borrowed-endpoint handle bound to an owner generation and admission state.

## Guides

Pages that discuss `tmux_server`.

- [Native API documentation](/en/erlang/latest/guides/api-documentation/)

## In other ports

A tmux server

| Language | Equivalent |
| --- | --- |
| Python | [`libtmux.Server`](/en/py/latest/reference/libtmux-server/) (class) |
| Ruby | [`LibTmux::Server`](/en/ruby/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. |
| Haskell | No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing. |
| 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) |
| Clojure | [`libtmux.core/open!`](/en/clojure/latest/reference/libtmux-core-open/) (function). Opens a closeable Java server client for an explicit endpoint. Acquisitions return persistent maps with explicit Java references for effects. |
| 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) |
| OCaml | [`Libtmux_unix.Client.t`](/en/ocaml/latest/reference/libtmux_unix-client-t/) (typealias). A client is a live, generation-bound server connection. Endpoint describes a socket without connecting; closing a client releases its resources. |
| Perl | [`LibTmux::Server`](/en/perl/latest/reference/libtmux-server/) (class). Construction records connection settings without tmux I/O. Optional LibTmux::Async::Server returns standard Future results for operations. |

No equivalent is recorded in Common Lisp.