Examples

Testing Webhooks

When integrating with services like Stripe, GitHub, or Twilio, you need a publicly accessible URL to receive webhook callbacks. Beam makes this simple without deploying to a server.

Stripe Webhook Example

First, create a simple webhook handler. Here's an example using Express:

1
2
3
4
5
6
7
8
9
10
11
12
13
const express = require('express');
const app = express();
app.post('/webhook/stripe', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['stripe-signature'];
  console.log('Received webhook:', req.body.toString());
  // Process the webhook...
  res.status(200).send('OK');
});
app.listen(3000, () => console.log('Webhook server running on port 3000'));

Start your webhook server, then create a Beam tunnel:

node webhook-server.js

beam 3000 --mode=private

Beam outputs a .onion address. In Stripe's dashboard, configure your webhook endpoint as:

💡 For faster webhook testing during development, use --mode=balanced for ~80-150ms latency instead of ~200-500ms with private mode.

http://your-onion-address.onion/webhook/stripe

Note: Some services may not support .onion addresses. For those, you'll need to use a service that bridges HTTP to Tor, or wait for Beam's upcoming public URL feature.

API Development

When building APIs, you often need to test from different devices or share your work with teammates. Beam's dual mode gives you both fast local access and remote accessibility.

REST API with Express

Suppose you're building an API server:

# Your API runs on port 8080
npm run dev

Create a tunnel with a custom domain for local testing and Tor for remote access:

beam 8080 --domain api.local --mode=balanced

Now you can:

• Test locally at http://api.local:8080 with minimal latency
• Share the .onion address with teammates for testing (~80-150ms latency)
• Point mobile apps at the .onion address for device testing

beam 8080 --domain api.local --mode=fast

Testing with curl

curl http://api.local:8080/users

curl --socks5 localhost:9050 http://your-onion.onion/users

Mobile App Development

Testing mobile apps against a local backend is challenging because your phone can't access localhost. Beam solves this by providing a globally accessible URL.

React Native / Flutter Setup

Start your backend server and create a tunnel:

beam 3000 --mode=balanced --https

💡 Using --mode=balanced gives you ~80-150ms latency, which is acceptable for mobile development. For maximum privacy, use --mode=private.

In your mobile app, configure the API base URL to use the .onion address. For React Native:

1
2
3
4
5
6
// Development configuration
const API_BASE_URL = __DEV__
  ? 'http://your-onion-address.onion'  // Beam tunnel
  : 'https://api.production.com';       // Production
export { API_BASE_URL };

Your mobile app will need Tor support to access .onion addresses. Consider using a library like Orbot for Android or configuring your app to route through Tor.

Team Collaboration

Share work-in-progress with teammates without deploying to a staging environment. This is especially useful for design reviews, QA testing, or client demonstrations.

Sharing a Feature Branch

You're working on a new feature and want your teammate to test it:

# Switch to your feature branch and start the dev server
git checkout feature/new-dashboard && npm run dev

beam 3000 --mode=balanced

Share the .onion address with your teammate. They can view your changes immediately in a Tor Browser without you pushing code or setting up a preview deployment. Balanced mode provides ~80-150ms latency for a responsive experience.

Remember: The tunnel only works while Beam is running. Once you stop it, the .onion address becomes inaccessible.

Framework Integration

Beam works with any framework that runs a local development server. Here are examples for popular frameworks:

npm run dev
# In another terminal:
beam 3000 --domain nextjs.local --mode=balanced

npm run dev
# In another terminal:
beam 5173 --domain vite.local --mode=balanced

python manage.py runserver 8000
# In another terminal:
beam 8000 --domain django.local --mode=balanced

rails server
# In another terminal:
beam 3000 --domain rails.local --mode=balanced

uvicorn main:app --reload
# In another terminal:
beam 8000 --domain fastapi.local --mode=balanced

💡 Use --mode=fast for maximum speed during local development, or --mode=private when sharing sensitive projects.

HTTPS for Development

Some browser features require HTTPS, even in development. These include:

• Service Workers and PWA features
• Secure cookies with SameSite=None
• Geolocation API
• WebRTC
• Clipboard API

Use Beam's HTTPS mode to generate self-signed certificates:

beam 3000 --https --domain secure.local

Access your app at https://secure.local. Your browser will show a certificate warning—click through it to proceed.

To avoid the warning in Chrome, you can add the generated certificate to your system's trust store. Certificates are stored in ~/.beam/certs/.

Performance Optimization

Beam offers several performance optimizations. Here are examples for different scenarios:

beam 3000 --mode=fast --cache-size=200 --cache-ttl=600

beam 3000 --mode=balanced --prebuild-circuits=5 --geo-prefer=US,CA,UK

beam 3000 --mode=private --prebuild-circuits=8

beam 3000 --mode=balanced --no-cache

For detailed performance tuning, see the Performance Guide.

Next Steps

• CLI Reference — All available commands and options
• Performance Guide — Optimize latency with caching, circuit prebuilding, and mode selection
• Tor Network — Understanding .onion addresses and Tor integration
• Troubleshooting — Solutions to common issues