butai docs 1.3.0

Native Windows TUI (experimental alpha)#

The butai.exe binary runs the same terminal workbench, CLI, and persistent background daemon as Linux and macOS. Use Windows Terminal on Windows 10 1809+ or Windows 11; the pane backend uses Windows ConPTY. Git commands require Git for Windows on PATH. Install agent CLIs separately as usual.

The native Windows TUI is experimental alpha. Frequent crashes have been reported; it is unsuitable for reliable daily use. Linux and macOS keep their existing interface and defaults.

Stable installation#

Use WSL2 and the Linux installer for a stable installation on Windows. Run butai and your projects inside WSL2.

Download the native Windows build (experimental)#

The 1.3.0 release includes a Windows x64 build, but the native Windows port remains experimental alpha. WSL2 is the recommended option for daily use.

Download Butai 1.3.0 for Windows x64 and SHA256SUMS from the 1.3.0 release. In PowerShell, open the folder containing your downloads and calculate the archive's checksum:

Get-FileHash .\butai-1.3.0-x86_64-pc-windows-msvc.tar.gz -Algorithm SHA256

Compare the hash with the entry for that exact filename in SHA256SUMS. Continue only if they match; letter case does not matter. Extract the archive, then start the included executable from Windows Terminal:

tar -xzf .\butai-1.3.0-x86_64-pc-windows-msvc.tar.gz
.\butai-1.3.0-x86_64-pc-windows-msvc\butai.exe

To run butai from your project folders, place butai.exe in a permanent folder and add that folder to your user PATH. Open a new terminal afterward. The curl ... | sh command on the homepage is for Linux, macOS, and WSL2; it does not install the native Windows build.

The sections below describe the native port's behavior and limitations.

Display compatibility#

The Windows TUI alpha defaults to [ui] glyphs = "ascii": borders, arrows, spinners and meters use single-column ASCII alternatives that do not require a special font. Normal text, accented characters, CJK and emoji remain Unicode. This is a display setting; copied text and saved pane output retain their original characters. Linux and macOS keep their Unicode default.

For the original symbols with a terminal font that supports them, add:

[ui]
glyphs = "unicode"

The Windows client enables UTF-8 while attached and defers wrapping at the last column so painting the bottom-right corner cannot scroll the whole interface. It restores the previous console modes and encoding when it exits.

Shells and configuration#

State and configuration live in %USERPROFILE%\.butai, with the same BUTAI_HOME, BUTAI_SOCKET and BUTAI_SESSION_FILE overrides. Windows defaults to %COMSPEC% (cmd.exe). To use PowerShell, put this in config.toml:

[general]
default_shell = "pwsh.exe"

Process commands use /D /C with a temporary batch file for cmd, -EncodedCommand for PowerShell, and -c for Unix-style shells. Write .butai.toml commands for the configured shell. Agent lookup respects PATHEXT, including npm's .cmd wrappers. Batch agents launch through Windows PowerShell so their paths and arguments survive quoting.

Local transport and remote hosts#

The socket path remains the endpoint identity and the location of its lock file. Windows maps the absolute path to a deterministic named pipe; it does not create an AF_UNIX socket file there. The pipe ACL grants access only to the current user and SYSTEM, and rejects network clients. HTTP and the framed pane protocol share that pipe. Unix keeps its existing socket transport, terminal recovery and daemon detachment code.

butai proxy exposes either protocol over standard input/output. SSH connections from Windows to Unix hosts bridge a local named pipe to one ssh ... butai proxy process per connection; Unix clients continue using socket forwarding and SSH multiplexing. Windows needs OpenSSH on PATH and a working noninteractive key or agent setup for remote workspaces.

To update a connected Unix server from the Windows client, enable the existing remote updater in that server's ~/.butai/config.toml:

[update]
channel = "stable"
allow_remote = true

Run :reload-config on that server's tab, then use :update there or select the server's update action under SETTINGS → MACHINES. The server downloads its own platform's release, verifies its checksum and restarts; connected clients detach and saved workspaces return. This works independently of the Windows client's local self-update limitation. Only published releases appear in the updater; CI artifacts do not. The configuration above follows stable releases.

Current limits#

  • Content search skips binary files and files larger than 1 MiB.
  • In-place self-update is disabled on Windows; install new releases manually.
  • CPU and RAM telemetry use Windows APIs. Network, disk, swap and temperature samplers that use /proc or Mach are unavailable on Windows.
  • Shell rows keep their shell label because ConPTY has no Unix foreground process-group query. Automatic SSH handoff detection is Unix-only; use the host picker on Windows.
  • Remote host discovery expects a Unix shell on the SSH server. Native Windows SSH servers and Unix socket tools such as curl --unix-socket are not covered.
  • The browser relay currently expects Unix sockets; this port covers the native TUI.

    ↑↓ move ↵ open esc close