Ultimate Dyad-sh / Dyad Setup Guide in 5 Steps (2025)

What is Dyad-sh and Why You Need It in 2025

In the ever-evolving landscape of software development, the friction between local and remote environments remains a persistent challenge. Juggling SSH sessions, synchronizing files, and maintaining consistent configurations can drain productivity. Enter Dyad-sh, a revolutionary, open-source dual-environment shell designed to eliminate this friction. Updated for 2025, Dyad-sh (or simply Dyad) provides a unified interface to manage, interact with, and synchronize two environments—typically your local machine and a remote server—as a single, cohesive unit.

Imagine running a command that executes simultaneously on your local machine and a staging server, with the output intelligently merged. Picture a file-watcher that automatically syncs changes from your local editor to a remote Docker container. This is the power Dyad offers. It’s more than a terminal multiplexer like tmux; it's a complete workflow management system built for the modern, distributed development era.

This guide will walk you through the entire Dyad-sh setup process in five straightforward steps, transforming your development workflow from fragmented to fluid.

Before You Begin: Prerequisites

Before we dive in, ensure your system meets the following requirements. Dyad-sh is built to be lightweight and compatible, but a few things are necessary for a smooth installation.

• A Unix-like Operating System: macOS, Linux, or Windows Subsystem for Linux (WSL) 2.
• Git: Dyad uses Git for its plugin management and some sync operations. Verify your installation with git --version.
• Curl or Wget: Required for the installation script. Most systems have one of these pre-installed.
• SSH Access: If you plan to connect to a remote server, ensure you have passwordless SSH access configured using SSH keys. This is crucial for seamless operation.

Step 1: Installing Dyad-sh

Getting Dyad-sh onto your system is the first and simplest step. The team behind Dyad provides several installation methods to suit your preference and package manager.

For macOS (using Homebrew)

If you're on a Mac with Homebrew, installation is a one-line command:

brew install dyad-sh

This will install the latest stable version and handle all necessary dependencies.

For Linux and WSL (using the official script)

For most Linux distributions and WSL, the recommended method is to use the official installation script, which intelligently detects your system and installs Dyad-sh in the appropriate location (usually /usr/local/bin).

curl -sS https://get.dyad.sh | sh

After the installation, close and reopen your terminal or run source ~/.bashrc (or ~/.zshrc) to update your shell's path. You can verify the installation by running:

dyad --version

You should see the latest version number, confirming that Dyad-sh is ready to go.

Step 2: Initializing Your First Project

With Dyad installed, the next step is to initialize it within your project directory. Dyad works on a per-project basis, using a configuration file to define its behavior.

Navigate to your project's root folder and run the init command:

cd ~/your-project
dyad init

This command creates a new file named dyad.yml in your current directory. This YAML file is the heart of your Dyad setup. A newly generated file will look something like this:

# Dyad Configuration File v1.2
# Define your paired environments (dyads) here.

config:
  default_dyad: my-app


dyads:
  my-app:
    # Define the first environment (pane 1)
    env1:
      name: "Local"
      path: "."
      shell: "zsh"

    # Define the second environment (pane 2)
    env2:
      name: "Remote"
      # Example: ssh://user@host:/path/to/project
      path: ""
      shell: "bash"

sync:
  # File synchronization rules (optional)
  - from: env1
    to: env2
    watch: ["src/", "config/"]
    ignore: ["node_modules/", ".git/"]

Don't worry about understanding every line just yet. We'll configure the most important parts in the next step.

Step 3: Defining Your Dyads (Local & Remote)

Now we get to the core concept: defining your "dyad." A dyad is a pair of environments that you want to control simultaneously. Let's configure a common use case: a local development environment and a remote staging server.

Open the dyad.yml file in your favorite editor. We will focus on the dyads: section.

Configuring the 'my-app' Dyad

Let's assume your local project is at ~/projects/my-app and your remote project is on a server at staging.myapp.com under the user dev at path /home/dev/my-app.

Modify the dyads.my-app block as follows:

dyads:
  my-app:
    # This is our local machine
    env1:
      name: "Local 💻"
      path: "." # The dot means the current directory where dyad.yml is
      shell: "zsh" # Or your preferred local shell

    # This is our remote staging server
    env2:
      name: "Staging ☁️"
      # The path uses an SSH URI format
      path: "ssh://dev@staging.myapp.com:/home/dev/my-app"
      shell: "bash" # The default shell on the remote server

Here's what we did:

• env1 (Local): We gave it a descriptive name with an emoji (Dyad supports Unicode!). The path: "." tells Dyad that this environment's root is the current directory.
• env2 (Remote): We used an SSH URI for the path. This format is intuitive: ssh://[user]@[host]:[path]. Dyad will use your existing SSH configuration to connect.

This simple configuration is enough to get started. You can define multiple dyads in the same file for different purposes (e.g., `staging`, `production`, `testing`).

Step 4: Launching Your First Dyad Session

With your configuration in place, it's time to launch Dyad and see the magic happen. From your project's root directory (where dyad.yml is located), run:

dyad start my-app

If you set a default_dyad in the config, you can simply run dyad start.

Your terminal will transform. You'll be greeted by a split-pane view:

• On the left (Pane 1): A shell session in your local project directory. The prompt will be prefixed with `[Local 💻]`.
• On the right (Pane 2): A shell session on your remote server, already `cd`-ed into the correct project directory. The prompt will be prefixed with `[Staging ☁️]`.

You can now type commands in either pane. To run a command in both panes simultaneously, press the meta key (usually `Ctrl+A` by default) and then type your command. For example, hitting `Ctrl+A` and then typing `ls -l` will list files in both your local and remote directories at the same time. This is incredibly powerful for comparison and verification tasks.

Step 5: Advanced Customization and Plugins

You now have a working Dyad setup. To truly make it your own, you can explore its advanced features.

Customizing the Interface

You can customize colors, the status bar, and keybindings in the config: section of your dyad.yml. For example, to change the meta key from `Ctrl+A` to `Ctrl+B` (like tmux), you would add:

config:
  default_dyad: my-app
  meta_key: "C-b"

Using Plugins

The 2025 version of Dyad-sh boasts a robust plugin system. Plugins can add new commands, status bar widgets, or event hooks. To install a popular plugin for showing the current Git branch in your status bar:

dyad plugin install git-status

After installation, the plugin is active immediately. You can discover more plugins by running dyad plugin search.

Automated File Synchronization

Revisit the sync: block in your dyad.yml. By uncommenting and configuring it, you can instruct Dyad to watch for file changes in one environment and automatically copy them to the other using `rsync` over SSH. This creates a tight development loop without manual `scp` or `rsync` commands.

Dyad-sh vs. Other Tools: A Quick Comparison

How does Dyad-sh stack up against other popular development tools? Here's a high-level comparison.

Conclusion: Embrace the Duality

Setting up Dyad-sh is a small investment of time that pays massive dividends in productivity. By following these five steps, you've configured a powerful, modern development environment that treats your local and remote machines as a single, unified workspace. You've moved beyond simple terminal multiplexing and into the realm of true dual-environment orchestration.

As development becomes increasingly distributed, tools like Dyad-sh are not just a convenience; they are a necessity. Welcome to the future of command-line development in 2025.