Redock
中文 Download Free

Redock User Setup Guide

This guide helps you connect Redock to your Mac, VPS, or development server and quickly experience the core workflow: open a remote terminal, enter a project directory, start an AI coding agent, check Git state, and keep long-running work alive with Redock's built-in tmux integration.

The recommended first quick start is to use the same local network at home. This path has the least setup and is ideal for trying Redock from the couch or bed before you configure any public or outdoor access.

  1. Enable Remote Login on your Mac. This turns on SSH.
  2. Connect your iPhone or iPad and Mac to the same Wi-Fi.
  3. When adding a Host in Redock, tap Discover Local Devices so Redock can scan the same LAN and prefill Host and Port.
  4. If no device is found, find the Mac's LAN IP manually. It usually looks like 192.168.x.x; enter it as Host and use Port 22.
  5. Enter your Mac username and start with Password for Auth.
  6. After connecting, enter a project directory and try the AI coding agent, Git, Redock's built-in tmux integration, and snippets.

After this LAN quick start works, configure Tailscale, ngrok, or public port forwarding for outdoor use, cellular networks, office networks, or long-term remote access. Do not expose weak-password SSH to the public internet.

1. What You Need

Prepare the following:

  • A Mac, Linux machine, VPS, or NAS that can accept SSH connections.
  • Redock installed on your iPhone or iPad.
  • The username for the remote machine.
  • An authentication method: use your account password for the quick start; switch to an SSH private key for long-term use.
  • A network path: same Wi-Fi/LAN, Tailscale, ngrok TCP tunnel, or public IP/port forwarding.
  • Optional tools on the remote machine: git, tmux, claude, codex, opencode, project dependencies, and package managers. tmux only needs to be installed on the remote host; Redock handles creating, attaching, and restoring sessions.

Redock connects to your remote host. Claude Code, Codex, opencode, Git, Node, Python, Rust, and other commands must be installed on that remote host, not on your iPhone.

2. Enable Remote Login on macOS

If your development machine is a Mac, enable the built-in macOS SSH service first.

  1. Open System Settings on the Mac.
  2. Go to General > Sharing.
  3. Find Remote Login and open its detail settings.
  4. Turn on Remote Login.
  5. Prefer Only these users and allow only your development account.
  6. Note the SSH command shown by macOS. It usually looks like:
ssh username@hostname

If you want Redock to browse files over SFTP, Remote Login also enables SFTP.

You can confirm your macOS username in Terminal:

whoami

Check the hostname:

hostname

Check the current Wi-Fi LAN IP:

ipconfig getifaddr en0

If you use Ethernet, the interface may not be en0. In that case, check the active IP address in System Settings > Network.

Test on the Same Wi-Fi First

If you are adding the Host directly in Redock, first tap Discover Local Devices. Redock scans SSH devices on the same LAN and lets you select one to prefill Host and Port. Allow the iOS Local Network permission prompt; otherwise Redock cannot scan nearby devices.

If no device is found, or if you want to verify manually, test SSH from another computer on the same network:

ssh username@192.168.1.23

Replace username with your Mac username and 192.168.1.23 with your Mac LAN IP. If this works, use the same Host, Port, Username, and authentication method in Redock.

The default SSH port is 22.

Use SSH Keys

Redock supports generated keys and imported private keys.

If you generate a key in Redock:

  1. Add a Host in Redock and choose SSH Key.
  2. Select Generate Key.
  3. Copy the public key shown by Redock.
  4. On the Mac, run:
mkdir -p ~/.ssh
chmod 700 ~/.ssh
touch ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
pbpaste >> ~/.ssh/authorized_keys

pbpaste >> ~/.ssh/authorized_keys appends the public key from your clipboard. Make sure your clipboard contains the Redock public key before running it.

If you import an existing private key into Redock, first add the matching public key to ~/.ssh/authorized_keys on the remote host.

3. Choose a Remote Access Method

Redock only needs a reachable SSH address. Choose the network path that fits your situation.

3.1 Same Wi-Fi or LAN

This is the simplest quick start for home, office, or hotspot use. A typical scenario is using Redock from the couch, bed, or anywhere away from your desk while your iPhone or iPad and Mac are still on the same Wi-Fi.

Redock Host settings:

  • Host: prefer Discover Local Devices to prefill it; or enter the Mac LAN IP manually, for example 192.168.1.23
  • Port: 22
  • Username: your Mac username
  • Auth: Password. After it works, prefer SSH Key
  • Connection Mode: SSH

This has low latency and minimal setup, so it is the best way to experience the product quickly. Local discovery also reduces the need to look up the IP address and port manually. The limitation is that it only works while your devices are on the same network, and the LAN IP may change.

If your router supports DHCP reservation, reserve a stable LAN IP for the Mac.

3.2 Tailscale

After Redock works on the same Wi-Fi, use Tailscale when you want to connect from outdoors, cellular networks, office networks, or another city. It does not directly expose SSH to the public internet. Instead, it puts your iPhone, iPad, Mac, VPS, and other machines into the same private tailnet. Redock then connects to the Mac's standard SSH service through the Tailscale IP or MagicDNS name.

Setup

  1. Install Tailscale on the Mac and sign in.
  2. Install Tailscale on the iPhone or iPad and sign in to the same account or tailnet.
  3. Confirm both devices are connected.
  4. Keep Remote Login enabled on the Mac.
  5. Find the Mac's Tailscale IP in the Tailscale client or Machines page. It usually looks like 100.x.y.z.
  6. If MagicDNS is enabled, you can also use the machine name, such as my-mac, or the full tailnet domain name.

Redock Host settings:

  • Host: the Mac Tailscale IP, for example 100.72.10.25, or its MagicDNS name
  • Port: 22
  • Username: your Mac username
  • Auth: Password or SSH Key
  • Connection Mode: SSH

About Tailscale SSH

Tailscale SSH is a Tailscale feature that manages SSH authentication and authorization inside your tailnet. It is different from macOS Remote Login plus a normal SSH password or key.

The most reliable Redock setup is:

  1. Use Tailscale for private network connectivity.
  2. Use macOS Remote Login for the standard SSH server.
  3. Use normal SSH username, password, or key authentication in Redock.

Only enable Tailscale SSH if you understand its authentication behavior and have confirmed that your current SSH client setup is compatible.

Best Use Cases

  • You often move between cellular and Wi-Fi networks.
  • You do not want to configure router port forwarding.
  • You do not want to expose SSH to the public internet.
  • You need stable access to a home Mac, office machine, or private server.

3.3 ngrok TCP Tunnel

ngrok is useful for temporary access when you need to expose local SSH through a public TCP address. For example, you may want short-term access to a Mac at home or to a machine without a public IP.

Important: an ngrok TCP endpoint creates a public entry point. Use a strong password or SSH key, and keep it running only when needed.

ngrok TCP endpoint availability and static address support depend on your ngrok account and plan. Current ngrok documentation says TCP endpoints on the free plan require adding a valid payment method. If ngrok tcp 22 fails, check your ngrok Dashboard plan and billing status.

Setup

Install ngrok on the Mac and connect it to your account:

brew install ngrok
ngrok config add-authtoken YOUR_NGROK_AUTHTOKEN

Start a TCP tunnel to local SSH:

ngrok tcp 22

ngrok will print a forwarding address similar to:

Forwarding  tcp://0.tcp.ngrok.io:12345 -> localhost:22

Redock Host settings:

  • Host: 0.tcp.ngrok.io
  • Port: 12345
  • Username: your Mac username
  • Auth: Password or SSH Key
  • Connection Mode: SSH

Do not include tcp:// in the Host field. Put the ngrok port in the Port field.

Keep ngrok Stable

Free or random TCP addresses may change. When the address changes, update the Redock Host.

If you need a stable address, configure a reserved TCP address in ngrok or install the ngrok agent as a background service. Availability depends on your ngrok account and plan.

3.4 Router Port Forwarding or Public IP

If your Mac or server has a public IP, or you can configure router port forwarding, Redock can connect directly to public SSH.

This is not recommended as the first setup for most users. Public SSH is continuously exposed to the internet and requires stricter security.

Typical setup:

  1. Enable Remote Login on the Mac.
  2. Forward an external router port to the Mac's port 22.
  3. In Redock, use the public domain/IP and external port.

Example:

  • Public endpoint: home.example.com:2222
  • Router forwarding: home.example.com:2222 -> 192.168.1.23:22
  • Redock Host: home.example.com
  • Redock Port: 2222

Recommendations:

  • Prefer SSH keys.
  • Restrict allowed Remote Login users.
  • Do not allow weak passwords.
  • Keep macOS and router firmware updated.
  • Prefer Tailscale whenever it fits your workflow.

4. Add a Host in Redock

In Redock:

  1. Open Launch.
  2. Add a Host.
  3. Enter a Name, such as MacBook Pro, Home Mac, or VPS.
  4. Enter Host and Port.
  5. Enter Username.
  6. Select SSH as the initial Connection Mode.
  7. Choose Password or SSH Key.
  8. If you want recoverable sessions, enable tmux in the Host settings after installing tmux on the remote host.
  9. Save and connect.

Start with SSH for the first setup. Mosh is useful on mobile or unstable networks, but it requires mosh to be installed on the remote host and requires UDP connectivity. Get SSH working first, then enable Mosh if you need it.

5. Experience the Core Workflow

After the connection succeeds, try the following workflow.

Enter a Project Directory

cd ~/Projects/your-project

If the project uses Git:

git status
git branch
git pull

Start an AI Coding Agent

Choose the tool installed on your remote host:

claude
codex
opencode

If you already have a previous session, use the corresponding resume command or slash command. Redock's AI coding agent snippets include common entries such as:

/resume
/status
/model
/exit

Different agents support different commands. Redock snippets are fast input helpers; they do not determine whether the active tool supports a command.

Choose an Action Run Mode

Actions are Redock entries for saved commands. When you create or edit an Action, choose how it should run:

  • Terminal Interactive: opens a terminal workspace and keeps the session available for further input. Use it for Claude Code, Codex, opencode, long-lived shells, REPLs, log following, or any command that needs ongoing conversation or manual intervention. If the Action launches an AI agent, this is usually the right mode.
  • Quick Task: runs the command over SSH, waits for it to finish, and saves the output as a Run record. Use it for short scripts, health checks, git status, npm test, pytest, pre-deploy checks, cleanup scripts, and tasks with a clear endpoint. It does not become a terminal session; it is for tap once and review the result.
  • Background Long Task: starts the command inside remote tmux and saves logs so it can keep running after the phone disconnects. Use it for builds, long tests, batch jobs, service startup, long agent runs, data migrations, or anything that may take a while. The remote Host must have tmux installed; after launch, open the background session or saved log from the Run detail.

Use this rule of thumb:

  • Need to keep typing, talk to an agent, or watch live terminal state: choose Terminal Interactive.
  • Command finishes quickly and you only need status plus output history: choose Quick Task.
  • Command may run for a long time and should continue after leaving Redock: choose Background Long Task.

Use Git Snippets

The Git snippet tab is useful for high-frequency commands on mobile:

git status
git diff
git log --oneline --decorate --graph -20
git add .
git commit -m ""
git pull --rebase
git push

Before running destructive commands on mobile, confirm the current directory and branch. Commands such as git reset --hard and git clean -fd should not be one-tap habits.

Use Redock's Built-In tmux for Persistent Work

If tmux is installed on the remote host, enable tmux in the Host settings. Redock will then expose tmux session entry points when you connect. You do not need to type tmux new or tmux attach manually for the basic recovery workflow.

After tmux is enabled, Redock uses the current Host, Project, or Action context to:

  • Show a connection picker when recoverable tmux sessions exist, so you can quickly return to an existing session.
  • Create a new tmux session when no matching session exists and associate it with the current work context.
  • Prefer restoring the original tmux runtime on reconnect, so long-running work is not lost just because the phone goes to the background or the network briefly drops.
  • Provide built-in tmux snippets for common pane splitting and pane navigation commands.

A practical layout is one pane for the AI agent and another pane for logs, tests, or Git diff. Advanced users can still type tmux commands directly in the terminal, but for daily create, attach, and restore flows, prefer the Host tmux switch and Redock's connection picker.

6. Configure Speech Input

Redock speech input turns your recording into text and places the result in the bottom terminal input area. You can review and edit it before pressing Return or the send button. It is useful for:

  • Dictating longer AI agent prompts on mobile.
  • Quickly drafting Git commit messages, test plans, or error context.
  • Entering natural-language instructions when typing is inconvenient, then sending them to Claude Code, Codex, opencode, or another agent installed on the remote host.

Apple Speech is the default and does not require an API key. It works for simple Chinese or English dictation, but it is not always smart enough for mixed Chinese, English, command names, paths, and code symbols. If you often dictate agent prompts or mixed-language technical text, switch to a model-based speech provider in My / Speech.

Redock currently supports:

  • Apple: system speech recognition, no extra configuration.
  • OpenAI: OpenAI speech-to-text models, useful for multilingual and technical dictation.
  • Volcengine Doubao: Volcengine Doubao speech recognition large model, useful for Chinese and mixed Chinese/English dictation.
  • OpenAI Compatible: use a compatible transcription API by entering a Base URL, model name, and API key.

API keys are stored in Apple Keychain. In free or local mode, they stay on this device. With Pro and iCloud Sync enabled, they can sync through iCloud Keychain across devices signed in to the same Apple account.

Configure OpenAI Speech

  1. Open the OpenAI Platform API Keys page.
  2. Create a new secret key, or use an existing valid key.
  3. Make sure the account or project has available quota.
  4. In Redock, open My / Speech.
  5. Set Speech Provider to OpenAI.
  6. Choose a model:
    • Fast Transcribe: the default, using gpt-4o-mini-transcribe; good for everyday speed and cost.
    • Accurate Transcribe: uses gpt-4o-transcribe; better when accuracy matters more.
    • Diarize: uses gpt-4o-transcribe-diarize; mainly for identifying speakers, usually unnecessary for single-person terminal input.
  7. Paste the OpenAI API key into API Key.
  8. Return to the terminal workspace, tap the speech button, record, and review the transcript before sending it.

Configure Volcengine Doubao Speech

  1. Sign in to the Volcengine console and open the Doubao Speech console.
  2. Enable the speech recognition large model service and make sure the fast recorded-file recognition API is available.
  3. Get the APP Key from the console.
  4. Confirm the Resource ID. Redock defaults to:
volc.bigasr.auc_turbo
  1. In Redock, open My / Speech.
  2. Set Speech Provider to Volcengine Doubao.
  3. Set Resource ID to a resource ID available in your console. Start with the default value in most cases.
  4. Paste the Volcengine key into APP Key.
  5. Return to the terminal workspace, tap the speech button, and test transcription.

If you prefer another speech provider or already use a transcription service, send feedback from Redock. We will prioritize providers based on real user demand.

7. Troubleshooting

Connection Refused

The target address is reachable, but SSH is not listening on that port.

Check:

  • Remote Login is enabled on the Mac.
  • The Redock Port is correct. Default SSH is 22.
  • The ngrok tunnel is still running.
  • Router port forwarding points to the correct LAN IP.

Connection Timed Out

The network path is not reachable.

Check:

  • The iPhone or iPad is connected to Tailscale.
  • The Mac is connected to Tailscale.
  • The Host value is the correct IP or hostname.
  • Cellular, office, or public Wi-Fi networks are not blocking the connection.
  • The ngrok forwarding address has not changed.

Authentication Failed

The username, password, or key does not match.

Check:

  • Username is the remote machine's system username, not your Apple ID, email, or device name.
  • Password is the remote account password.
  • The Redock public key has been added to ~/.ssh/authorized_keys on the remote host.
  • ~/.ssh and authorized_keys permissions are correct.

Hostname Does Not Resolve

If my-mac.local, a MagicDNS name, or a custom domain is unreliable, test with an IP address first.

For Tailscale, try the 100.x.y.z Tailscale IP first. After that works, switch to the MagicDNS name if you prefer.

AI Agent Command Not Found

Redock connects to the remote host. Install the agent command on that host and verify:

which claude
which codex
which opencode

If a command is missing, install the corresponding tool on the remote host and confirm the shell PATH is available in your terminal session.

tmux Command Not Found

On macOS, install tmux with Homebrew:

brew install tmux

On Linux, use your distribution's package manager, for example:

sudo apt install tmux

After installing tmux, return to Redock and enable tmux in the Host settings. Basic create, attach, and restore flows do not require typing tmux commands manually. If the connection picker does not show tmux sessions, first confirm that tmux is enabled for that Host.

Speech Transcription Fails or Is Inaccurate

Check:

  • iOS has granted Redock microphone access.
  • For Apple Speech, iOS has granted Speech Recognition permission.
  • For OpenAI or Volcengine Doubao, the matching provider is selected in My / Speech and the API key is filled in.
  • The OpenAI or Volcengine account has available quota, permissions, and the correct resource ID.
  • For mixed Chinese/English, command names, paths, or code symbols, try a model-based provider such as OpenAI or Volcengine Doubao.

8. Recommended Setups

Personal Mac Quick Start at Home

  • Network: same Wi-Fi or LAN
  • Redock Connection Mode: SSH
  • Auth: start with Password, switch to SSH Key for long-term use
  • Session: enable Redock tmux in the Host settings
  • Workflow: from the couch, bed, or away from your desk, use Discover Local Devices to prefill the Host, or connect to the Mac through 192.168.x.x, enter a project, open an agent, check Git, and restore tmux sessions.

This is the best first setup for trying Redock. It needs no extra network service and quickly shows whether the mobile workflow fits your development style.

Personal Mac Across Networks

  • Network: Tailscale
  • Redock Connection Mode: SSH
  • Auth: SSH Key
  • Session: enable Redock tmux in the Host settings
  • Workflow: let Redock create and restore tmux sessions for common projects, then return to them from the connection picker on mobile.

This is the recommended long-term remote-access setup. It avoids public SSH exposure and works well on mobile networks.

Temporary Access to a Home or Office Mac

  • Network: ngrok TCP tunnel
  • Redock Connection Mode: SSH
  • Auth: SSH Key
  • Note: stop ngrok when you are done.

Use this for short sessions. For long-term access, prefer Tailscale or a stable public server setup.

VPS or Cloud Server

  • Network: public IP or domain
  • Redock Connection Mode: SSH
  • Auth: SSH Key
  • Session: enable Redock tmux in the Host settings
  • Security: restrict SSH users, avoid weak passwords, and keep the system updated.

VPS hosts usually already have public IP addresses. The main work is SSH hardening.

9. Best Practices

  • Prefer Tailscale for everyday remote access to reduce public SSH exposure.
  • Use SSH keys for any public endpoint.
  • In macOS Remote Login, choose Only these users and allow only the accounts you need.
  • Use clear Host names, such as Home Mac - Tailscale and VPS - Prod.
  • Create separate Hosts for LAN, Tailscale, and ngrok addresses instead of repeatedly editing one Host.
  • Enable Redock tmux on the Host and run long tasks in recoverable tmux sessions instead of depending on the mobile connection to stay alive.
  • Keep one project directory as the working root, then start the agent, Git commands, and tests from there.
  • Use snippets or quick actions for frequent commands, but leave room for manual confirmation before destructive operations.
  • On unstable mobile networks, confirm the current directory, branch, and connection state; when recovering long-running work, return to the matching tmux session from the connection picker.
  • Keep the remote Mac powered on and connected. Adjust power settings if sleep prevents remote access.
  • Avoid storing unnecessary SSH credentials on untrusted devices or networks.

10. Official References