<!-- Markdown mirror. Canonical: https://empryo.com/docs/tools/hearth -->

# Hearth - Remote control [experimental]

> Control your running Empryo from Telegram or Discord. Send prompts, approve edits with inline buttons, keep code on your host. Experimental, expect rough edges.

Hearth turns your running Empryo into a remote coding agent. Send prompts from your phone, approve edits with inline buttons, keep coding from anywhere.

Your code never leaves your host. Hearth only opens outbound connections to messaging platforms.

## Start in 4 steps

**1. Start the daemon**

```bash
empryo hearth start
```
Leave this running. It listens on a UNIX socket (`0600` permissions, local only).

**2. Create a bot and store the token**

Create a bot on [@BotFather](https://t.me/BotFather) (Telegram) or the [Discord Developer Portal](https://discord.com/developers/applications).

```bash
# pipe the token: never appears in ps output:
cat token.txt | empryo hearth login telegram:<botId>
```

**3. Pair your chat**

```bash
empryo hearth pair telegram:<botId> --issue
# prints a 6-character code
```
DM your bot and type:
```
/pair ABC123
```

**4. Talk**

Any message you send the bot now goes to your forge. Tool calls that need approval arrive as inline buttons - tap Approve or Deny.

## Commands (in the chat)

| Command | What it does |
|---------|--------------|
| `/pair <code>` | Redeem a pairing code |
| `/new [label]` | Open a new tab (max 5) |
| `/tab [id]` | List or switch tabs |
| `/rename <name>` | Rename the bound tab — persisted, so the name survives a restart |
| `/stop` | Abort the current turn |
| `/close [id]` | Close a tab |
| `/help` | Show commands |

Plain text becomes a prompt to the active tab.

## CLI reference

```bash
empryo hearth start                               # run the daemon
empryo hearth status                              # daemon health + paired chats
empryo hearth login <surface>:<id> [token]        # store a bot token
empryo hearth pair <surface>:<id> --issue         # mint a pairing code
empryo hearth pair <surface>:<id> <code>          # redeem from CLI
empryo hearth unpair <surface>:<id> <chatId>      # revoke a chat
empryo hearth doctor                              # diagnose setup
empryo hearth logs [--follow]                     # tail daemon log
```

Inside Empryo, `/hearth` opens the settings panel with the same controls.

## Always-on (service)

Run Hearth as a background service so your forge is reachable even after logout. Open the `/hearth` settings panel inside Empryo to install a launchd (macOS) or systemd (Linux) service — the platform is auto-detected.

Prefer the CLI? Run the daemon detached:

```bash
empryo hearth start --detach   # run in the background
empryo hearth stop             # graceful shutdown
```

Check status and surface owner at any time: `empryo hearth status`.

## Surfaces

| Surface | Platform | Identity |
|---------|----------|----------|
| **Telegram** | Any OS | Bot + numeric `from.id` allowlist |
| **Discord** | Any OS | Bot + user `snowflake` allowlist |

Unknown senders are silently dropped - their existence is not revealed.

## Security

Hearth layers several protections on top of Empryo's existing hook system:

#### Identity allowlist

Only paired identities can send. Unknown senders are dropped.

#### Approval prompts

Destructive tool calls (edit, shell, git) arrive as tap-to-approve buttons.

#### Secret redaction

Bot tokens, API keys, PATs, AWS keys, bearer tokens - auto-redacted from all logs.

#### Read denylist

`.env`, `*.pem`, `~/.ssh/**`, `~/.aws/credentials` - blocked before every read.

#### Sandboxed caps

Optional: route destructive ops through Docker with `caps: "sandboxed"`.

#### Bot tokens in keychain

Tokens live in macOS Keychain / Linux secret-tool. Never in plain config.

## Config

Default config lives at `~/.empryo/hearth.json`. Most users never edit it - the CLI manages everything. Advanced setups (multiple chats, read denylists, capability caps) are configured by editing that file directly.

## Non-goals

- **No cloud.** Hearth is "reach your host" - not a hosted service. Your machine must be running.
- **No WhatsApp.** Terms of service forbid it.
- **No concurrent writers.** Reads ok across chats; writes are single-owner per tab.