# Workspaces

`runpane workspace` lets your own machines read files, write files, run commands, and drive each other's Pane. You don't need SSH or keys.

| You ask | The agent |
| --- | --- |
| "Which of my machines are online?" | Lists your machines and whether Pane is running on each (`runpane workspace list`). |
| "Run the tests on my Windows PC and tell me what failed." | Runs the command in that machine's shell and reads its output and exit code. |
| "Read the error log on the devbox." | Prints the file from that machine. |
| "Put this note in my home folder on the laptop." | Writes the file there, replacing any file with the same name. |
| "What's running in Pane on my other Mac?" | Lists that machine's panes and the agent tabs in each (`workspace state`). |

It reaches a machine one of two ways:

- **Linked computers.** Link two computers with a one-time link from **Add a device → Computer**, or pair one phone with both ([Your computers](/docs/your-computers)). They reach each other directly or through Pane's relays, encrypted end to end, with Tailscale off.
- **Tailscale.** Machines on the Tailscale network you already use reach each other with no pairing. See [Who is trusted](#who-is-trusted).

The same connections power desktop remote mode. Pick your other machine under **Settings → Remote Access → Computers**, or from the machine menu at the top of the sidebar.

```bash
runpane workspace list
runpane workspace <machine> read  <path>
runpane workspace <machine> write <path>          # content from stdin
runpane workspace <machine> exec -- <command>     # runs in that machine's shell
runpane workspace <machine> <runpane command>     # e.g. sessions list --json
```

The machine is its Tailscale name (`my-devbox`), a unique prefix (`devbox`), its MagicDNS name, or a Tailscale IP. A linked computer goes by its name in lower case with dashes (`travel-laptop`). A computer that is both linked and on your tailnet is one machine, and runpane tries each of its routes until one answers.

> **Warning:** These commands need the npm [`runpane` CLI](/docs/runpane-cli) (`npm i -g runpane`, or `npx --yes runpane@latest workspace list`). The Python package doesn't run them.

Passing a command through works for commands that talk to Pane, such as `sessions list`, `panes list`, or `workspace state`. Commands that only make sense where you type them, such as `doctor`, run on the other machine with `runpane workspace <machine> exec -- 'runpane doctor'`.

## Turning it on

Workspaces are on by default. Linked computers need nothing else. For the Tailscale path, desktop Pane joins your tailnet as it starts when Tailscale is installed and signed in. It listens on `127.0.0.1` and runs `tailscale serve --bg --https=8443 http://127.0.0.1:<port>`, next to the [remote daemon](/docs/remote-daemon)'s port 443 handler if you have one. Nothing is opened to the public internet and no firewall rule is added.

`runpane --help`, `runpane doctor`, and `runpane agent-context` all print the current state:

```text
Workspaces: on (my-macbook-pro)
Other machines: my-devbox (Windows, online), my-macbook-air (macOS, offline)
Reach them: runpane workspace <machine> read|write|exec|<command>
```

When the Tailscale path is off, the first line says why and gives the one step that fixes it. Linked computers still work without Tailscale:

| Reason | Fix |
|---|---|
| Tailscale is not installed | Install Tailscale from [tailscale.com/download](https://tailscale.com/download) and sign in. |
| Tailscale is signed out | Open Tailscale and sign in. |
| HTTPS certificates are off for the tailnet | Turn on HTTPS Certificates in the [Tailscale DNS settings](https://login.tailscale.com/admin/dns). |
| Pane is not running | Open Pane. |
| Turned off with `runpane workspace disable` | `runpane workspace enable` |

`runpane workspace disable` takes this machine off until `runpane workspace enable`. It can still reach your other machines while it's off. Pane must be running on a machine for the others to reach it.

## Try your other machine

Replace `my-windows-pc` with a name from `runpane workspace list`. These commands read a file, run a command, write a note, and show that machine's panes and tabs:

```bash
runpane workspace my-windows-pc read '~/notes.md'
runpane workspace my-windows-pc exec -- 'git --version'
printf 'Check the Windows build\n' | runpane workspace my-windows-pc write '~/qa-note.txt'
runpane workspace my-windows-pc workspace state --json
```

The `printf` example runs from Bash or Zsh on the sending machine.

To hand a task with your branch and notes to a fresh agent, use [Handoff](/docs/runpane-handoff). Handoff can route a WSL sender to its own Windows host when no local Linux daemon is reachable. The receiving repository still has to be native.

## Who is trusted

A linked computer is trusted by the token it got when the two were linked. Use **Unlink from all your computers** on its row, or remove the phone that linked it, to take that away ([Your computers](/docs/your-computers)).

Over Tailscale, set **Settings → Remote Access → Tailscale → Who can connect**:

| Visibility | Who can connect |
|---|---|
| **Off** | No codeless access. Same as `runpane workspace disable`. |
| **Only me** | Your own Tailscale login. This is the default. |
| **Everyone on tailnet** | People with untagged devices on the current tailnet. |

Pane warns before you allow everyone, and access changes only after **Allow Everyone**. Devices shared from another tailnet and tagged devices are refused.

Password protection is off by default. When you set a password, every Tailscale client needs it, including your own computers. Pane stores a hash. Only someone at the host itself can change visibility or the password.

`runpane workspace` and cross-machine `runpane handoff` send the password the desktop app saved for that computer. To reach a password-protected host from the CLI, connect to it once from **Settings → Remote Access → Computers** and enter the password.

Tailscale Serve adds the caller's login after stripping any copy the caller sent. Pane checks visibility first, then the password. Browsers are refused on this listener. For a browser, pair with a [QR code](/docs/phone) or use a connection code.

Pane answers only requests that arrive through Serve. Its target path has a secret that changes each launch. Another OS user who can read `tailscale serve status` could learn it, so only give local accounts the trust you'd give the owner.

> **Warning:** `write` and `exec` let agents run shell commands and change files on the host, and so can everyone you let in through visibility. A local agent's sandbox sees the `runpane workspace ... exec` call, not what runs on the other machine.

## Paths across Windows, WSL, and macOS

`read`, `write`, and `exec --cwd` take any path form and translate it on the machine that runs the request:

- `C:\Users\me\notes.md` and `/mnt/c/Users/me/notes.md` reach the same Windows file.
- On Windows, WSL paths such as `/home/me/repo/README.md` are read through `\\wsl.localhost\<distro>\...` with the default distribution (the one `wsl -l -v` marks with `*`).
- `~` is the home directory of the machine that runs the request.

`exec` runs in the shell Pane uses for terminals on that machine, prints stdout and stderr, ends with a line naming the machine, OS, shell, and exit code, and exits with the command's exit code. Add `--json` for all of these as fields. Pass the command as one quoted string, because several words after `--` are joined with spaces.

Without a machine name, `read`, `write`, and `exec --cwd` send a path that can't exist on this machine to the one joined machine it fits, so `C:\...` on a Mac goes to your Windows PC. When another command gets a missing file or Session that lives on another machine, its error names the machine and the exact `runpane workspace` command to use.

## Workspaces and pairing codes

| | Workspaces | Pairing codes |
|---|---|---|
| For | Your machines, from the CLI or desktop app; your tailnet if you allow it | Browsers and devices on another Tailscale account |
| Trust | Tailscale identity, visibility, and an optional password | A `pane-remote://` code per device |
| Serves | Desktop Pane's `~/.pane` | The [remote daemon](/docs/remote-daemon)'s data directory |
| Port | 8443 | 443 |
| Setup | None | `runpane setup`, then paste the code |

Machine commands (`read`, `write`, `exec`) work for Tailscale identity and linked computers only. A phone's sign-in or a `pane-remote://` code can't run them.

See the [runpane CLI](/docs/runpane-cli) for every other command.
