Integration proxy

Some vendor APIs can’t be reached from the region where your Falang deployment runs — for example Telegram or OpenAI from Russia, or a Russian marketplace from abroad. Instead of moving the whole deployment, an administrator can run a small forward proxy in a place that can reach those APIs and tell Falang which integrations should use it. All other traffic keeps going out directly.

Run the proxy

The proxy is the standalone falang-proxy service from the proxy/ folder of the repository (Node 24, no runtime dependencies). Build and run it on a host in the right region:

cd proxy
docker build -t falang-proxy .
docker run -d --restart unless-stopped \
  -e PROXY_TOKENS=a-long-random-secret \
  -p 8080:8080 falang-proxy

Variable	Default	Meaning
HTTP_PORT	8080	Listen port.
PROXY_TOKENS	required	Comma-separated list of accepted tokens. The service refuses to start without one.
PROXY_ALLOWED_PORTS	443,80	Ports the proxy may connect to; * allows any. Keep it narrow.
PROXY_EXPOSE_STATS	false	Exposes a per-destination connection counter; meant for test stacks only.

Check that it is alive with curl http://your-proxy:8080/health — it answers 200 ok without authentication.

Protect the token. Falang sends the token in the Proxy-Authorization header of every request to the proxy. Put the proxy behind HTTPS termination (a reverse proxy in front of it, then use an https:// URL in Falang) or keep it on a private network. The traffic tunnelled through the proxy to HTTPS APIs stays end-to-end TLS — the proxy only sees which host and port are being contacted, never the request contents.

Configure it in the Admin app

1. Open the Admin app and go to the Proxy page.

2. Enter the proxy URL (http://… or https://…) and the token. When settings are already saved, leave the token blank to keep the stored one.

3. In Integrations, pick the vendors whose traffic should go through the proxy. The list is searchable and grouped into built-in integrations and ActivePieces pieces.

4. Click Save. Reset removes the URL, the token and the selection — everything goes out directly again.

What goes through the proxy

Only traffic of the selected integrations is routed, decided per request from the integration that issues it:

• actions, questions and choices of those integrations, executed in the workflow’s runner;

• backend-side work for them: Telegram long polling and webhook setup, incoming-webhook handlers, loading the options of dropdown fields, “Sync structure”, and the OAuth2 token exchange;

• ActivePieces pieces you selected (actions, triggers’ polling, option loading).

What does not go through it:

• database integrations (PostgreSQL, MySQL) — their connections are plain TCP, not HTTP, so selecting them has no effect;

• Falang’s own internal calls (backend, file storage, media and ActivePieces services);
• the AI-agent chat itself, which uses its own endpoint settings;

• ActivePieces pieces that build their own HTTP agent or open raw TCP connections (SMTP, IMAP, MongoDB and similar).

How fast changes apply

• Backend: within about 15 seconds.
• Runner pods of running workflows: within about 30 seconds — no rebuild or restart needed.
• ActivePieces service: within about 30 seconds.

Troubleshooting

• 407 Proxy Authentication Required — the token in the Admin app doesn’t match any entry in the proxy’s PROXY_TOKENS.

• 403 Forbidden — the proxy refused the destination port. A vendor API on a non-standard port needs that port in PROXY_ALLOWED_PORTS (or *).

• Connection refused or timeout — the proxy isn’t reachable from the deployment; check /health from the backend’s host and any firewall in between.

• A call still fails from the wrong region — make sure the vendor is ticked on the Proxy page; the proxy’s own log (one line per request, never the token) shows whether it arrived.