Workspaces and environments

The workspace environment determines where a terminal runs, where filesystem operations are authorized and how a new tab resolves its working directory.

Local

Local is the default environment. Rust spawns the configured shell in the authorized workspace directory. The explorer, Git commands and AI filesystem tools use the same authorization boundary.

WSL

On Windows, Voktty can enumerate installed WSL distributions and open a terminal in the selected distribution. The WSL home directory is resolved through a Rust command rather than guessed from Windows environment variables.

WSL is modeled as its own environment so a tab can retain its distribution and path context. The current CLI control plane does not yet pass control credentials into WSL panes.

SSH

SSH connections contain a host, optional user and port, optional identity file, extra arguments and an initial directory. Saved connection metadata is separate from an active session id. The remote workspace protocol can proxy requests for directory listing, file reads and writes through the Rust host.

SSH paths and authentication are platform-sensitive. Treat the SSH workspace path as experimental while the remote protocol evolves, and verify the connection from the workspace selector before editing files.

Serial devices

The serial workspace presents a serial port as a terminal-like tab. It supports common baud rates and serial parameters:

Parameter Values
Data bits 5, 6, 7 or 8
Parity None, odd or even
Stop bits 1 or 2
Flow control None, software or hardware

The status bar exposes DTR and RTS controls and a reset pulse where the device supports those signals. Serial output is streamed as raw bytes to avoid JSON overhead on high-rate connections.

Docker

The workspace model includes a Docker environment with a container id, name, image, optional shell, user and working directory. The Docker backend is under active development. Do not assume Docker workspace support is present in every released build until it is exposed by the workspace selector and release notes.

Scope and persistence

Workspace environment identity contributes to the tab scope key. SSH session ids are runtime-only and are removed before persistence. WSL distribution selection can be remembered as a preference. Serial and Docker connection details should be treated as environment metadata, not as secrets.

Troubleshooting

  1. Confirm the environment is available outside Voktty, for example with wsl --list --verbose or ssh host.
  2. Re-open the workspace selector and refresh discovery.
  3. Check that the selected root exists and is authorized.
  4. For SSH, check identity-file permissions and the remote shell.
  5. For serial, close other monitor applications before opening the port.
  6. For Docker, confirm the container is running and the selected shell exists.