Instant Preview

Expose the Farm app that is already running on your machine through a temporary public URL.

farm dev --port 3000
farm preview --port 3000

farm preview is not a deployment command. It does not run farm build, upload output, or create a production release. It opens an outbound connection from the CLI to the Farm Preview gateway and forwards public traffic back to your local dev server.

Use it when an external system needs to reach the app you are actively developing:

Stripe, Clerk, Better Auth, Supabase, Unkey, or custom webhooks.
OAuth redirect and callback URLs.
Mobile device testing on a real phone.
Sharing a local branch with a teammate.
Browser automation that needs a public HTTPS origin.
Demoing an integration before it is deployed.

Quick Start

Start the app first:

farm dev --port 4324

Open a preview in another terminal:

farm preview --port 4324 --name checkout-test

Farm prints the local target, persistent relay, and public URL:

Creating public preview for the running app...
Local:  http://localhost:4324
Relay: wss://preview.farming-labs.dev/agent
Opening native Farm preview tunnel...
Preview URL ready.
Public: https://checkout-test.preview.farming-labs.dev
Forwarding requests through the native tunnel until Ctrl+C.

During the relay rollout, the CLI warns and falls back to compatibility gateway polling if the hosted endpoint cannot accept the native WebSocket connection. An explicitly configured FARM_PREVIEW_RELAY_URL is tried first as well.

Open the public URL from another browser, device, webhook provider, or test runner:

https://checkout-test.preview.farming-labs.dev

Keep both terminals running while you test. Stop the preview with Ctrl+C.

Automatic Shutdown

The preview lifecycle is tied to the local app. When farm dev stops or the configured local target becomes unreachable, the native tunnel closes its hosted relay session and farm preview exits. The compatibility path closes its gateway session the same way.

The public URL is invalidated as soon as the session closes, so later requests return 404. You do not need to run a separate command to stop or clean up the tunnel.

Cancellation also applies to individual requests. If a visitor closes the connection while a slow or streaming local response is still running, the gateway tells the preview agent to abort that localhost request.

Commands

farm preview
farm preview --port 3000
farm preview --host 127.0.0.1 --port 3000
farm preview --url http://localhost:4319
farm preview --name stripe-webhook
farm preview --dry-run

When no target is passed, Farm tries to detect a running app from the current project config and common development ports. Pass --port or --url when the app is running somewhere specific.

The pathname in --url is a mount point. For example, --url http://localhost:4319/console forwards the public preview root to /console/ and a public /settings request to /console/settings without allowing the public path to escape that mount.

Options

Option	Purpose
`--port <port>`	Expose a specific local port.
`--host <host>`	Expose a specific local host. Defaults to `localhost`.
`--url <url>`	Expose a full local URL.
`--name <name>`	Request a readable preview URL name.
`--dry-run`	Validate target detection and print the preview plan without opening a session.
`--no-probe`	Skip the local reachability check when `--port` is provided.
`--gateway <url>`	Advanced: use a different Farm Preview gateway.
`--provider <provider>`	Advanced: use `farm` for the hosted gateway or `local` for a custom local provider.

Readable URLs

Use --name when the URL needs to be pasted into a provider dashboard.

farm preview --port 4324 --name stripe-webhook

Farm normalizes the name into a safe subdomain:

https://stripe-webhook.preview.farming-labs.dev

Names are best treated as temporary handles. Stop and restart the command when you want to rotate the session.

Request Logging

Every remote request is visible in the preview terminal:

GET /api-demo-client -> 200 1139ms
GET /@farm/client.js -> 200 1790ms
GET /src/app/api-demo-client/page.tsx?import -> 200 1074ms
GET /api/hello?name=something -> 200 621ms
POST /api/auth/login -> 200 580ms
POST /api/users -> 200 1014ms

The local farm dev terminal also logs the same app-level work:

[FARM] [PAGE] [GET] /api-demo-client - 200 (21ms)
[FARM] [API] [GET] /api/hello?name=something - 200 (5ms)
[FARM] [API] [POST] /api/auth/login - 200 (5ms)

Use the preview terminal to confirm traffic is reaching the tunnel, and use the dev terminal to confirm Farm handled the route, API handler, middleware, or page render.

Interaction Model

The hosted preview forwards HTTP requests from the public URL to your local app. Browser interaction works after the client runtime hydrates.

In development, Vite serves many separate modules before hydration completes. Over a public tunnel that can make the first page load feel slower than localhost. Farm queues button clicks that happen before hydration and replays them after React attaches, so an early click on a client component does not silently disappear.

After hydration, normal client-side handlers run in the browser and API calls go through the preview URL:

"use client";

import { apiClient } from "../lib/api";

export default function Demo() {
  return (
    <button
      onClick={async () => {
        const result = await apiClient.hello.get({
          query: { name: "preview" },
        });
        console.log(result.data);
      }}
    >
      Fetch
    </button>
  );
}

That click is visible as GET /api/hello?name=preview in both the preview and dev terminals.

Webhook Testing

Run the local app:

farm dev --port 4324

Open a named preview:

farm preview --port 4324 --name stripe-local

Use the public route in the provider dashboard:

https://stripe-local.preview.farming-labs.dev/api/stripe/webhook

When the provider sends an event, the preview terminal shows the public request and the dev terminal shows the Farm API route. This is the fastest way to test integration routes before deploying them.

OAuth and Auth Callbacks

For auth providers that require a public redirect URL, use a named preview URL and paste the callback path:

https://auth-check.preview.farming-labs.dev/api/auth/callback

Keep the preview running for the whole login test. If you restart with a different name, update the provider callback URL too.

Hosted Gateway

The default gateway is operated by Farming Labs:

https://preview.farming-labs.dev

Regular Farm apps do not need Vercel, DNS, Redis, ngrok, cloudflared, or a separately installed tunnel binary. The CLI loads @farm.js/tunnel, tries to open one outbound WebSocket to the gateway, and forwards requests through its native Rust transport. Compatibility gateway polling keeps previews available while the hosted relay is being rolled out.

The hosted gateway owns:

TLS for *.preview.farming-labs.dev.
Session creation and expiry.
Request and response relay over the persistent WebSocket or compatibility polling path.
Stale session cleanup.

The local CLI owns:

Local target detection.
Native tunnel lifecycle and local reachability checks.
Forwarding requests to localhost.
Request and response logging.
Closing the preview when the local app exits.

Preview transports currently buffer bodies while carrying them through the relay. Public request and local response bodies are limited to 5 MiB by default; an oversized request receives 413, while an oversized local response receives 502. Self-hosted gateway and relay operators can configure those limits.

Self-Hosting a Gateway

Most app developers should use the hosted gateway. Self-host only when you are operating a private preview domain or maintaining Farming Labs infrastructure.

The gateway example lives in examples/preview-gateway.

cd examples/preview-gateway
pnpm install
vercel deploy

The Vercel example can use Vercel Blob as the session store. Configure a private Blob store for the Vercel project, then set the public domain:

vercel blob create-store farm-preview-gateway --access private --region iad1 --yes
vercel env add FARM_PREVIEW_DOMAIN production

For a private domain such as preview.example.com, configure:

preview.example.com for the gateway root.
*.preview.example.com as a wildcard domain.
FARM_PREVIEW_DOMAIN=preview.example.com.

Then point the CLI at it:

farm preview --gateway https://preview.example.com --name checkout-test

Custom Tunnel Providers

If you need to integrate a private tunnel provider, set FARM_PREVIEW_TUNNEL_COMMAND to a command template that prints the public HTTPS URL after opening the tunnel.

FARM_PREVIEW_TUNNEL_COMMAND='farm-preview-agent tunnel --url {url} --hostname {hostname}' farm preview

Available template values are {url}, {port}, {host}, {name}, and {hostname}.

Use this path only when the hosted Farm gateway is not appropriate for your environment.

Environment Variables

Variable	Purpose
`FARM_PREVIEW_GATEWAY_URL`	Override the hosted gateway URL.
`FARM_PREVIEW_RELAY_URL`	Override the persistent WebSocket relay URL.
`FARM_PREVIEW_DOMAIN`	Override the preview domain used for generated hostnames.
`FARM_PREVIEW_NAME`	Provide a default readable preview name.
`FARM_PREVIEW_PROVIDER`	Select `farm` or `local`.
`FARM_PREVIEW_TUNNEL_COMMAND`	Command template for a custom local tunnel provider.

Troubleshooting

Symptom	Check
`No active Farm preview is running`	The CLI session stopped, expired, or the local app exited. Restart `farm preview`.
`The local Farm preview did not respond before the gateway timed out`	Confirm `farm dev` is still running and the local route is not hanging.
Public page loads, but clicks feel delayed	Wait for the first hydration pass. Dev-mode Vite modules are forwarded through the tunnel. Early button clicks are queued and replayed.
No traffic appears in the preview terminal	The browser may still be loading modules, the URL may be stale, or the request may be blocked before reaching the gateway.
Traffic appears in preview terminal but not `farm dev`	The local target may be wrong. Re-run with `--port` or `--url`.
HMR websocket errors appear in the browser console	The hosted preview currently forwards HTTP traffic. Vite HMR websocket forwarding is not part of the hosted gateway yet.
Webhook provider receives a non-2xx response	Check the local dev terminal for the actual Farm API route error.

Security

The preview URL forwards public internet traffic to your local app. Treat it like a temporary public deployment:

Stop the command when testing is finished.
Do not expose admin-only routes, local dashboards, or secret-bearing pages unless you trust the audience.
Do not paste a preview URL into untrusted systems.
Rotate preview names after sharing sensitive routes.
Keep provider secrets in environment variables, not client code.
Remember that anyone with the URL can send requests while the session is active.

Production Deployments

Use farm preview for temporary access to a running local app. Use farm build and the deployment guide for production releases.

farm build

Preview is for the branch you are holding in your editor. Deployment is for the version you want to keep online.

Edit on GitHubllms.txt llms-full.txt