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

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

Pair your chat

DM your bot and type:
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)

Plain text becomes a prompt to the active tab.

​
CLI reference

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:
Check status and surface owner at any time: soulforge hearth status.

​
Surfaces

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.