Self-hosted relay · Docker

Run your own Touchless relay

Touchless normally connects your phone and your AI through the Touchless cloud relay. You can run that relay on your own computer instead, so your phone's commands never leave your home network, and you can use a local AI (LM Studio) with no cloud account. About 10 minutes, no code and no build.

AI app / LM Studio │ ▼ Touchless relay (Docker, on your computer) ▲ │ your Wi-Fi Touchless app (on your phone)
What you need1 · Install Docker2 · Download 3 · Start4 · Check5 · Phone6 · Your AI Cloud AIs (HTTPS)Everyday useTroubleshootingSecurity

What you need

  • A computer that stays on: Windows 10/11, macOS or Linux (amd64). Apple Silicon Macs work through Docker's emulation.
  • Docker: Docker Desktop on Windows/macOS, or Docker Engine with Compose on Linux (step 1).
  • Touchless on your Android phone: download the latest version.
  • Phone and computer on the same Wi-Fi. A guest network often stops devices from seeing each other.
  • Optional: LM Studio (lmstudio.ai) with a model that supports tool use.

Only want ChatGPT or Claude on the web? Keep the Touchless cloud relay (the default): it already works. A self-hosted relay is for keeping traffic at home, a local AI, or full control.

Step 1 · Install Docker

W

Windows 10/11

  1. Download Docker Desktop from docker.com/products/docker-desktop and run the installer. Keep Use WSL 2 checked.
  2. Restart the computer if it asks. If Windows says WSL needs an update, open PowerShell and run wsl --update.
  3. Open Docker Desktop, accept the terms, and wait until the bottom-left says Engine running.
  4. In Docker Desktop › Settings › General, turn on Start Docker Desktop when you sign in, so the relay comes back after a restart.
M

macOS

  1. Download Docker Desktop for your Mac (Apple chip or Intel) from docker.com, open the .dmg and drag Docker to Applications.
  2. Open Docker, allow what it asks, and wait for Engine running.
L

Linux

Install Docker Engine and the Compose plugin, then let your user run Docker (log out and back in afterwards):

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Check it works: open a terminal (PowerShell on Windows) and run docker compose version. It should print a version number.

Step 2 · Download the Touchless bundle

Download touchless-docker.zip and unzip it anywhere, for example Documents\touchless-docker. The relay image itself (~80 MB) is downloaded and checksum-checked by the wizard in the next step; you don't download it by hand.

Step 3 · Start the relay (one click)

1

Run the wizard

Windows: double-click start.cmd in the folder.

macOS / Linux: open a terminal in the folder and run:

chmod +x start.sh stop.sh && ./start.sh
2

Answer two questions

  1. How will your phone reach this computer? Press Enter for 1 · Same Wi-Fi (recommended). It finds your computer's Wi-Fi address by itself, for example 192.168.1.50.
  2. Enable LM Studio without a token? Answer y only if LM Studio runs on this same computer and it's your own, trusted computer. Otherwise press Enter.

Windows may ask whether Docker may use the network: allow it for Private networks only.

3

The setup page opens

Your browser opens http://127.0.0.1:8789: your exact relay address with Copy buttons, a live phone connected light, and the relay settings. The same steps are printed in the window under WHAT TO DO NOW. You can open this page again any time.

Step 4 · Check the phone can reach the computer

On the phone, open the browser and go to your relay address followed by /healthz, for example:

http://192.168.1.50:8787/healthz

It must show ok. If it doesn't load, go to Troubleshooting before going on.

Step 5 · Point Touchless at your relay

1

Open the relay setting

Touchless › Settings › Advanced › Relay server, then tap Custom / self-hosted.

2

Type the address

Relay address: http://192.168.1.50:8787, your own address from the setup page, without /mcp at the end.

3

Allow the home-network address

Turn on Allow LAN-only cleartext (http/ws). It's needed for an http:// address on your own Wi-Fi. Leave it off for an https:// address.

4

Save & connect

Touchless reconnects to your computer, and the setup page's phone connected light turns on. Keep the AI agent switch on the Touchless home screen On.

This screen is protected: an AI can't change it for you. You do this step yourself, once.

Step 6 · Connect your AI

LM Studio on the same computer (simplest)

  1. Load a model that supports tool calling (for example a Qwen 3 "instruct" model) and raise Context Length to at least 16384: Touchless has many tools.
  2. Turn on LM Studio without a token on the setup page (or answer y in the wizard).
  3. In LM Studio open Program › Install › Edit mcp.json and add (keep any servers you already have):
{
  "mcpServers": {
    "touchless": { "url": "http://127.0.0.1:8788/mcp" }
  }
}

Any computer on your Wi-Fi (with an API key)

  1. On the phone: Settings › AI connection › Copy address. It looks like http://192.168.1.50:8787/mcp/abc123…
  2. Same screen › API key: give it a name (e.g. LM Studio), create it and copy the key (tlk.…). It's shown once; treat it like a password.
  3. In your AI app's MCP settings:
{
  "mcpServers": {
    "touchless": {
      "url": "http://192.168.1.50:8787/mcp/PASTE-YOUR-DEVICE-ID",
      "headers": { "Authorization": "Bearer tlk.PASTE-YOUR-API-KEY" }
    }
  }
}

You can revoke the key any time on the same screen.

Test it: ask your AI "Call the Touchless get_device_info tool and tell me what it returns." You should see your phone's model and battery level.

Cloud AIs (ChatGPT, Claude on the web)

A cloud AI runs on the internet and can't reach a 192.168.x.x address. Choose one:

  • Keep the Touchless cloud relay (the default): simplest.
  • Your own domain with HTTPS: point a domain's DNS at this computer, open ports 80 and 443 to it, and run start.cmd public (Windows) or ./start.sh public. Caddy gets a free HTTPS certificate automatically. In Touchless use https://your-domain with the cleartext switch off, and give the AI the address from Settings › AI connection.
  • A VPN (Tailscale, WireGuard) for your own devices only: no port to open.

Everyday use

To…WindowsmacOS / Linux
Start (after a reboot it starts by itself)start.cmd./start.sh
Stopstop.cmd./stop.sh
Update to the newest relaystart.cmd update./start.sh update
Change settingsopen http://127.0.0.1:8789 on the computer
See the logdocker compose logs -f relay
Go back to the Touchless cloudSettings › Advanced › Relay server › Touchless cloud (Default)

Your settings and the relay's small state live in the Docker volume relay-data, so stopping, restarting and updating keep them. docker compose down -v deletes that volume.

Troubleshooting

The phone can't reach the relay

  1. Same network? The phone must be on the same Wi-Fi as the computer: not mobile data, not a guest Wi-Fi.
  2. Right address? On Windows run ipconfig and use the Wi-Fi adapter's IPv4 address. Not 127.0.0.1, not 172.x (that's Docker/WSL). If it changed, run start.cmd lan again and update the phone.
  3. Windows network set to Private? In PowerShell run Get-NetConnectionProfile. If your home Wi-Fi says Public, open PowerShell as Administrator and run: 
    Set-NetConnectionProfile -InterfaceIndex <number> -NetworkCategory Private
  4. Firewall. Windows, PowerShell as Administrator: 
    New-NetFirewallRule -DisplayName "Touchless relay 8787" -Direction Inbound -Protocol TCP -LocalPort 8787 -RemoteAddress LocalSubnet -Profile Private -Action Allow
    macOS: System Settings › Network › Firewall › allow Docker. Linux (ufw): 
    sudo ufw allow from 192.168.0.0/16 to any port 8787 proto tcp
  5. Is the port published? docker ps must list <your-IP>:8787->8787/tcp. If you see only 127.0.0.1:8787, run start.cmd lan.
  6. Touchless says the address isn't encrypted: turn on Allow LAN-only cleartext (http/ws).
MessageWhat it means
No phone connectedThe relay runs but the phone isn't on it yet: finish step 5 and keep AI agent On.
401Wrong, revoked or missing API key, or the address isn't the one from Copy address.
403Touchless's IP access list blocks that computer: tap the IP chip on the Touchless home screen.
Container name already in useAnother copy of the relay is running: docker stop touchless-relay, then start again.
Port already in useSomething else uses 8787: change RELAY_PORT in .env, then start again.
Image download fails (company proxy)Download touchless-relay-image.tar.gz and its .sha256 from the releases page into the folder and run the wizard again.

Security

  • The relay listens on this computer and, in Wi-Fi mode, on your Wi-Fi address only, never on all interfaces. Never port-forward 8787 or 8788 on your router.
  • A home-network http:// address isn't encrypted. Use it only on your own trusted Wi-Fi; for anything else use HTTPS.
  • AIs sign in with a sign-in you approve on the phone, or an API key you create in Touchless and can revoke. The relay stores only hashes and never prints keys.
  • The settings page (127.0.0.1:8789) and LM Studio without a token (127.0.0.1:8788) answer only on this computer.
  • LM Studio without a token lets any program on this computer control the paired phone: enable it only on a personal computer you trust.
  • Touchless's own safety settings (approval mode, protected screens, IP access, active hours) work the same on your relay as on the cloud.

Never post your API key or relay address publicly, and never put the key in the URL.