Skip to main content
Hearth turns your running SoulForge 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

soulforge 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 (Telegram) or the Discord Developer Portal.
# pipe the token — never appears in ps output:
cat token.txt | soulforge hearth login telegram:<botId>
3

Pair your chat

soulforge 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)

CommandWhat it does
/pair <code>Redeem a pairing code
/new [label]Open a new tab (max 5)
/tab [id]List or switch tabs
/stopAbort the current turn
/close [id]Close a tab
/helpShow commands
Plain text becomes a prompt to the active tab.

​
CLI reference

soulforge hearth start                               # run the daemon
soulforge hearth status                              # daemon health + paired chats
soulforge hearth login <surface>:<id> [token]        # store a bot token
soulforge hearth pair <surface>:<id> --issue         # mint a pairing code
soulforge hearth pair <surface>:<id> <code>          # redeem from CLI
soulforge hearth unpair <surface>:<id> <chatId>      # revoke a chat
soulforge hearth doctor                              # diagnose setup
soulforge hearth logs [--follow]                     # tail daemon log
Inside SoulForge, /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: 
# macOS (launchd) / Linux (systemd) — auto-detected
soulforge hearth install        # install service
soulforge hearth install --now  # install and start
Check status and surface owner at any time: soulforge hearth status.

​
Surfaces

SurfacePlatformIdentity
TelegramAny OSBot + numeric from.id allowlist
DiscordAny OSBot + user snowflake allowlist
Unknown senders are silently dropped — their existence is not revealed.

​
Security

Hearth layers several protections on top of SoulForge’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 ~/.soulforge/hearth.json. Most users never edit it — the CLI manages everything. For advanced setups (multiple chats, read denylists, capability caps), see the config schema.

​
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.