Instant PreviewCopy Anchor Link

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 StartCopy Anchor Link

Start the app first:

farm dev --port 4324

Open a preview in another terminal:

farm preview --port 4324 --name checkout-test --expires 2h

Previews use a Farm.js Infrastructure API key. Without one, the first preview opens app.farmjs.dev: sign in or create an account (email and password, or GitHub) and confirm the code. The CLI then asks whether to create an API key for this machine; answer yes and it saves the key. If your account already has projects, it offers them, and the one you pick is saved to the app's .env as FARMJS_PROJECT_ID:

Creating public preview for the running app...
Local:  http://localhost:4324
Confirm this code in Farm.js Infrastructure: W7KDQ2PL
Open: https://app.farmjs.dev/device?user_code=W7KDQ2PL
After approving this device, return here.
Create an API key for this machine? (Y/n) y
Signed in to Farm Preview as your Farm.js Infrastructure account.
Use one of your Farm.js Infrastructure projects for this app?
  1) Storefront (Acme)
Project number, or Enter to skip: 1
Saved FARMJS_PROJECT_ID for Storefront to .env.
Relay: wss://preview.farmjs.dev/agent
Opening native Farm preview tunnel...
Preview URL ready.
Public: https://checkout-test.preview.farmjs.dev
Expires: Sep 30, 2026, 3:45 PM
Forwarding requests through the native tunnel until Ctrl+C.

Later previews reuse the saved API key and don't ask again. Pass --login, or run farm login, to get a new one. In an interactive terminal, omitting --expires prompts for a duration and defaults to one hour. In CI and other non-interactive terminals, the hosted default is used.

Farm.js Infrastructure authentication and dashboardCopy Anchor Link

farm preview needs one credential, a Farm.js Infrastructure API key:

• If FARMJS_API_KEY is set, in your shell, your CI secrets, or the app's .env files, it is used and there is no sign-in.
• Otherwise farm login, or the first farm preview, signs you in at app.farmjs.dev and asks whether to create an API key for this machine. Yes saves it in a file only your user can read; no creates nothing. It then offers your existing projects; the one you pick goes into the app's .env as FARMJS_PROJECT_ID. Apps that already set it aren't asked.
• farm logout forgets that saved key on this machine. The key itself stays valid until you revoke it in Farm.js Infrastructure.

1. With a Farm.js Infrastructure API key in FARMJS_API_KEY, the same key analytics uses, the CLI signs in with it and never opens a browser. It reads the key from your shell or your CI secrets, and from the app's .env files the way farm dev does. Set FARMJS_API_URL too if Infrastructure isn't at https://app.farmjs.dev: the key is only sent to a gateway that signs in through that Infrastructure.
2. Without a key or saved login, the CLI opens Farm.js Infrastructure, displays a code, and waits for you to confirm the matching code and explicitly authorize your terminal.
3. Return to the CLI. Choose the preview duration when prompted, or pass --expires.
4. Once the tunnel is ready, the CLI prints its public URL and a dashboard link.

CI never waits for browser approval: set FARMJS_API_KEY, otherwise the command fails with instructions. For CI, create a key restricted to the preview's project, with an expiry, rather than an account-wide key. FARM_PREVIEW_TOKEN is deprecated: it still works and prints a warning, and FARMJS_API_KEY replaces it. Device approval only exists to create the key: the CLI trades the approved sign-in for an API key and keeps nothing else. The gateway verifies that credential or API key whenever it issues a new, name-scoped grant. A grant cannot outlive the verified account session or API key expiry. API keys may be restricted to one project slug: pass the matching --project when starting a preview. With the matching Infra access-control gateway, revoking a key also blocks existing preview traffic. Stop preview in the detail page revokes that grant across reconnects without stopping your local app; start a new farm preview to get another grant. Both transports check access before forwarding. WebSocket relays also check idle connections every five seconds; authority requests have a five-second timeout and fail closed. Work already executed locally cannot be undone. Older gateways without the access hook only enforce key revocation on new grants, so deploy the matching Infra migrations and access endpoint before updating the gateway. Revoking a device account session prevents new grants; stop existing previews separately.

The Previews dashboard shows account-owned connections, expiry, and the latest 200 request metadata records per preview. It refreshes every five seconds and marks missing heartbeats as Stale, not live. Paths, methods, statuses, durations, and times are recorded; query strings, headers, and bodies are excluded. Paths may still contain app identifiers or embedded credentials; never put secrets in URL paths. This is best-effort activity reporting, not an audit log or your application's stdout/stderr. Your app still runs on your computer or CI runner.

Projects and preview detailsCopy Anchor Link

One API key can create multiple previews across multiple projects. The key authenticates your account; it does not define a project. Each run has its own preview ID, detail URL, expiry, and request history. Use a different --name for simultaneously running previews.

farm preview --project storefront --name checkout-review --expires 2h
farm preview --project storefront --name payment-review --expires 1h
farm preview --project docs --name docs-review --expires 1h

The managed CLI defaults the project to a normalized package.json name under --root (or the directory name when no package name exists). Set --project or FARM_PREVIEW_PROJECT to a stable lowercase slug to group runs from different checkouts. Projects are scoped to your account. Older clients are grouped by their preview name.

Filter projects on /dashboard/previews, then open a preview to inspect its transport, credential ID (never the key itself), request paths, response statuses, and timings. Search requests or filter error responses without collecting payloads. The CLI's dashboard link opens that preview directly. Activity is retained until seven days after preview expiry; it is best-effort metadata, not a complete request archive.

This requires matching CLI, gateway, and Infra releases plus database/environment setup.

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.

If a managed native relay disconnects before the printed expiry, the same CLI process reuses its session-scoped grant and continues through compatibility polling. This preserves the preview until its absolute expiry instead of turning a relay invocation limit into a shortened user session.

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

https://checkout-test.preview.farmjs.dev

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

Expiry and Automatic ShutdownCopy Anchor Link

Every hosted preview has an absolute expiry enforced by the gateway and relay. Set it explicitly with minutes, hours, or days:

farm preview --expires 30m
farm preview --expires 2h
farm preview --expires 1d

The hosted service may cap the requested duration. The CLI prints the authoritative expiry returned by the service. Heartbeats do not extend it. After expiration, browser visitors see a friendly Farm preview-expired page.

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. Browser navigation receives an expired preview page; API-style requests receive 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.

CommandsCopy Anchor Link

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 --project storefront --name checkout-review
farm preview --expires 2h
farm preview --login
farm preview --dry-run

Account commandsCopy Anchor Link

farm login
farm whoami
farm logout

farm login signs in and saves an API key without starting a preview. farm whoami prints the gateway, how it signs people in, and which credential farm preview would send: FARMJS_API_KEY (shown by its first characters, never the whole key), the deprecated FARM_PREVIEW_TOKEN, or the saved key. It also says when FARMJS_API_KEY is set but not used, and exits with code 1 when farm preview would need a browser sign-in, so scripts can check first.

farm logout deletes the saved key from this machine. It doesn't revoke it; revoke keys in the Farm.js Infrastructure dashboard.

All three read the app's .env files the way farm preview does, and accept --gateway and --root.

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.

OptionsCopy Anchor Link

Readable URLsCopy Anchor Link

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.farmjs.dev

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

Request LoggingCopy Anchor Link

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 ModelCopy Anchor Link

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 TestingCopy Anchor Link

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.farmjs.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 CallbacksCopy Anchor Link

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

https://auth-check.preview.farmjs.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 GatewayCopy Anchor Link

The default gateway is operated by Farming Labs:

https://preview.farmjs.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.farmjs.dev.
• Developer identity, name authorization, and absolute session expiry.
• Short-lived, single-preview tunnel grants. A shared relay secret is never sent to developers.
• Request and response relay over the persistent WebSocket or compatibility polling path.
• Stale session cleanup.

The local CLI owns:

• Local target detection.
• Farm.js Infrastructure sign-in and the saved API key.
• 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 GatewayCopy Anchor Link

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 managed login, generate two secrets and keep them only on the server:

openssl rand -hex 32
vercel env add FARM_PREVIEW_AUTH_SECRET production
vercel env add FARM_PREVIEW_GATEWAY_SECRET production

FARM_PREVIEW_AUTH_SECRET signs the short-lived tunnel grants. FARM_PREVIEW_GATEWAY_SECRET lets the gateway check API keys with Farm.js Infrastructure at app.farmjs.dev; set the same value there. Neither ever reaches a developer machine. FARM_PREVIEW_DEFAULT_TTL_MS and FARM_PREVIEW_MAX_TTL_MS optionally control the default and maximum hosted durations. See the gateway example README for the deployment order and activity cleanup contract.

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 ProvidersCopy Anchor Link

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 VariablesCopy Anchor Link

TroubleshootingCopy Anchor Link

SecurityCopy Anchor Link

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.
• The CLI saves only the API key, in a file created with user-only permissions. Use --login or farm login to replace it, and farm logout to remove it.
• Tunnel grants are bound to one normalized preview name and one absolute expiry. Current polling control requests send session credentials in the Authorization header. The native agent is configured with one relay URL, so its name-bound grant is carried only on the outbound /agent WebSocket URL; it is never added to the public preview URL. Pre-auth compatibility gateways may still require their random session token in control-request query strings. Gateway operators should redact /agent and legacy control-request query strings from access logs.
• 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 DeploymentsCopy Anchor Link

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.