Familiar logo
Familiar usefamiliar.com
Documentation / Fleet

Remote Gateway

Connect Fleet to external services with Fleet Gateway.

What is Fleet Gateway?

Fleet Gateway is a secure relay service that allows external services to send events to your local Fleet installation. It enables webhook-based automation without exposing your machine to the internet.

Key features:

  • Receive webhooks from GitHub, Stripe, Slack, and other services
  • Secure connection without port forwarding
  • Automatic reconnection
  • Event signature verification

How It Works

External Service (GitHub, Stripe, etc.)
          │
          ▼
     Fleet Gateway (Cloud)
          │
          ▼ (Secure tunnel)
     Your Fleet App (Local)
          │
          ▼
     Your Agent
  1. External services send webhooks to Fleet Gateway
  2. Gateway securely relays events to your local Fleet
  3. Fleet triggers subscribed agents

Connecting to Gateway

Step 1: Open Settings

Press Cmd+, or click the gear icon to open Settings.

Step 2: Navigate to Remote

Click Remote in the settings sidebar.

Step 3: Connect

Click Connect to Fleet Gateway and sign in.

Once connected, you'll see:

  • Connection status (Connected/Disconnected)
  • Your Gateway ID
  • Active webhooks

Creating Webhooks

Via Agent

Ask any agent to create a webhook:

Create a webhook for GitHub pull request events

The agent returns a URL like:

https://fleet-gateway.fly.dev/t/abc123xyz

Via API

The agent uses the create_webhook tool:

create_webhook({
  name: "github-events",
  description: "Receives GitHub webhook events"
})

Configuring External Services

GitHub

  1. Go to your repository → Settings → Webhooks
  2. Click Add webhook
  3. Payload URL: Paste your Fleet webhook URL
  4. Content type: application/json
  5. Secret: (Optional) Add for signature verification
  6. Select events (push, pull_request, issues, etc.)
  7. Click Add webhook

Stripe

  1. Go to Dashboard → Developers → Webhooks
  2. Click Add endpoint
  3. Endpoint URL: Paste your Fleet webhook URL
  4. Select events to receive
  5. Click Add endpoint
  6. Copy the signing secret to Fleet Vault

Slack

  1. Go to api.slack.com → Your app
  2. Event Subscriptions → Enable
  3. Request URL: Paste your Fleet webhook URL
  4. Subscribe to events
  5. Save changes

Generic Webhooks

For any service that supports webhooks:

  1. Find the webhook configuration in the service
  2. Paste your Fleet Gateway URL
  3. Configure event types
  4. Save

Signature Verification

For security, enable signature verification:

Creating a Verified Webhook

create_webhook(
  name: "secure-webhook",
  require_signature: true
)

This generates a signing secret stored in your macOS Keychain.

Configuring External Services

Provide the signing secret to the external service. They'll use it to sign payloads.

Fleet verifies signatures using:

  • GitHub: X-Hub-Signature-256 (HMAC-SHA256)
  • Stripe: Stripe-Signature
  • Custom: HMAC-SHA256 in X-Signature header

Viewing Signing Secret

Signing secrets are stored securely and not displayed in the UI. Access them through the Secure Vault if needed for configuration.

Webhook Management

View Active Webhooks

Go to Settings → Remote to see all webhooks:

  • Webhook name
  • URL
  • Event count
  • Last triggered

Delete Webhooks

Click the delete icon next to any webhook to remove it.

Note: This invalidates the webhook URL. Update external services accordingly.

Test Webhooks

Click Test to send a test payload and verify connectivity.

Security Considerations

What's Exposed

  • Webhook URLs are public endpoints
  • Payload data is transmitted through Gateway

What's Protected

  • Your IP address is never exposed
  • Connection is encrypted (TLS)
  • Signature verification prevents spoofing
  • Gateway doesn't store payload contents

Best Practices

  1. Enable signature verification for sensitive webhooks
  2. Use specific event types rather than "send everything"
  3. Rotate signing secrets periodically
  4. Delete unused webhooks promptly
  5. Monitor webhook activity in Settings

Troubleshooting

Connection Issues

Gateway disconnected:

  1. Check internet connection
  2. Try reconnecting in Settings → Remote
  3. Restart Fleet if needed

Webhooks not arriving:

  1. Verify external service configuration
  2. Check webhook URL is correct
  3. Look for delivery errors in external service
  4. Test with the Test button

Signature Failures

Invalid signature errors:

  1. Verify signing secret matches in both places
  2. Check signature header name is correct
  3. Ensure external service is sending signatures

Limitations

  • Requires internet connection
  • Some latency for webhook delivery
  • Payload size limit: 1MB
  • Rate limit: 1000 events/hour per webhook

Next Steps