Network deployment, Raspberry Pi & proxy

This page covers running Revka on a local network or a low-power ARM board, and routing its outbound traffic through a proxy. Use it when you deploy to a Raspberry Pi or home-lab host, need to decide between polling and webhook channels, or have to send Revka’s traffic through a corporate or air-gapped proxy.

The single revka binary runs everywhere — see Runtime modes, adapters & resource limits for the native vs. Docker adapter, and Run as a background service to keep the daemon alive across reboots.

Choose a channel by inbound-port requirement

The biggest network decision is whether your channels need an inbound port. Polling-style channels make only outbound connections, so they work behind NAT, on a Raspberry Pi, or in a home lab with no port forwarding. Webhook channels need a public HTTPS URL so the remote service can POST events to you.

Mode	Inbound port needed?	Notes
Telegram polling	No	Revka polls the Telegram API; works from anywhere
Matrix sync (incl. E2EE)	No	Syncs via the Matrix client API; no webhook
Discord / Slack	No	Outbound only
Nostr	No	Connects to relays over WebSocket; outbound only
Gateway webhook	Yes	POST /webhook, /whatsapp, /linq, /nextcloud-talk need a public URL
Gateway pairing	Yes	If you pair remote clients via the gateway

Tip

If every channel you use is polling-based, keep the gateway bound to 127.0.0.1 and skip tunnels entirely. Reach for a tunnel only when a webhook channel or remote pairing requires a public URL — see Expose your gateway with a tunnel.

Network deployment modes (bind addresses)

The gateway can bind to:

• 127.0.0.1 — localhost only (the default; not reachable from other machines)
• 0.0.0.0 — all IPv4 interfaces (LAN access)
• [::] — all IPv6 interfaces (the default inside Docker containers)

Binding to a non-loopback address is guarded: the CLI and daemon refuse to bind to anything other than loopback unless allow_public_bind = true is set, or a tunnel is active.

~/.revka/config.toml

[gateway]
host = "0.0.0.0"
port = 42617
allow_public_bind = true

You can override the bind address per run from the CLI:

revka daemon --host 127.0.0.1            # localhost only (default)
revka daemon --host 0.0.0.0 --port 42617 # LAN access

Setting	Env override	Default	Meaning
gateway.host	REVKA_GATEWAY_HOST	127.0.0.1	Bind address
gateway.port	REVKA_GATEWAY_PORT	42617	Listen port
gateway.allow_public_bind	REVKA_ALLOW_PUBLIC_BIND	false	Required to bind a non-loopback address

Caution

0.0.0.0 exposes the gateway to every connected network. Only enable allow_public_bind on trusted LANs. For public internet exposure, prefer a tunnel pointed at 127.0.0.1 over a raw public bind — that way the gateway itself never listens on a routable interface.

Raspberry Pi & embedded deployment

Revka runs on ARMv7 and ARM64 (aarch64) Linux, including Raspberry Pi 3 / 4 / 5 on Raspberry Pi OS. Telegram polling needs no inbound port, and USB-attached serial peripherals (Arduino, STM32 Nucleo) work over the native runtime.

ARMv7 / aarch64 prebuilt binaries

Prebuilt binaries are published for both Raspberry Pi architectures, so you usually do not need to compile on the device:

Target	Board
aarch64-unknown-linux-gnu	Raspberry Pi 4 / 5 (64-bit)
armv7-unknown-linux-gnueabihf	Raspberry Pi 2 / 3 (ARMv7)
arm-unknown-linux-gnueabihf	Older 32-bit ARM

Tip

Source builds need roughly 2 GB RAM and 6 GB disk — tight on constrained Pis. Pass --prefer-prebuilt to the bootstrap installer to download a release binary first and fall back to source only if no prebuilt target matches. See Installation.

Build from source with hardware support

If you do build locally (for example to enable GPIO), add the hardware features:

# USB / serial device support
cargo build --release --features hardware

# Native Raspberry Pi GPIO via rppal
cargo build --release --features hardware,peripheral-rpi

Cargo feature	Enables
hardware	USB / serial device support
peripheral-rpi	Native RPi GPIO (via rppal)

Configure GPIO, serial peripherals, and Telegram

~/.revka/config.toml

[peripherals]
enabled = true

# Native RPi GPIO
[[peripherals.boards]]
board = "rpi-gpio"
transport = "native"

# Or an Arduino over USB-serial
[[peripherals.boards]]
board = "arduino-uno"
transport = "serial"
path = "/dev/ttyACM0"
baud = 115200

[channels_config.telegram]
bot_token = "YOUR_BOT_TOKEN"
allowed_users = []          # deny-by-default; bind identities explicitly

[gateway]
host = "127.0.0.1"
port = 42617
allow_public_bind = false

Run the daemon

1. Start the daemon bound to localhost — Telegram still works because it polls outbound:

   revka daemon --host 127.0.0.1 --port 42617

2. Approve one Telegram account at runtime (numeric user ID or username without @):

   revka channel bind-telegram <IDENTITY>

3. To let other LAN devices reach the dashboard or pair, switch to 0.0.0.0 and set allow_public_bind = true (see bind addresses above).

Single-poller rule

The Telegram Bot API getUpdates endpoint allows only one active poller per bot token. Run a single revka daemon for a given token; do not also run revka channel start or another bot process with the same token. The symptom of a conflict is:

Conflict: terminated by other getUpdates request

Stop the extra instances and restart a single daemon.

For GPIO tooling, board references, and a dedicated Pi walkthrough, see Raspberry Pi (self-hosted), GPIO tools, and Supported boards reference. On Alpine/OpenRC boards, install the system service with sudo revka service install — details in Run as a background service.

Webhook channels (public URL)

Webhook channels — WhatsApp Cloud API, Nextcloud Talk, and the generic ingress — need a public HTTPS endpoint. The recommended pattern is to keep the gateway on 127.0.0.1 and front it with a tunnel rather than binding publicly:

[tunnel]
provider = "tailscale"   # or "ngrok", "cloudflare", "pinggy", "openvpn", "custom"

Point your webhook URL at the tunnel’s public hostname. The full provider list, tokens, and config keys are in Expose your gateway with a tunnel; the ingress endpoints are documented in Webhook ingress.

Outbound proxy routing — [proxy]

Enterprise and air-gapped deployments often must route Revka’s outbound HTTP/HTTPS/SOCKS5 traffic through a proxy. The [proxy] section controls this, including per-service routing so only chosen providers, channels, or tools traverse the proxy.

[proxy]
enabled = true
http_url = "http://proxy.example.com:8080"
https_url = "http://proxy.example.com:8080"
scope = "services"
services = ["provider.anthropic", "channel.telegram"]

Key	Env override	Default	Meaning
enabled	REVKA_PROXY_ENABLED	false	Master switch
http_url	REVKA_HTTP_PROXY	unset	HTTP proxy URL
https_url	REVKA_HTTPS_PROXY	unset	HTTPS proxy URL
all_proxy	REVKA_ALL_PROXY	unset	Fallback proxy for all protocols (SOCKS5)
no_proxy	REVKA_NO_PROXY	unset	Hosts that bypass the proxy
scope	REVKA_PROXY_SCOPE	"revka"	environment | revka | services
services	REVKA_PROXY_SERVICES	[]	Comma-separated service keys (when scope = "services")

Allowed proxy URL schemes are http, https, socks5, and socks5h.

Scope: environment / revka / services

The scope field decides how far the proxy reaches:

Scope	Affects	Exports env vars?	Use when
revka	Revka’s own outbound HTTP clients	No	Normal runtime proxying without process-level side effects
services	Only the listed service keys / selectors	No	Surgical routing for specific providers, channels, or tools
environment	Runtime plus process HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / NO_PROXY	Yes	Sidecars or subprocesses that read proxy env vars

When scope = "services", you select targets by exact key or wildcard. Supported keys include provider.anthropic, provider.openai, provider.compatible, channel.telegram, channel.discord, tool.browser, tool.web_search, memory.embeddings, tunnel.custom, and transcription.groq, among others. Wildcards provider.*, channel.*, and tool.* are supported.

[proxy]
enabled = true
http_url = "http://127.0.0.1:7890"
scope = "services"
services = ["provider.*", "channel.telegram"]   # only LLM providers + Telegram

Caution

scope = "services" with an empty services list fails fast at startup:

proxy.scope='services' requires a non-empty proxy.services list

Set at least one concrete key or selector.

Manage the proxy at runtime — proxy_config tool

The agent can read and change proxy settings live through the proxy_config tool, without editing config.toml by hand. This is ideal when an operator needs the agent to switch proxy behavior on demand.

Actions: get, set, disable, list_services, apply_env, clear_env.

Param	Type	Used by	Meaning
action	string	all	One of the actions above (default get)
enabled	bool	set	Enable or disable the proxy
scope	string	set	environment | revka | services
http_proxy / https_proxy / all_proxy	string	set	Proxy URLs
no_proxy	string or array	set	NO_PROXY entries
services	string or array	set	Service selectors (when scope = services)
clear_env	bool	disable	Also clear process proxy env vars

Proxy Agent Playbook

Follow this standard, reversible workflow for every proxy change: inspect, discover, apply, verify, roll back if needed.

1. Inspect current state and discover valid service keys.

   {"action": "get"}
   {"action": "list_services"}

2. Apply the scope you need.

   Revka internals only

   Route Revka’s provider/channel/tool HTTP traffic without exporting process env vars:

   {"action": "set", "enabled": true, "scope": "revka",
    "http_proxy": "http://127.0.0.1:7890",
    "https_proxy": "http://127.0.0.1:7890",
    "no_proxy": ["localhost", "127.0.0.1"]}

   Selected services

   Proxy only specific providers/tools/channels (exact keys or selectors):

   {"action": "set", "enabled": true, "scope": "services",
    "services": ["provider.openai", "tool.http_request", "channel.telegram"],
    "all_proxy": "socks5h://127.0.0.1:1080",
    "no_proxy": ["localhost", "127.0.0.1", ".internal"]}

   Process environment

   Export process-wide proxy env vars for subprocesses that read them, then apply:

   {"action": "set", "enabled": true, "scope": "environment",
    "http_proxy": "http://127.0.0.1:7890",
    "https_proxy": "http://127.0.0.1:7890",
    "no_proxy": "localhost,127.0.0.1,.internal"}
   {"action": "apply_env"}

3. Verify the runtime and environment snapshots.

   {"action": "get"}

4. Roll back if behavior is not what you expect.

   {"action": "disable"}                       // disable proxy (safe default)
   {"action": "disable", "clear_env": true}    // also clear exported env vars
   {"action": "clear_env"}                     // keep proxy on, drop env exports only

Troubleshooting

• proxy.scope='services' requires a non-empty proxy.services list — add at least one service key or selector.
• Invalid proxy URL scheme — allowed schemes are http, https, socks5, socks5h.
• Proxy not applying as expected — run {"action": "list_services"} to confirm service names, then {"action": "get"} to inspect the runtime_proxy and environment snapshot values.

RPi deployment checklist

1. Use a prebuilt aarch64/armv7 binary, or build with --features hardware (add peripheral-rpi for native GPIO).
2. Configure [peripherals] and [channels_config.telegram] in ~/.revka/config.toml.
3. Run revka daemon --host 127.0.0.1 --port 42617 — Telegram works without a public bind.
4. For LAN access, set --host 0.0.0.0 plus allow_public_bind = true.
5. For webhooks, front the gateway with a Tailscale, ngrok, or Cloudflare tunnel.
6. Keep a single poller per Telegram bot token.

Related pages

Runtime modes & adapters Native vs. Docker runtime and resource limits.

Run as a background service launchd, systemd, OpenRC & Windows Task Scheduler.

Expose with a tunnel Cloudflare, Tailscale, ngrok, Pinggy & more.

Raspberry Pi (self-hosted) GPIO, boards & a full Pi walkthrough.

Connect a messaging channel Polling and webhook channel setup.

Configuration overview Every config section and key.