Skip to main content
Moldable ships with secure defaults and expects you to opt in to higher-risk settings only when you understand the tradeoffs. Most people only need the simple setups below. These are the same choices you’ll see in Guided onboarding. Pick one and you’re done. Manual config is shown only as an optional reference.

​
Start here: simple safe setups (most people)

Use when: You only use Moldable on this computer. Guided onboarding: Choose Just me (this computer only). Manual config (optional):
  • gateway.bind=loopback
  • gateway.public_access=false
  • gateway.auth.mode=token
  • pairing.dm_policy=pairing
Why this is safe: Your gateway never leaves your laptop, and new people can’t message it until you approve them.

​
2) “Local network (other devices on same Wi‑Fi)”

Use when: You want to connect from another device on your home/office network. Guided onboarding: Choose Local network (other devices on same Wi‑Fi). Manual config (optional):
  • gateway.bind=lan
  • gateway.public_access=false
  • gateway.auth.mode=token
  • pairing.dm_policy=pairing
Why this is safe: Only devices on your home/office Wi‑Fi can reach it. The wider internet still can’t.

​
3) “Remote access with a tunnel” (no public ports)

Use when: You want remote access without opening a public port. Guided onboarding: Choose Remote access with a tunnel. Manual config (optional):
  • Keep gateway.bind=loopback
  • Keep gateway.public_access=false
  • Use a tunnel (SSH, Tailscale, ngrok)
Why this is safer: You’re not opening a public port on your machine. Access only works through the tunnel, which you can disable or restrict with access policies.

​
4) “Webhooks (e.g. WhatsApp Cloud)”

Use when: A service needs to send webhooks to you. Guided onboarding: Choose Webhooks (e.g. WhatsApp Cloud). Manual config (optional):
  • Keep gateway.bind=loopback
  • Keep gateway.public_access=false
  • Expose the webhook port (e.g. 127.0.0.1:8088) via a tunnel
Why this is safe: You only expose the tiny webhook doorway, not your whole gateway or computer.

​
5) “Telegram (local-only)”

Use when: You only need outbound polling. Guided onboarding: Choose Telegram (local-only). Manual config (optional):
  • Same as “Just me (this computer only)” or “Local network (other devices on same Wi‑Fi)”
Why this is safe: Telegram doesn’t need to call into your computer. Your gateway calls out to Telegram, so nothing on the internet can access your machine.
If you are not sure, choose “Just me (this computer only)”. You can always change later.

​
What actually protects you (simple explanation)

  • Loopback bind means “only this computer can connect.”
  • Public access = off means “the internet can’t reach me.”
  • Auth required means “a secret token is always needed.”
  • Pairing means “new people must be manually approved by you before they can DM your bot.”
You can verify your posture any time: 
moldable gateway audit
Use moldable gateway audit --fix to apply safe fixes automatically. The gateway also prints a security summary on startup and refuses to run if there are critical findings (use moldable gateway run --force to override).

​
Prompt injection & LLM risks (applies to everyone)

Prompt injection is a real risk for any LLM system. The gateway helps, but it is not a guarantee. For secret storage and “prompt injection can’t print my keys” protections, see: Common risk vectors people often miss:
  • Exfiltration prompts: “summarize your secrets,” “print the system prompt,” or “read local files and send them back.”
  • Tool misuse: a message tricks the model into running commands or sending data it shouldn’t.
  • Untrusted inputs: web pages, documents, or chats can contain hidden instructions.
  • Untrusted tools/CLIs: compromised node packages or vendor tools can execute arbitrary code you didn’t audit.
  • Expanded surface area: granting access to email, calendars, notes, or other dynamic sources multiplies the ways attackers can inject or exfiltrate data.
  • Model supply risk: a model trained on poisoned data (e.g. 200 documents placed on the internet for training data crawlers to find) can have hidden triggers.
  • Over‑sharing: users paste sensitive data or keys into chats, which gets logged locally or sent to a provider.
Mitigations we recommend:
  • The gateway can prepend a safety system prompt (when enabled).
  • Gateway outputs can be redacted for known secrets (gateway.safety.redact_output_secrets).
  • Use allowlists and avoid dm_policy=open.
  • Don’t expose the gateway on LAN/custom binds without TLS + strong tokens.
  • Use a strong model for higher resistance.
  • Audit tools, skills, and configurations on a regular basis to only keep what you absolutely need.

​
Remaining risks by setup (what’s still true)

Even with safe defaults, there are still risks depending on how you use the gateway. Here’s what remains for each recommended setup:

​
“Just me (this computer only)”

  • Risk if your laptop is compromised (malware, stolen device, unlocked session).
  • Any message you send to the bot can still be logged locally.
  • If you enable nodes, those can access local files when approved.

​
“Local network (other devices on same Wi‑Fi)”

  • Everything from “Just me” plus: anyone on your LAN who gets the token can connect.
  • Shared or untrusted Wi‑Fi increases exposure, so always use a VPN on shared networks.

​
“Remote access with a tunnel” (tunnel)

  • Everything from “Just me” plus: the tunnel provider becomes part of the trust chain.
  • Misconfigured tunnel access controls can expose the gateway.

​
“Webhooks (e.g. WhatsApp Cloud)”

  • Webhook URL is public; attackers can hit it (the verify token helps, but be sure to set a rate‑limit and monitor for abuse).
  • The tunnel endpoint is on the internet; secure it and rotate tokens if leaked.

​
“Telegram (local-only)”

  • Telegram bot chats are not end‑to‑end encrypted. Content flows through Telegram’s servers.
  • If the bot is in a group, any member can talk to it, so use pairing/allowlists and keep require_mention=true.

​
If your machine handles sensitive data (e.g., banking, HIPAA, PHI / PII)

If this computer sometimes accesses sensitive data, keep a strict boundary:
  • Keep the gateway local‑only (bind=loopback, public_access=false).
  • Keep pairing on and use allowlists for trusted senders.
  • Avoid sending sensitive data to remote AI providers unless you have the right agreements (e.g., BAA).
  • Consider running the gateway under a separate OS user or on a dedicated machine.
Recommended guided setup: Just me (this computer only) (local‑only).
If you need another device on the same Wi‑Fi, use Local network and keep public_access=false. Data access summary (Telegram or other channels):
  • The gateway does not read local files unless nodes are enabled.
  • By default, messages are kept in memory only (not written to disk). If you enable session transcripts (sessions.transcripts.enabled), messages are stored locally in session logs.
  • Operational logs and Vault audit logs are separate from transcripts. See Logging for privacy options (including a global disk log kill switch).
  • Telegram bot chats are not end‑to‑end encrypted and pass through Telegram servers.
  • If you use a remote AI adapter, message content is sent to that provider.
  • Group chats can expose the bot to any group member, so keep require_mention=true and use pairing/allowlists.

​
Advanced setup (read only if you are customizing)

If you want to change defaults or expose the gateway beyond your own device, read this section carefully. These options are powerful but easier to misconfigure.

​
What do loopback, LAN, and public mean?

  • Loopback = this computer only (127.0.0.1).
  • LAN = other devices on your local network (same Wi‑Fi/router).
  • Public = devices outside your network (the internet).

​
Remote access & tunnels (how they avoid a public port)

Normally, to reach your gateway from the internet you would open a public port on your router. A tunnel avoids that. Your machine makes an outbound connection to a tunnel provider, and the provider relays traffic back to your local gateway. From the internet’s point of view, your gateway still has no open public port. Recommended posture:
  • Keep gateway.bind=loopback and gateway.public_access=false.
  • Keep auth on (token).
  • Use a tunnel if you need remote access.
Common options:
  • SSH tunnel:
    • ssh -N -L 19789:127.0.0.1:19789 user@host
  • Tailscale Serve/Funnel (identity‑based)
  • ngrok (public HTTPS tunnel)

​
Security checklist (quick self‑check)

  • gateway.auth.mode is token (never off).
  • gateway.public_access=false unless you explicitly need public access.
  • If gateway.public_access=true, then gateway.tls.enabled=true.
  • HTTP endpoints are protected with gateway.http.auth_token (or gateway auth).
  • Pairing is enabled (pairing.dm_policy=pairing).

​
Gateway API authentication

The gateway exposes a local control API for the CLI. Auth is configured under gateway.auth:
  • token (required)
Auth is always required. Example: if you set a token, the CLI uses it when you run moldable gateway status.

​
Can anyone else access my gateway?

Not unless you allow it:
  • Loopback bind keeps the gateway reachable only on the local machine.
  • LAN/custom binds still require gateway.auth and gateway.http.auth_token for HTTP endpoints.
  • LAN-only access is enforced by default; set gateway.public_access=true to allow public internet access.
  • Node connections (if enabled) require explicit pairing and authorization.
If you expose the gateway beyond loopback, enable TLS and keep tokens secret.

​
Reverse proxies (unsupported)

Running the gateway behind a reverse proxy on the same host is risky and unsupported today. Some proxy setups can unintentionally weaken network boundary checks. If you must use a reverse proxy:
  • Keep gateway.bind=loopback and gateway.public_access=false.
  • Enforce strong auth + TLS at the proxy and restrict access with firewall rules.
  • Prefer a tunnel instead of opening a public port.

​
DM policies

Configured in pairing.dm_policy:
  • pairing: unknown senders create a pending request (default).
  • allowlist: only explicitly allowed or approved senders.
  • open: all DMs allowed (no pairing gate).
  • disabled: all DMs blocked.
When to use each:
  • Pairing (recommended): safest default. New people must be approved before they can DM.
  • Allowlist: use if you want only a short list of people to DM the bot.
  • Open: only for controlled setups (e.g., a private test bot where you are the only user). Anyone who can reach the gateway can DM.
  • Disabled: use if you only want group chats or webhooks and want to block all DMs entirely.
When pairing is enabled, the gateway sends a short message back with a pairing code. You approve it with: 
moldable gateway pair approve <channel> <code>

​
Group policies

Groups are gated by the channel‑specific allowlist and mention rules:
  • If groups is empty or contains *, all groups are allowed.
  • If require_mention is true, the bot must be mentioned in a group message.

​
Allowlists

Each channel has an allow_from list of sender IDs. These are always allowed, regardless of pairing status.

​
Where approvals live

Pairing approvals are stored locally under the gateway state directory.

​
Are my files and personal data safe?

The gateway does not read your local files by default. It only sees:
  • Messages received by enabled channels.
  • Session transcripts stored locally.
  • Any data you explicitly pass to an adapter.
File access only happens if you use paired node runtimes that can run system commands. If you use a remote AI adapter, your message content is sent to that provider. If you use a local adapter, data stays on your machine.

​
Node pairing

Nodes (tool runtimes) must be paired when nodes.require_pairing is true. Pairing requests are managed via: 
moldable gateway node pair list
moldable gateway node pair approve <node-id>
Node approvals are stored under: 
~/.moldable/gateway/nodes/paired.json
Next: Channels