Ambit Signal

api | install-astro | install-caddy | install-cloudflare | install-express | install-js-tag | install-netlify | install-nginx | install-shopify | install-squarespace | install-sveltekit | install-vercel-next | install-webflow | install-wix | install-wordpress | mcp | outcomes | privacy | quickstart | troubleshooting

Install: nginx (self-hosted)

Collection: server collector (sees bots and humans). Replace example.com and st_YOURSITEID with your site's values (dashboard, list_sites, or GET /v1/sites). The MCP tool get_install_snippet(platform="nginx", site_id=...) returns this page pre-filled.

Steps

  1. Add the ambit_signal log_format to the http {} block (file below).
  2. In the site's server {} block add: access_log /var/log/nginx/ambit_signal.log ambit_signal;
  3. nginx -t && systemctl reload nginx
  4. Run the shipper as a service: AMBIT_SIGNAL_SITE=... AMBIT_SIGNAL_SECRET=... python3 ship.py /var/log/nginx/ambit_signal.log --state /var/lib/ambit-signal/offset.json
  5. Keep logrotate retention short (7 days): this log holds raw IPs.

File: /etc/nginx/conf.d/ambit_signal_format.conf

log_format ambit_signal escape=json
  '{"ts":$msec,"method":"$request_method","host":"$host","path":"$request_uri",'
  '"status":$status,"ip":"$remote_addr","ua":"$http_user_agent",'
  '"referer":"$http_referer","lang":"$http_accept_language",'
  '"sig_agent":"$http_signature_agent","signature":"$http_signature",'
  '"signature_input":"$http_signature_input"}';

Configuration

Name Value
AMBIT_SIGNAL_SITE example.com
AMBIT_SIGNAL_SECRET <SECRET>

<SECRET> is the site secret shown once when the site was created. Lost it? Rotate it in the dashboard (Site > Keys) or ask ambit; the old secret stops working immediately.

Verify

Load any page of example.com once, then check: MCP tool verify_install(site_id="st_YOURSITEID") or GET https://signal.ambit.agency/v1/sites/st_YOURSITEID/status with your API key. "receiving": true means events are arriving (usually within a minute).

curl -s -H "Authorization: Bearer $AMBIT_SIGNAL_API_KEY" \
  https://signal.ambit.agency/v1/sites/st_YOURSITEID/status

Expected: "receiving": true. If not, see troubleshooting.

Notes