Moshi

https://getmoshi.app/docs
Admin
Moshi is a mobile terminal app for iOS and Android that enables developers to monitor, control, and...
Tokens:24,056
Snippets:377
Trust Score:7.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Moshi Hook on Linux or WSL

Source: https://getmoshi.app/docs/hooks

Install via the provided script and start the service.

```bash

$curl -fsSL https://getmoshi.app/install.sh | sh
$moshi-hook pair --token <token from Moshi>
$moshi-hook install
$moshi-hook serve

```

--------------------------------

### Install Moshi Hook on macOS

Source: https://getmoshi.app/docs/hooks

Use Homebrew to install and start the Moshi hook service after pairing with a token.

```bash

$brew tap rjyo/moshi
$brew trust rjyo/moshi
$brew install moshi-hook
$moshi-hook pair --token <token from Moshi>
$moshi-hook install
$brew services start moshi-hook

```

--------------------------------

### Manually install moshi-hook binary

Source: https://getmoshi.app/docs/troubleshooting

Perform these steps to manually extract and install the binary if the automated script is blocked by network challenges.

```bash
$tar -xzf moshi-hook_Linux_x86_64.tar.gz
$sudo mv moshi-hook /usr/local/bin/
$moshi-hook pair --token <token>
$moshi-hook install
```

--------------------------------

### Agent Prompt with URL

Source: https://getmoshi.app/docs/files

Example of providing a direct instruction alongside an uploaded file URL to an agent.

```text
$> Review this screenshot and tell me which UI element is misaligned: https://...
```

--------------------------------

### Start an agent session in Herdr

Source: https://getmoshi.app/docs/herdr

Commands to navigate to a project directory and initialize agent sessions.

```bash
$cd ~/projects/app
$claude
$codex
```

--------------------------------

### Configure macOS agent hooks

Source: https://getmoshi.app/docs/install

Commands to install and start the moshi-hook service on macOS for agent notifications.

```bash
$brew tap rjyo/moshi
$brew trust rjyo/moshi
$brew install moshi-hook
$moshi-hook pair --token <token from Moshi>
$moshi-hook install
$brew services start moshi-hook
```

--------------------------------

### Manage Zellij Sessions

Source: https://getmoshi.app/docs/zellij

Commands for starting, attaching, and creating persistent Zellij sessions.

```bash
$zellij --session moshi
```

```bash
$zellij attach moshi
```

```bash
$zellij attach --create moshi
```

--------------------------------

### Install Moshi host packages

Source: https://getmoshi.app/docs/install

Commands to install the moshi-hook utility and dependencies on macOS or Debian-based Linux distributions.

```bash
# macOS
$brew tap rjyo/moshi
$brew trust rjyo/moshi
$brew install moshi-hook
$brew install mosh tmux
# Debian, Ubuntu, or WSL on Windows
$curl -fsSL https://getmoshi.app/install.sh | sh
$sudo apt install mosh tmux
```

--------------------------------

### Install Herdr

Source: https://getmoshi.app/docs/herdr

Use the provided shell script to install Herdr on Linux or macOS.

```bash
curl -fsSL https://herdr.dev/install.sh | sh
```

--------------------------------

### Start or Attach to Herdr

Source: https://getmoshi.app/docs/herdr

Commands to initialize the default Herdr server or manage named persistent sessions.

```bash
herdr
```

```bash
herdr session list
herdr session attach work
herdr session attach side-project
herdr session stop work
```

--------------------------------

### Instructional prompts for pasted files

Source: https://getmoshi.app/docs/image-paste

Examples of how to pair a pasted file path with a direct instruction for a coding agent when Ctrl+V is not supported.

```text
$> Review this screenshot and tell me which UI element is misaligned: ~/.moshi/uploads/2026-05-11-misalign.png
$> Summarize this log: ~/.moshi/uploads/2026-05-21-server.log
```

--------------------------------

### Start a remote session

Source: https://getmoshi.app/docs/first-session

Commands to initialize a tmux session and navigate to a project directory within the remote shell.

```bash
$tmux new -s work
$cd ~/projects/my-app
$claude
```

--------------------------------

### Start a new tmux session

Source: https://getmoshi.app/docs/scrolling

Initializes a new tmux session on the host to maintain persistent scrollback.

```bash
$tmux new -s moshi
```

--------------------------------

### Update Moshi Hook on Linux

Source: https://getmoshi.app/docs/hooks

Re-run the installation script to update the binary.

```bash

$curl -fsSL https://getmoshi.app/install.sh | sh

```

--------------------------------

### Add custom directory to PATH

Source: https://getmoshi.app/docs/troubleshooting

Append the custom installation directory to the user's .profile to ensure it is available to the login shell.

```bash
$echo 'export PATH="/custom/dir:$PATH"' >> ~/.profile
```

--------------------------------

### Initialize a durable tmux session

Source: https://getmoshi.app/docs/terminal-sessions

Use this command to start a persistent tmux session on the host, ensuring work survives network disconnections.

```bash
$tmux new -s moshi
$codex
```

--------------------------------

### Verify Grok Build hook status

Source: https://getmoshi.app/docs/debug-gateway

Check the installation and status of the moshi-hook to ensure agent session mapping is functional.

```bash
$moshi-hook version
$moshi-hook status
$moshi-hook install --target grok
```

--------------------------------

### Triggering a Session via Webhook

Source: https://getmoshi.app/docs/notifications

Example of embedding a Moshi deep link within a webhook notification payload to open a session on tap.

```bash
$curl -X POST https://api.getmoshi.app/api/webhook \
$  -H "Content-Type: application/json" \
$  -d '{"token":"YOUR_API_TOKEN","title":"Agent needs input","message":"Open my-project","data":{"type":"url","url":"moshi://tmux?session=my-project"}}'
```

--------------------------------

### Initialize Easy Pair

Source: https://getmoshi.app/docs/install

Run this command on the host machine to generate the QR code for pairing with the Moshi mobile app.

```bash
$moshi-hook host setup
```

--------------------------------

### Pair with File Storage

Source: https://getmoshi.app/docs/troubleshooting

Use file-based storage for pairing in headless environments.

```bash
$moshi-hook pair --token <token> --store file
```

--------------------------------

### Update Moshi Hook on macOS

Source: https://getmoshi.app/docs/hooks

Refresh the Homebrew tap and upgrade the installed package.

```bash

$brew update
$brew upgrade moshi-hook
$brew services restart moshi-hook

```

--------------------------------

### Launch Diff Viewer from CLI

Source: https://getmoshi.app/docs/diff-viewer

Commands to open the diff viewer for the current directory or a specific repository path.

```bash
$moshi diff .
$moshi diff ~/projects/some-repo
```

--------------------------------

### Launch project tmux sessions

Source: https://getmoshi.app/docs/install

Use the moshi command to open or attach to a tmux session in a specific directory.

```bash
$moshi .
$moshi ~/projects/app
```

--------------------------------

### Launch Git Diff Viewer

Source: https://getmoshi.app/docs/moshi-cli

Use the diff subcommand to open a local repository's git diff in the default browser.

```bash
$moshi diff .
$moshi diff ~/projects/some-repo
$moshi diff ~/projects/some-repo --no-open
```

--------------------------------

### GET /v1/transcripts

Source: https://getmoshi.app/docs/debug-gateway

Establishes a WebSocket connection to stream raw JSONL transcript rows for a specific agent session.

```APIDOC
## GET /v1/transcripts

### Description
Streams raw JSONL transcript rows from the host to the application. The stream begins with a 'backlog' message followed by 'append' events as new data is written.

### Method
GET

### Endpoint
ws://127.0.0.1:24543/v1/transcripts

### Parameters
#### Query Parameters
- **source** (string) - Required - The agent name (e.g., 'grok').
- **session** (string) - Required - The unique session ID associated with the agent.

### Response
#### Success Response (WebSocket)
- **type** (string) - Message type ('backlog' or 'append').
- **source** (string) - The agent source name.
- **entries** (array) - JSONL rows containing transcript data.

#### Error Responses
- **400** - Invalid session ID (malformed or belongs to a different source).
- **404** - Transcript not found (session ID valid but file cannot be resolved on disk).
```

--------------------------------

### Get JSON Status

Source: https://getmoshi.app/docs/troubleshooting

Retrieve status information in JSON format, excluding path diagnostics for faster preflight.

```bash
$moshi-hook status --json
```

--------------------------------

### Compare Multiplexer Environments

Source: https://getmoshi.app/docs/multiplexer

Use these commands to compare the PATH resolution between the SSH environment and the Moshi daemon environment.

```bash
$ssh <host> 'command -v herdr; command -v tmux; command -v zellij'
$moshi-hook status
```

--------------------------------

### Run Moshi Hook Diagnostics

Source: https://getmoshi.app/docs/troubleshooting

Use these commands to check the status of the daemon, view logs, or reinstall the hook.

```bash
$moshi-hook status
$moshi-hook logs -f
$moshi-hook install
```

--------------------------------

### Symlink moshi-hook to standard path

Source: https://getmoshi.app/docs/troubleshooting

Create a symbolic link to the binary in a standard directory if it is located in a custom path.

```bash
$sudo ln -sfn /custom/dir/moshi-hook /usr/local/bin/moshi-hook
```

--------------------------------

### Inspect mosh-server processes

Source: https://getmoshi.app/docs/debug-gateway

List active UDP connections to identify running mosh-server instances.

```bash
$lsof -i UDP | grep mosh
```

--------------------------------

### Define absolute mosh-server paths

Source: https://getmoshi.app/docs/troubleshooting

Use these absolute paths in the Moshi connection settings if the server binary is not found in the default system PATH.

```text
$/opt/homebrew/bin/mosh-server
$/usr/local/bin/mosh-server
```

--------------------------------

### Inspect SSH daemon processes

Source: https://getmoshi.app/docs/debug-gateway

Use these commands on the host to verify sshd processes and active network connections.

```bash
# On the host, list sshd processes:
$ps aux | grep sshd
# Verify the connection is still alive:
$ss -tnp | grep ssh
```

--------------------------------

### Configure Git for SSH Commit Signing

Source: https://getmoshi.app/docs/connections

Set up Git to use the SSH agent for signing commits instead of the default GPG format.

```bash
$git config --global gpg.format ssh
$git config --global user.signingkey "ssh-ed25519 AAAA..."
$git config --global commit.gpgsign true
```

--------------------------------

### Define a custom theme using JSON

Source: https://getmoshi.app/docs/personalization

The v1 theme format requires a version, name, mode, and specific color palette definitions.

```json
{
  "v": 1,
  "name": "My Theme",
  "mode": "dark",
  "colors": {
    "background": "#1a1b26",
    "foreground": "#c0caf5",
    "cursor": "#c0caf5",
    "black": "#15161e",
    "red": "#f7768e",
    "green": "#9ece6a",
    "yellow": "#e0af68",
    "blue": "#7aa2f7",
    "magenta": "#bb9af7",
    "cyan": "#7dcfff",
    "white": "#a9b1d6",
    "brightBlack": "#414868",
    "brightRed": "#f7768e",
    "brightGreen": "#9ece6a",
    "brightYellow": "#e0af68",
    "brightBlue": "#7aa2f7",
    "brightMagenta": "#bb9af7",
    "brightCyan": "#7dcfff",
    "brightWhite": "#c0caf5",
    "selectionBackground": "#33467c"
  }
}
```

--------------------------------

### Probe the transcript stream

Source: https://getmoshi.app/docs/debug-gateway

Connect to the transcript stream using wscat to verify JSONL data flow for a specific session.

```bash
$wscat -c "ws://127.0.0.1:24543/v1/transcripts?source=grok&session=<session-id>"
# Expected: a JSON message with type "backlog", source "grok", and entries
```

--------------------------------

### Configure firewall for Mosh

Source: https://getmoshi.app/docs/install

Commands to open the required UDP port range for Mosh traffic on common Linux firewalls.

```bash
$sudo ufw allow 60000:61000/udp
$sudo firewall-cmd --add-port=60000-61000/udp --permanent
$sudo firewall-cmd --reload
```

--------------------------------

### Verify moshi-hook in login shell

Source: https://getmoshi.app/docs/troubleshooting

Use this command to check if the login shell can resolve the moshi-hook binary path.

```bash
$ssh <host> 'sh -lc "command -v moshi-hook"'
```

--------------------------------

### Verify SSH connectivity

Source: https://getmoshi.app/docs/troubleshooting

Use this command to test basic SSH reachability from a client machine before troubleshooting Mosh.

```bash
$ssh user@host -p 22
```

--------------------------------

### Connect to events stream without session

Source: https://getmoshi.app/docs/debug-gateway

Verifies that the gateway is broadcasting server discovery events.

```bash
$wscat -c ws://127.0.0.1:24543/events
```

--------------------------------

### Connect to events stream with Mosh session

Source: https://getmoshi.app/docs/debug-gateway

Connects to the gateway using specific Mosh host and port parameters.

```bash
$wscat -c "ws://127.0.0.1:24543/events?session=mosh&moshHost=100.96.116.120&moshPort=60002"
```

--------------------------------

### Define SSH jump host format

Source: https://getmoshi.app/docs/connections

Use this format to specify jump host connections when the connection type is set to SSH.

```text
$bastion@example.com:22
$deploy@10.0.0.5:2222
```

--------------------------------

### Retrieve Tailscale Host Information

Source: https://getmoshi.app/docs/tailscale

Use these commands on the host machine to identify the tailnet address required for Moshi configuration.

```bash
$tailscale ip
$tailscale status
```

--------------------------------

### Send a notification with a hosted image

Source: https://getmoshi.app/docs/notifications

Send a notification using a URL generated from a previously uploaded image.

```bash
curl -X POST https://api.getmoshi.app/api/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "title": "Screenshot ready",
    "message": "Tap to view the result",
    "data": {
      "type": "image",
      "url": "https://i.getmoshi.app/abcde1xy"
    }
  }'
```

--------------------------------

### Verify Multiplexer Availability via SSH

Source: https://getmoshi.app/docs/troubleshooting

Check if multiplexer binaries are visible to the SSH preflight process.

```bash
$ssh <host> 'command -v tmux; command -v zellij; command -v herdr'
```

--------------------------------

### Check Daemon Binary Resolution

Source: https://getmoshi.app/docs/troubleshooting

Display the paths resolved by the daemon for multiplexer binaries to ensure they are correctly detected.

```bash
$moshi-hook status
multiplexers (daemon):
  tmux:    /opt/homebrew/bin/tmux
  zellij:  not found
  herdr:   /Users/you/.local/bin/herdr
```

--------------------------------

### POST /api/webhook

Source: https://getmoshi.app/docs/notifications

Sends a push notification to devices. Use the unified parameter to broadcast to all devices associated with a license.

```APIDOC
## POST /api/webhook

### Description
Sends a push notification to the device associated with the provided token. If `unified` is set to true, the notification is fanned out to all devices opted-in to the same Moshi license.

### Method
POST

### Endpoint
https://api.getmoshi.app/api/webhook

### Request Body
- **token** (string) - Required - The API token for the device.
- **title** (string) - Required - The title of the notification.
- **message** (string) - Required - The body content of the notification.
- **unified** (boolean) - Optional - If true, sends the notification to all devices joined to the same Moshi license.

### Request Example
{
  "token": "YOUR_API_TOKEN",
  "title": "Done",
  "message": "Build finished",
  "unified": true
}
```

--------------------------------

### Tail daemon logs

Source: https://getmoshi.app/docs/debug-gateway

Monitor gateway events in real-time by filtering the Moshi hook log.

```bash
$tail -f ~/Library/Application\ Support/Moshi/hook.log | grep gateway
```

--------------------------------

### Connect to events stream with SSH session

Source: https://getmoshi.app/docs/debug-gateway

Connects to the gateway using specific SSH connection parameters.

```bash
$wscat -c "ws://127.0.0.1:24543/events?session=ssh&sshConnection=192.168.1.10 52431 192.168.1.20 22"
```

--------------------------------

### Handle Keychain for Headless macOS

Source: https://getmoshi.app/docs/hooks

Unlock the keychain or use file-backed storage if pairing from an SSH session.

```bash

$security unlock-keychain ~/Library/Keychains/login.keychain-db
$moshi-hook pair --token <token from Moshi>
$moshi-hook pair --token <token from Moshi> --store file

```

--------------------------------

### Upload a local image

Source: https://getmoshi.app/docs/notifications

Upload a local file to Moshi to obtain a public URL for use in notifications.

```bash
curl -X POST https://api.getmoshi.app/api/v1/images/upload \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@/path/to/screenshot.png"
```

--------------------------------

### Configure tmux for OSC 52

Source: https://getmoshi.app/docs/clipboard

Required configuration in .tmux.conf to allow OSC 52 escape sequences to pass through to the host.

```text
$set -g set-clipboard on
```

--------------------------------

### Find mosh-server address and port

Source: https://getmoshi.app/docs/debug-gateway

Identifies the bind address and port for an active mosh-server process.

```bash
$lsof -i UDP | grep mosh
mosh-serv 67724 jyo 4u IPv4 ... UDP 100.96.116.120:60002
```

--------------------------------

### Manual tmux session management

Source: https://getmoshi.app/docs/tmux

Commands for manually creating or reattaching to a tmux session named 'moshi'.

```bash
$tmux new -s moshi
```

```bash
$tmux a -t moshi
```

--------------------------------

### Diagnose Cloudflare 403 errors

Source: https://getmoshi.app/docs/troubleshooting

Use this command to verify if a download failure is caused by a Cloudflare bot protection challenge.

```bash
$curl -v https://cdn.getmoshi.app/hook/v0.1.4/moshi-hook_Linux_x86_64.tar.gz 2>&1 | head -30
```

--------------------------------

### Configure UTF-8 Locale for CJK Output

Source: https://getmoshi.app/docs/cjk-input

Set the environment variables to ensure the remote shell correctly renders CJK characters. Add these to your shell configuration files to persist the settings across sessions.

```bash
$export LANG=en_US.UTF-8
$export LC_ALL=en_US.UTF-8
```

--------------------------------

### Send a unified webhook push

Source: https://getmoshi.app/docs/notifications

Use the unified flag in the webhook payload to broadcast notifications to all devices associated with a Moshi license.

```bash
$curl -X POST https://api.getmoshi.app/api/webhook \
$  -H "Content-Type: application/json" \
$  -d '{"token":"YOUR_API_TOKEN","title":"Done","message":"Build finished","unified":true}'
```

--------------------------------

### Check daemon status and logs

Source: https://getmoshi.app/docs/debug-gateway

Verifies if the Moshi daemon is running and inspects recent gateway logs.

```bash
$brew services list | grep moshi
$tail -50 ~/Library/Application\ Support/Moshi/hook.log | grep gateway
```
Tokens:
Raw