Preview Tunnel & Gateway

Relevant source files

The following files were used as context for generating this wiki page:

• ARCHITECTURE.md
• AGENTS.md
• packages/farm/src/vite.ts
• packages/farm/src/docs/index.ts
• packages/farm/src/tests/docs-handler.test.ts

The Preview Tunnel and Gateway systems facilitate the secure exposure of local Farm.js development environments to external networks. These components enable real-time collaboration, agent-based discovery, and remote testing of applications built with the Farm.js framework.

The system integrates with the core Request Flow of the Farm.js architecture. It leverages the Vite development server to intercept non-asset requests and route them through the appropriate handlers, ensuring that remote previews maintain the same behavior as local development instances.

Sources: ARCHITECTURE.md:43-52, AGENTS.md:10-15

System Architecture

The Preview Tunnel architecture creates a bridge between a local developer machine and a public gateway. This bridge allows external users or AI agents to access the local Vite development server without complex firewall configurations.

The diagram shows the request flow from an external client through the gateway and relay into the Farm.js core components.
Sources: ARCHITECTURE.md:12-25, packages/farm/src/vite.ts:1145-1160

Key Components

Component	Description
Preview Gateway	A public-facing server that accepts incoming HTTP/WebSocket requests and routes them to the correct local relay.
Preview Relay	A local client running alongside the Farm.js project that maintains a persistent connection to the Gateway.
Vite Middleware	Intercepts requests arriving at the local server to resolve them via the Farm.js Route Manager.
Route Manager	Matches incoming URL paths to specific page.tsx or route.ts handlers.

Sources: ARCHITECTURE.md:31-41, packages/farm/src/vite.ts:1210-1225

Request Handling and Security

The gateway validates incoming requests before forwarding them to the local tunnel. It ensures that only authorized traffic reaches the development server. The local Vite plugin provides a middleware layer that manages these incoming requests.

Middleware Integration

The Farm.js Vite plugin injects middleware that handles both API and page requests. When a request arrives via the tunnel, the system:

1. Resolves the requested URL using resolveFarmRequestURL.
2. Checks if the path belongs to an internal API (e.g., /api/docs or /__farm/page-data).
3. Executes application middleware managed by the MiddlewareManager.
4. Renders the appropriate React Server Component (RSC) or API response.

Sources: packages/farm/src/vite.ts:1095-1110, packages/farm/src/vite.ts:1340-1355

Sequence of Operation

The sequence diagram illustrates an AI agent requesting a discovery file through the preview system.
Sources: packages/farm/src/vite.ts:1260-1280, packages/farm/src/tests/docs-handler.test.ts:474-485

AI-Native Discovery via Tunnels

A primary use case for the Preview Tunnel is enabling AI agents to discover application capabilities remotely. The system automatically serves specific discovery routes when accessed through the gateway.

Supported Discovery Routes

Path	Format	Purpose
/llms.txt	text/plain	Lists available documentation and routes for LLMs.
/AGENTS.md	text/markdown	Provides specific instructions for AI agents.
/.well-known/agent.json	application/json	Defines agent capabilities and route specifications.
/api/docs	application/json	Provides programmatic access to site documentation.

Sources: packages/farm/src/vite.ts:1257-1265, packages/farm/src/tests/docs-handler.test.ts:503-520

Configuration

Tunnel behavior is configured via farm.config.ts. The agent and docs sections determine which discovery features are enabled for remote previews.

export default defineConfig({
  agent: {
    llmsTxt: {
      enabled: true,
      full: true
    }
  },
  docs: {
    enabled: true,
    entry: "/docs"
  }
});

Sources: packages/farm/src/vite.ts:103-108, packages/farm/src/vite.ts:1240-1250

Conclusion

The Preview Tunnel & Gateway system provides a seamless bridge for remote access to local development servers. By integrating directly with the Vite middleware and Farm.js Route Manager, it ensures that external clients and AI agents receive accurate, dynamically rendered responses while maintaining project security and standard web-platform semantics.