# CatStack Remote connector — 0.2.0 beta

Download the controller, MeowOS image, and remote connector:
https://remote.catstack.sh/downloads

## Windows: download, sign in, connect

1. Keep your existing CatStack controller running on this computer. Its local
   dashboard normally opens at http://127.0.0.1:8888.
2. Download and open `CatStackRemoteConnector.exe` on this same computer.
   A Meowcoin-branded setup page opens in your browser.
3. Choose **Sign in & connect**. A CatStack Remote sign-in tab opens. Sign in
   or create a beta account, check the matching code on the connector page,
   and choose **Connect controller**. Only approve a connection you started.
4. The connector saves the connection privately. When it says **Controller
   connected**, choose **Open remote dashboard**.

No config file, copied token, administrator access, or router rule is needed.
Your password is entered only on https://remote.catstack.sh. If your account
has 2FA enabled, use its authenticator code when signing in; 2FA is optional.
Passwords require at least eight characters.

**Start automatically when I sign in to Windows** is selected during setup.
Leave it selected for automatic reconnection, or clear it to run manually.
The connector installs a private per-user copy and a Windows sign-in startup
entry when enabled. CatStack itself must also stay running.

Closing the browser does not stop the connector. Open the connector again to
see its status; it reuses the running instance. Choose **Stop connector** on
that status page to stop it. If automatic startup is enabled it will run at
your next Windows sign-in; it can be disabled in Windows Settings > Apps > Startup.

## Linux desktop or headless controller

Download the Linux binary on the controller and run:

```bash
chmod 700 ./CatStackRemoteConnector-linux-x86_64
./CatStackRemoteConnector-linux-x86_64
```

On a desktop, the browser setup page opens. On a headless controller, the
connector prints a sign-in link and a short code. Open that link on any device,
sign in, confirm the matching code, and choose **Connect controller**. The
connector saves the connection automatically and keeps running in the terminal.
Use Ctrl+C to stop it. Run the same binary again to reconnect with saved details.
To replace an expired/revoked connection, run it with `--pair` and sign in again.
Linux automatic startup is not installed by this beta.

Linux x86_64 requires glibc 2.36 or newer, such as Debian 12 or Ubuntu 24.04.
Windows requires Windows 10/11 x64. Outbound HTTPS/WebSocket port 443 is needed.

## Troubleshooting

- **CatStack not found:** start the CatStack controller, then choose **Check
  again**. Install this connector on the controller computer, not a separate rig.
- **Sign-in expired:** requests last ten minutes. Return to the connector and
  choose **Sign in & connect** again.
- **Existing connector:** one controller is supported per beta account.
  Approving another replaces the previous connection; existing installs are
  untouched until you approve that replacement.
- **Connection revoked:** sign in again through the connector. Headless Linux
  users can use `--pair`.
- **No browser opens on a Linux desktop:** use `--pair` to print a link instead.
- **Blank dashboard from an older build:** download this connector again and
  check the SHA-256. This release includes the complete-response relay fix.
- **Windows startup unavailable:** keep the connector running and open it again
  after sign-in. The local status page reports startup installation failures.

Connection details are stored in `%LOCALAPPDATA%\CatStackRemote` on Windows
and `$XDG_CONFIG_HOME/catstack-remote` (normally `~/.config/catstack-remote`) on
Linux. These folders are private to your account. Do not share their contents.
The gateway keeps only the token's hash; passwords are never stored by the connector.
There is no automated password/authenticator recovery in this beta.

## Existing and advanced installations

Existing `--config /path/to/config.json` installations continue to work and
do not need migration. Manual token issuance remains under **Connector setup >
Advanced: manual token setup**. Use `--local http://127.0.0.1:PORT` only if your
controller uses a different local port. Non-loopback controller URLs are refused.

The source ZIP includes `connector.py`, its local UI assets, and requirements.
Extract the whole ZIP, install its requirements in a virtual environment, and
run `python connector.py`. The separate source `.py` asset supports headless
`--pair` and existing `--config` use; the browser UI needs the ZIP's assets.

The Windows beta is not Authenticode signed. Check `SHA256SUMS.txt` before use.
Report errors with connector/OS versions; omit tokens, private host details,
wallets, and SSH material. Your rig database stays on your controller.