# tmux.Server

- **Module:** tmux
- **Package:** github.com/libtmux/libtmux-go/tmux
- **Language:** Go
- **Kind:** struct
- **Source:** https://github.com/libtmux/libtmux-go/blob/5f808882015a975a65acc7f9da5b3ff0d5cbdc91/tmux/server.go#L16
- **Page:** https://libtmux.org/reference/go/tmux-server/

Server is an immutable handle to one tmux configuration. Its zero value is invalid. Copying a configured Server preserves its configuration and shares version-cache coordination; only the documented concurrent operations are safe to share.

## Members

- `ConnectionBound` (method) — ConnectionBound reports whether this handle retains terminal transport owned by a [Connection]. A bound handle never reconnects or falls back to a tmux subprocess after that connection closes.
- `NewSessionConnection` (method) — NewSessionConnection creates a session with a control-mode client and keeps that same process as the first terminal command lane. Unlike [Server.NewSession], it creates an attached session. If tmux reports a valid session ID before later setup fails, the returned partial session retains that ID and server. Cleanup closes the attached creator, so tmux policy may make the partial session no longer live. Before tmux 3.6, destroying the created session follows its detach-on-destroy policy and may end the connection. KillExisting is rejected because removing an existing session cannot be rolled back if later connection setup fails.
- `OpenControl` (method) — OpenControl starts a control-mode client attached to session. The startup context bounds process start, attach framing, and client registration but does not own the returned client's lifetime. Session must belong to the same configured server selector.
- `DisplayMessage` (method) — DisplayMessage displays or prints a server-scoped tmux message. Print returns an owned stdout slice even when tmux exits nonzero; completed stderr is delivered synchronously through [WarningCommandStderr], not returned as a completed-error classification. Unsupported flags follow [UnsupportedPolicy]. Any warnings run on the caller goroutine before return. Cancellation does not prove display did not occur.
- `SetEnvironment` (method) — SetEnvironment stores a value in the server's global tmux environment. ExpandFormat and Hidden select tmux flags; cancellation does not prove the value was not stored.
- `UnsetEnvironment` (method) — UnsetEnvironment deletes a value from the server's global tmux environment. Cancellation does not prove deletion did not occur.
- `RemoveEnvironment` (method) — RemoveEnvironment marks a variable for removal from new process environments.
- `ShowEnvironment` (method) — ShowEnvironment returns an owned server-global non-hidden tmux environment. Completed command failures return an empty map unless strict errors are enabled. Externally injected multiline entries return ErrMalformedEnvironment because tmux's multi-entry output does not frame continuation lines. Decode errors are compatible with [ErrMalformedEnvironment] and return no partial map.
- `GetEnvironment` (method) — GetEnvironment returns one non-hidden global environment entry. A missing or hidden variable reports ok false.
- `Sessions` (method) — Sessions materializes the server's sessions. Failures, including [ErrNoServer], remain errors rather than empty results.
- `Windows` (method) — Windows materializes one record per winlink. Failures, including [ErrNoServer], remain errors rather than empty results.
- `Panes` (method) — Panes materializes pane records for every winlink. Failures, including [ErrNoServer], remain errors rather than empty results.
- `Clients` (method) — Clients materializes attached clients. Failures, including [ErrNoServer], remain errors rather than empty results.
- `Equal` (method) — Equal reports whether both handles currently select the same socket path. It evaluates relative paths and environment-dependent named and default sockets against each handle's frozen binding.
- `String` (method) — String returns a concise representation of the server selector.
- `Kill` (method) — Kill terminates the configured tmux server and all of its sessions, windows, panes, and clients. After a completed failed kill, a liveness probe makes repeated calls harmless when no daemon answers. Transport or context errors can be delivery-ambiguous; no rollback is attempted.
- `KillSession` (method) — KillSession terminates the session selected by tmux target syntax. Pattern and prefix matching are deliberately left to tmux. Completed nonzero exits without stderr are ignored. Transport and context errors are delivery-ambiguous.
- `Session` (method) — Session performs a canonical live lookup of id and returns a newly materialized record. Use [Session.Refresh] when beginning from a record.
- `Window` (method) — Window performs a canonical live lookup of id using tmux's canonical session and returns a newly materialized record. It does not preserve a linked-session view; use [Window.ResolveSession] for that exact relationship.
- `Pane` (method) — Pane performs a canonical live lookup of id using tmux's canonical session and returns a newly materialized record. It does not preserve a linked-session view; use [Pane.ResolveWindow] for that exact relationship.
- `Client` (method) — Client performs a canonical live lookup of name and returns a new record.
- `OpenNotifications` (method) — OpenNotifications starts an owned observation-only stream attached to session. Session must belong to the same configured server selector. A connection-bound server returns [ErrConnectionRequiresProcess].
- `SetBackspace` (method) — SetBackspace stores the "backspace" server option as string (tmux 3.2a or later). Read it with [ServerOptionValues.Backspace] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetBufferLimit` (method) — SetBufferLimit stores the "buffer-limit" server option as int64 (tmux 3.2a or later). Read it with [ServerOptionValues.BufferLimit] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetCopyCommand` (method) — SetCopyCommand stores the "copy-command" server option as string (tmux 3.2a or later). Read it with [ServerOptionValues.CopyCommand] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetDefaultClientCommand` (method) — SetDefaultClientCommand stores the "default-client-command" server option as string (tmux 3.6 or later). Read it with [ServerOptionValues.DefaultClientCommand] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetDefaultTerminal` (method) — SetDefaultTerminal stores the "default-terminal" server option as string (tmux 3.2a or later). Read it with [ServerOptionValues.DefaultTerminal] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetEditor` (method) — SetEditor stores the "editor" server option as string (tmux 3.2a or later). Read it with [ServerOptionValues.Editor] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetEscapeTime` (method) — SetEscapeTime stores the "escape-time" server option as int64 (tmux 3.2a or later). Read it with [ServerOptionValues.EscapeTime] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetExitEmpty` (method) — SetExitEmpty stores the "exit-empty" server option as bool (tmux 3.2a or later). Read it with [ServerOptionValues.ExitEmpty] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetExitUnattached` (method) — SetExitUnattached stores the "exit-unattached" server option as bool (tmux 3.2a or later). Read it with [ServerOptionValues.ExitUnattached] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetExtendedKeys` (method) — SetExtendedKeys stores the "extended-keys" server option as ExtendedKeys (tmux 3.2a or later). Read it with [ServerOptionValues.ExtendedKeys] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetExtendedKeysFormat` (method) — SetExtendedKeysFormat stores the "extended-keys-format" server option as ExtendedKeysFormat (tmux 3.5 or later). Read it with [ServerOptionValues.ExtendedKeysFormat] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetFocusEvents` (method) — SetFocusEvents stores the "focus-events" server option as bool (tmux 3.2a or later). Read it with [ServerOptionValues.FocusEvents] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetGetClipboard` (method) — SetGetClipboard stores the "get-clipboard" server option as GetClipboard (tmux 3.7 or later). Read it with [ServerOptionValues.GetClipboard] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetHistoryFile` (method) — SetHistoryFile stores the "history-file" server option as string (tmux 3.2a or later). Read it with [ServerOptionValues.HistoryFile] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetInputBufferSize` (method) — SetInputBufferSize stores the "input-buffer-size" server option as int64 (tmux 3.6 or later). Read it with [ServerOptionValues.InputBufferSize] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetMessageLimit` (method) — SetMessageLimit stores the "message-limit" server option as int64 (tmux 3.2a or later). Read it with [ServerOptionValues.MessageLimit] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetPrefixTimeout` (method) — SetPrefixTimeout stores the "prefix-timeout" server option as int64 (tmux 3.5 or later). Read it with [ServerOptionValues.PrefixTimeout] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetPromptHistoryLimit` (method) — SetPromptHistoryLimit stores the "prompt-history-limit" server option as int64 (tmux 3.3 or later). Read it with [ServerOptionValues.PromptHistoryLimit] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetClipboard` (method) — SetClipboard stores the "set-clipboard" server option as SetClipboard (tmux 3.2a or later). Read it with [ServerOptionValues.SetClipboard] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetVariationSelectorAlwaysWide` (method) — SetVariationSelectorAlwaysWide stores the "variation-selector-always-wide" server option as bool (tmux 3.6 or later). Read it with [ServerOptionValues.VariationSelectorAlwaysWide] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default.
- `SetCodepointWidths` (method) — SetCodepointWidths replaces the complete "codepoint-widths" server option array with SparseArray[string], preserving holes and empty values (tmux 3.6 or later). Read it with [ServerOptionValues.CodepointWidths] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
- `SetCommandAlias` (method) — SetCommandAlias replaces the complete "command-alias" server option array with SparseArray[string], preserving holes and empty values (tmux 3.2a or later). Read it with [ServerOptionValues.CommandAlias] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
- `SetTerminalFeatures` (method) — SetTerminalFeatures replaces the complete "terminal-features" server option array with SparseArray[string], preserving holes and empty values (tmux 3.2a or later). Read it with [ServerOptionValues.TerminalFeatures] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
- `SetTerminalOverrides` (method) — SetTerminalOverrides replaces the complete "terminal-overrides" server option array with SparseArray[string], preserving holes and empty values (tmux 3.2a or later). Read it with [ServerOptionValues.TerminalOverrides] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
- `SetUserKeys` (method) — SetUserKeys replaces the complete "user-keys" server option array with SparseArray[string], preserving holes and empty values (tmux 3.2a or later). Read it with [ServerOptionValues.UserKeys] from [Server.Options]; [Server.UnsetOption] restores inheritance or the global default. Replacement is not atomic: the result reports confirmed writes, and failures stop without rollback. Serialize concurrent replacement of the same target and option.
- `SetOption` (method) — SetOption stores a server-scope option without refreshing existing models. It may validate a known option against the live version. Completed failures return secret-safe option errors; cancellation does not prove the mutation was not accepted by tmux.
- `AppendOption` (method) — AppendOption appends to a server-scope option without refreshing existing models. Completed failures are secret-safe option errors; cancellation does not prove the append was not accepted.
- `UnsetOption` (method) — UnsetOption unsets a server-scope option without refreshing existing models. UnsetPanes is invalid at server scope. Completed failures are secret-safe option errors; cancellation does not prove the unset was not accepted.
- `Options` (method) — Options returns a freshly decoded, caller-owned view of known server options, including inherited values. A read or transport failure is returned rather than answered with zero values; context errors propagate. Each returned accessor names the setter that writes it, so [ServerOptionValues.BufferLimit] pairs with [Server.SetBufferLimit].
- `RawOption` (method) — RawOption returns one exact server-scope option value. A successful string is caller-owned; ok reports presence. Targeted reads do not use list leniency, and completed failures return a secret-safe option error. An unindexed empty array is indistinguishable from an empty scalar; use Options for typed array presence.
- `GlobalSessionScope` (method) — GlobalSessionScope returns a handle that preserves s and its error policy.
- `GlobalWindowScope` (method) — GlobalWindowScope returns a handle that preserves s and its error policy.
- `ShowPromptHistory` (method) — ShowPromptHistory returns an owned snapshot of tmux prompt-history lines. It requires tmux 3.3 or later and returns [VersionTooLowError] below that floor. A tmux command or transport failure is returned rather than answered with no history.
- `ClearPromptHistory` (method) — ClearPromptHistory clears all tmux prompt history or one selected class. Version, transport, and completed-stderr failures are returned. It requires tmux 3.3 or later and returns [VersionTooLowError] below that floor.
- `SearchSessions` (method) — SearchSessions returns a newly materialized snapshot projection of sessions selected by tmux's live -f expression. A nil filter omits -f; a nonnil empty filter remains an explicit empty expression.
- `SearchClients` (method) — SearchClients returns a newly materialized snapshot projection of clients selected by tmux's live -f expression. A nil filter omits -f and requests the unfiltered listing on every supported tmux version. A nonnil filter, including an empty expression, requires tmux 3.4 or newer and otherwise returns [VersionTooLowError].
- `SearchWindows` (method) — SearchWindows returns a newly materialized snapshot projection of winlinks selected by tmux's live -f expression. A nil filter omits -f and a nonnil empty filter sends an explicit expression.
- `SearchPanes` (method) — SearchPanes returns a newly materialized snapshot projection of pane views selected by tmux's live -f expression. A nil filter omits -f and a nonnil empty filter sends an explicit expression.
- `SocketPath` (method) — SocketPath returns the absolute socket path selected when the server was constructed. An invalid server returns an empty string.
- `ConfigFile` (method) — ConfigFile returns the configured tmux configuration path.
- `ProcessEnvironment` (method) — ProcessEnvironment returns the normalized environment explicitly supplied through [ServerOptions]. Nil means the server inherited a private process snapshot. The returned slice is owned by the caller; an invalid server returns nil.
- `Executable` (method) — Executable returns the absolute tmux executable path resolved when the server was constructed. An invalid server returns an empty string.
- `Cmd` (method) — Cmd executes raw tmux arguments and returns caller-owned result slices. A completed nonzero exit remains a result; validation and transport failures return errors. Cancellation cannot prove whether a mutation reached tmux.
- `IsAlive` (method) — IsAlive reports whether a tmux server answers on the configured socket. Only an absent server reports false without an error: a socket that exists but cannot be reached, such as one the process may not read, is a question that could not be answered and is returned as an error.
- `RaiseIfDead` (method) — RaiseIfDead returns a [CommandError] when the configured server is not alive. Cancellation and transport failures are returned directly.
- `Start` (method) — Start starts the configured tmux server. It is idempotent when that server is already running. Completed stderr is an error; cancellation does not prove that a daemon was not started.
- `AttachSession` (method) — AttachSession attaches the caller's terminal to a matching session and blocks until detach or context cancellation. Nil standard streams inherit the process streams; each stream must be a concrete terminal descriptor. The call retains caller-supplied files while attached and never owns or closes them. A completed nonzero exit returns [CommandError]; cancellation can end waiting but does not prove that attachment or detachment did not occur.
- `SetBuffer` (method) — SetBuffer stores or appends exact string data without refreshing models. It mutates the selected paste buffer; completed stderr is reported as a redacted command error because Data may be secret. Cancellation does not prove that tmux did not store data.
- `ShowBuffer` (method) — ShowBuffer returns one buffer using Python-compatible line reconstruction. The returned string is owned by the caller; nil Name selects tmux's most recent buffer. Completed stderr is an error.
- `ShowBufferBytes` (method) — ShowBufferBytes returns one buffer as exact caller-owned tmux stdout bytes. Unlike [Server.ShowBuffer], it preserves invalid UTF-8, delimiters, and trailing newlines. Nil Name selects tmux's most recent buffer. Completed stderr returns a redacted command error and a nil byte slice.
- `DeleteBuffer` (method) — DeleteBuffer deletes a named buffer, or the most recent buffer when name is nil. Cancellation does not prove that tmux did not delete the buffer.
- `SaveBuffer` (method) — SaveBuffer writes a named or most-recent buffer to a file. Path follows [Server.SourceFile]'s current-user expansion and lexical normalization. It changes that file; exact "-" is rejected because the runner exposes no process stdio.
- `LoadBuffer` (method) — LoadBuffer reads a file into a named or newly allocated buffer. Path follows [Server.SourceFile]'s current-user expansion and lexical normalization. It mutates tmux's destination buffer and rejects exact "-" because no process stdio is exposed.
- `ListBuffers` (method) — ListBuffers returns an owned snapshot of live tmux buffer rows. A command or transport failure is returned rather than answered with no rows; context cancellation still returns its context error. The result is not a live collection.
- `ServerAccess` (method) — ServerAccess changes or lists the server access-control entries. It requires tmux 3.3 and returns [VersionTooLowError] below that floor. List returns an owned snapshot, and reports a completed or transport failure rather than answering with no entries; mutation completed stderr is an error.
- `LockServer` (method) — LockServer locks every attached client on the tmux server. Cancellation does not prove the server did not lock a client.
- `RefreshClient` (method) — RefreshClient redraws a client, or tmux's current client when no target is set. RequestClipboard requires tmux 3.4 and follows [UnsupportedPolicy].
- `LockClient` (method) — LockClient locks a client, or tmux's current client when targetClient is nil. Cancellation does not prove the target client was not locked.
- `SuspendClient` (method) — SuspendClient suspends a client, or tmux's current client when targetClient is nil. Cancellation does not prove suspension did not occur.
- `DetachClient` (method) — DetachClient detaches one client, or tmux's current client when no target is set. A completed stderr result is an error; cancellation does not prove delivery or detachment did not occur.
- `DetachAllClients` (method) — DetachAllClients detaches every client except KeepClient or tmux's current client. Cancellation does not prove every client was detached.
- `SwitchClient` (method) — SwitchClient switches tmux's current client to targetSession. TargetSession is a validated session name rather than a stable identity; cancellation does not prove the switch did not occur.
- `RunShell` (method) — RunShell executes a shell command through tmux and returns an owned stdout slice. A background request returns nil after tmux accepts the job. Unsupported optional flags follow [UnsupportedPolicy]. A completed stderr result is an error; context cancellation can be observed with [errors.Is] but does not establish that tmux did not start the job.
- `WaitFor` (method) — WaitFor waits for, signals, locks, or unlocks a named tmux channel. It changes only that server-side channel state; cancellation can interrupt the client wait but cannot prove a preceding signal or lock did not take effect.
- `IfShell` (method) — IfShell executes ThenCommand when ShellCommand succeeds and ElseCommand, if present, when it fails. A completed stderr result is an error; cancellation can interrupt delivery without proving that tmux did not execute a branch.
- `SourceFile` (method) — SourceFile loads or parses one tmux configuration file. The path expands ~ and ~/... for the current user and normalizes redundant separators and dot components without collapsing parent components. Named-user forms are rejected. Exact "-" is rejected because it requires process stdin; a relative path naming a file called "-" remains file data. It can mutate tmux configuration; completed stderr is an error, and cancellation does not prove that parsing or sourcing did not occur.
- `ConfirmBefore` (method) — ConfirmBefore asks tmux to display a background confirmation prompt and returns after tmux accepts it, not after the user answers or Command runs. It requires tmux 3.3. ConfirmKey and DefaultYes require tmux 3.4 and follow [UnsupportedPolicy]. Completed stderr is an error; cancellation does not prove prompt delivery or later command execution did not occur.
- `CommandPrompt` (method) — CommandPrompt asks tmux to display a background command prompt and returns after tmux accepts it, not after input is submitted or Template runs. It requires tmux 3.3. Later flags follow [UnsupportedPolicy]. Completed stderr is an error; cancellation does not prove prompt delivery or later execution.
- `DisplayMenu` (method) — DisplayMenu displays a menu and waits until tmux closes it. The target client must own a TTY; control-mode clients cannot render menu overlays. It returns no selected value and does not establish whether an item command ran. Unsupported optional flags follow [UnsupportedPolicy]. Completed stderr is an error, and cancellation does not prove menu delivery or a selected command's effect.
- `BindKey` (method) — BindKey binds Key to Command in a tmux key table. An empty Command creates a no-op binding on tmux 3.3 or newer; tmux 3.2a reports its upstream error. It mutates the table; cancellation does not prove that tmux did not bind Key.
- `UnbindKey` (method) — UnbindKey removes one key binding or every binding in a key table. Key and AllKeys must select exactly one target; cancellation does not prove removal did not occur.
- `ListKeys` (method) — ListKeys returns an owned snapshot of raw tmux key-binding lines. Format requires tmux 3.7 and follows [UnsupportedPolicy]. tmux 3.7 through 3.7c send a table's sole matching binding to client status and leave stdout empty; this method preserves that upstream and Python behavior. Listing failures remain errors.
- `ListCommands` (method) — ListCommands returns an owned snapshot of raw tmux command-description lines. A list failure is returned rather than answered with no rows. Like [Server.ListKeys], it answers on a socket holding no server.
- `ListClients` (method) — ListClients returns an owned snapshot of raw tmux client-description lines. A list failure is returned rather than answered with no rows.
- `ShowMessages` (method) — ShowMessages returns an owned snapshot of the tmux message log, terminal capabilities, job summary, or both terminal and job summaries. A zero TargetClient selects tmux's current client; a list failure is returned rather than answered with no rows.
- `WithSocketPath` (method) — WithSocketPath returns a server using path and the receiver's frozen executable, environment, working directory, and server-option policy. Empty clears explicit socket selectors and leaves endpoint selection to tmux. The result has fresh daemon-scoped coordination. A connection-bound receiver is rejected because its transport belongs to the original daemon.
- `Version` (method) — Version returns the configured tmux binary's cached version. Failed probes are not cached. A waiting caller can abandon an in-flight shared probe when ctx ends without canceling the caller that owns the probe.
- `RefreshVersion` (method) — RefreshVersion invalidates the cached version and probes the binary again. Canceling ctx stops this call's wait; it does not establish whether a probe reached the configured binary.
- `RequireVersion` (method) — RequireVersion returns a [VersionTooLowError] matching [ErrVersionTooLow] when the configured binary is older than minimum.
- `HasSession` (method) — HasSession reports whether Target selects a session. With Pattern false it compares session names exactly; with Pattern true, tmux may resolve IDs, client TTYs, unique prefixes, or globs. Pattern-mode completed nonzero exits are misses. Exact-name lookup treats [ErrNoServer] as a miss and returns other failures.
- `NewSession` (method) — NewSession creates a detached session, then returns a newly materialized [Session]. It never changes client focus. KillExisting is not rolled back; transport and context failures may be delivery-ambiguous.
- `Snapshot` (method) — Snapshot materializes sessions, winlinks, panes, and clients. Its sequential commands produce an observationally consistent result, not an atomic transaction. Failures remain errors rather than empty snapshots; cancellation may occur after earlier listings completed.
- `SocketSelection` (method) — SocketSelection returns tmux's -S, -L, TMUX, and default-socket precedence snapshotted by [NewServer]. It does not start tmux or require the selected socket to exist.