# Install and load a workspace

Source: https://libtmux.org/en/rs/latest/workspace/guides/installation/

> Build the workspace command and load a session on a private tmux socket.

**Workspace Manager concept example** A working example of the core library. It can change without notice.



Build the documented `tmux-workspace` revision, then load a small session on a
private socket. Use a Unix shell with tmux 3.3a or newer on `PATH`.

## Build the command

Fetch the documented source revision, then build from its repository root.
Keep the exported `PATH` in this shell for the rest of the walkthrough.

```console
$ git clone --filter=blob:none https://github.com/libtmux/libtmux-rs.git
```

```console
$ cd libtmux-rs
```

```console
$ git fetch --depth=1 origin e9be0b6f6d22cd2eb79b0ec08964f82e717e5fe4
```

```console
$ git checkout --detach FETCH_HEAD
```

Use the Rust toolchain selected by [`rust-toolchain.toml`](<https://github.com/libtmux/libtmux-rs/blob/2c165c4433d1bdb747a350bd460364daa4a06a55/rust-toolchain.toml>):

```console
$ cargo build --locked -p tmux-workspace --bin tmux-workspace
```

```console
$ export PATH="$PWD/target/debug:$PATH"
```

```console
$ tmux-workspace --help
```

## Create the input

Keep this shell open. Create a temporary working directory on a filesystem that
supports Unix sockets, then enter it:

```console
$ WORKSPACE_TMP="$(mktemp -d)"
```

```console
$ cd "$WORKSPACE_TMP"
```

Save this as `workspace.yaml`:

```yaml title="workspace.yaml"
session_name: workspace-guide
windows:
  - window_name: editor
    layout: even-horizontal
    panes: [null, null]
```

## Load and inspect

```console
$ tmux-workspace load \
    -S "$WORKSPACE_TMP/tmux.sock" \
    -f /dev/null \
    -d \
    --json \
    workspace.yaml
```

`-d` leaves the session detached. Inspect its panes using the same socket:

```console
$ tmux -S "$WORKSPACE_TMP/tmux.sock" list-panes -t '=workspace-guide:editor'
```

Attach interactively with [`tmux -S "$WORKSPACE_TMP/tmux.sock" attach-session -t
'=workspace-guide'`](https://libtmux.org/en/tmux/latest/manual/attach-session/). Detach with your tmux detach binding before continuing.

## Capture and clean up

```console
$ tmux-workspace freeze -S "$WORKSPACE_TMP/tmux.sock" --json workspace-guide
```

Try [export and reload](https://libtmux.org/en/rs/latest/workspace/guides/export-session/) before cleanup. Capture cannot
recover original scripts, command history or application state.

Remove only the session created by this walkthrough when finished:

```console
$ tmux -S "$WORKSPACE_TMP/tmux.sock" kill-session -t '=workspace-guide'
```

The configuration remains in the temporary directory. Keep the session running
when following guides that continue this example.

## Continue

[Configuration](https://libtmux.org/en/rs/latest/workspace/configuration/) describes execution fields;
[discovery](https://libtmux.org/en/rs/latest/workspace/guides/discovery/) finds saved files. Read the [load reference](https://libtmux.org/en/rs/latest/workspace/cli/load/)
and [automation](https://libtmux.org/en/rs/latest/workspace/guides/automation/) for attachment, output and failure handling.

[CLI source](https://github.com/libtmux/libtmux-rs/blob/e9be0b6f6d22cd2eb79b0ec08964f82e717e5fe4/crates/tmux-workspace/docs/cli.md).