Skip to main content

​
Testing Local Apps

Swarm’s AI agents run in the cloud. To test a local development server, the CLI automatically creates a secure tunnel from your machine to the cloud.

​
Basic local testing

Just pass your localhost URL: 
swarm test --url localhost:3000 --goal "Sign up for an account"
The CLI detects that the URL is local, opens a tunnel, and rewrites the URL for the cloud agents. No configuration needed.

​
Tunnel providers

Swarm supports two tunnel providers:

​
Cloudflare Tunnel (default)

Free, no bandwidth limits, no account required. Requires the cloudflared binary: 
# macOS
brew install cloudflared

# Linux
curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 \
  -o /usr/local/bin/cloudflared && chmod +x /usr/local/bin/cloudflared

# Windows
winget install Cloudflare.cloudflared

​
ngrok

Bundled with the CLI — works out of the box with your Swarm account. Has bandwidth limits on free ngrok plans.

​
Choosing a provider

# Auto (tries cloudflare first, falls back to ngrok)
swarm test --url localhost:3000 --goal "Sign up"

# Force cloudflare
swarm test --url localhost:3000 --goal "Sign up" --tunnel-provider cloudflare

# Force ngrok
swarm test --url localhost:3000 --goal "Sign up" --tunnel-provider ngrok

​
Split frontend/backend

Many apps run the frontend and backend on separate ports. For example, a React app on port 3000 and an Express API on port 8080. The problem: the tunnel only exposes one port. If your frontend makes API calls to localhost:8080, the cloud browser can’t reach it. The solution: Swarm’s built-in reverse proxy routes API paths to your backend through the same tunnel. 
swarm test --url localhost:3000 --backend localhost:8080 --goal "Create a project"
This starts a proxy that routes:
  • /api/*, /auth/*, /graphql, /trpc/* → localhost:8080 (backend)
  • Everything else → localhost:3000 (frontend)

​
Custom API paths

If your backend uses different path prefixes: 
swarm test --url localhost:3000 \
  --backend localhost:8080 \
  --backend-paths "/v1,/webhooks,/uploads" \
  --goal "Upload a file"

​
Skipping the tunnel

If your URL is already publicly accessible: 
swarm test --url https://staging.myapp.com --goal "Sign up" --no-tunnel

​
Framework notes

​
Next.js / Nuxt / SvelteKit / Remix

These full-stack frameworks serve both frontend and API routes on the same port. You typically don’t need the --backend flag — a single tunnel covers everything.

​
Django

Add the tunnel URL to your ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS in settings.py. The CLI prints a reminder with the exact values after the tunnel opens.

​
Vite / Create React App

If your frontend proxies API calls in development (e.g., Vite’s server.proxy), the proxy already handles routing and a single tunnel works. Only use --backend if you’re making direct cross-origin requests to a separate backend port.