Add local proxying docs

Author: ostenbom

src/assets/local-server-traffic.png

@@ -61,3 +61,7 @@ Endform has two additional ways of transferring state to the remote runners:
 - **Files** - `additionalFiles` in your `endform.jsonc` config
 
 For more information on these options, see the [endform config reference](/docs/reference/endform-config).
+
+## Transfering network traffic from the remote runners
+
+To find out more about how to direct traffic from the remote runners to your local network, see the [proxy traffic via your local network](/docs/guides/proxy-via-local) guide.

src/content/docs/explanation/transfer-state-to-remote-runners.mdx

@@ -3,26 +3,51 @@ title: Getting Started
 description: Running your tests with Endform for the first time.
 ---
 
-import { Aside } from '@astrojs/starlight/components';
+import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
 
 Make sure to check out the [requirements](/docs/reference/requirements) before you start.
 
 # Getting Started
 
 The easiest way to get started with endform, and to check if your setup is compatible with endform at the moment, is to run the endform cli from your playwright project directory.
 
-```
+```sh
 npx endform@latest test
 ```
 
 This will prompt you to login and run your tests.
 
-<Aside>
 
-Since endform is currently in beta, we recommend _not_ pinning the version of endform in your `package.json`, and instead "always running latest" by running `npx endform@latest test`.
+# Install the `endform` CLI
+
+<Tabs syncKey="pkg">
+   <TabItem label="npm">
+   ```sh
+   npm install endform
+   ```
+   </TabItem>
+   <TabItem label="pnpm">
+   ```sh
+   pnpm install endform
+   ```
+   </TabItem>
+   <TabItem label="Yarn">
+   ```sh
+   yarn install endform
+   ```
+   </TabItem>
+   <TabItem label="Bun">
+   ```sh
+   bun install endform
+   ```
+   </TabItem>
+</Tabs>
 
+<Aside>
+Since endform is currently in beta, we reccomend a very high update cadence of the CLI. Please try to keep within the _last 2 weeks_ of releases.
 </Aside>
 
+
 # Running your tests in CI
 
 Once you have your tests passing with endform from your machine, you might want to run endform in your CI pipeline.
@@ -33,7 +58,7 @@ The easiest way to do this is to replace your "playwright test" command with "en
 
 Here's an example of a what a GitHub Actions workflow might look like:
 
-```
+```yml
 name: Run Playwright tests with Endform
 on:
   push:
@@ -54,7 +79,7 @@ jobs:
         run: npm install
 
       - name: Run tests with Endform
-        run: npx endform@latest test
+        run: npx endform@latest test # or npm run endform test
         env:
           ENDFORM_API_KEY: ${{ secrets.ENDFORM_API_KEY }}
 ```

src/content/docs/guides/getting-started.mdx

@@ -0,0 +1,92 @@
+---
+title: Proxy traffic via your local network
+description: How to proxy traffic from your remote runners to your local network. This helps to run tests against local servers.
+---
+
+import { Steps, Tabs, TabItem, Code, Aside } from '@astrojs/starlight/components';
+
+import { Image } from "astro:assets";
+import LocalTraffic from "../../../assets/local-server-traffic.png";
+
+Servers that you want to test against that are either running locally or within a private network are not automatically exposed to the internet.
+These servers are not reachable by default from the remotely running Playwright instances.
+Trying to reach them without this extra setup, would likely result in connection errors in your tests.
+
+
+When this happens, we need a method of shuttling traffic between the remote runners and the servers running on your local network. 
+
+<Image
+  src={LocalTraffic}
+  alt="A diagram of the traffic from the remote runners through your CLI to your local server."
+  height={500}
+/>
+
+Endform has the ability to connect the remote Playwright runners to the servers on your local network via direct, hole-punched, encrypted, peer-to-peer connections.
+We can do this by utilizing the [iroh network](https://www.iroh.computer/docs/overview).
+
+## Setting up endform to proxy traffic
+
+<Aside>
+Proxying traffic via your local network is currently in alpha, we would be grateful for any feedback you have on this feature.
+</Aside>
+
+
+<Steps>
+
+1. ### Install the addon package
+
+   In order for traffic to be proxied, we need to install the extra `endform-proxy-network` package in the same place as you installed the main `endform` CLI.
+
+   <Tabs syncKey="pkg">
+      <TabItem label="npm">
+      ```sh
+      npm install endform-proxy-network
+      ```
+      </TabItem>
+      <TabItem label="pnpm">
+      ```sh
+      pnpm install endform-proxy-network
+      ```
+      </TabItem>
+      <TabItem label="Yarn">
+      ```sh
+      yarn install endform-proxy-network
+      ```
+      </TabItem>
+      <TabItem label="Bun">
+      ```sh
+      bun install endform-proxy-network
+      ```
+      </TabItem>
+   </Tabs>
+
+2. ### Configure which traffic to proxy.
+   
+   #### As a playwright `webServer`
+   If you want to run your local server as a [playwright `webServer`](https://playwright.dev/docs/api/class-testconfig#test-config-web-server)
+   then you're done! Leave your web server configuration as is, and we will automatically proxy the traffic to your local server.
+
+   #### With your own custom server
+   If you're running a server outside of playwright - that's fine. You can tell endform which traffic to proxy by using a `endform.jsonc` file.
+
+   <Code language="json" title="endform.jsonc" code={`
+   {
+      "proxyNetworkHosts": [
+        "<loopback>",
+        "*.my-special-domain.com"
+      ]
+   }
+   `} />
+
+   You can read more about the `proxyNetworkHosts` configuration in the [endform config reference](/docs/reference/endform-config#proxy-network-hosts).
+
+3. ### Run your tests!
+
+   That's it! You can now run your tests as normal, and the traffic will be proxied via the cli to your target server.
+
+
+
+
+
+
+</Steps>

src/content/docs/guides/proxy-via-local.mdx

@@ -12,7 +12,7 @@ Endform is:
 - A very fast _remote_ test runner for your playwright end-to-end tests.
 - (Soon) A dashboard for viewing and analyzing your test results.
 
-Endform is currently in early beta. If you're here, it's probably because we've given you early access,
+Endform is currently in beta. If you're here, it's probably because we've given you early access,
 and we appreciate you taking the time to try it out.
 
 ## Guides

src/content/docs/index.mdx

@@ -18,7 +18,7 @@ Currently, `endform.jsonc` supports the following options:
 
 `additionalFiles`: an array of strings used as globs to send extra files to your test machines.
 
-```
+```json
 {
   "additionalFiles": ["user-state/*"]
 }
@@ -31,7 +31,7 @@ However if your tests have implicit dependencies on more files, use this paramet
 
 `environmentVariables`: an array of string regular expressions that are used to match environment variables that should be transferred to the remote runners.
 
-```
+```json
 {
   "environmentVariables": ["VERCEL_.*"]
 }
@@ -41,3 +41,20 @@ By default the following environment variables are automatically transferred:
 
 - Environment variables that start with `E2E_`
 - All environment variables that are set in your `playwright.config.ts`
+
+### `proxyNetworkHosts`
+
+Choose which host names will have their traffic redirected to the CLI from the remote runners.
+All the traffic sent from the remote runners to your CLI is sent encrypted over direct peer-to-peer connections. Read more about [traffic to local servers here](/docs/guides/proxy-via-local).
+
+```json
+{
+    "proxyNetworkHosts": ["*.test.internal-domain", "*.staging.internal-domain", "<loopback>"]
+}
+```
+
+Each string in the array is a match rule. Either:
+
+- A hostname pattern `my-domain.com`, `*.interal.org`
+- An IP literal like `127.0.0.1`
+- `<loopback>` to match interfaces `localhost`, `*.localhost`, `127.0.0.1`, `[::1]`

src/content/docs/reference/endform-config.md

@@ -16,17 +16,18 @@ If you keep your tests decoupled from your application already by, for example,
 
 ### Remote
 
-Since your tests will be running on remote machines, your test environment needs to be accessible on the public internet.
-Endform does not support servers running "locally" / on `localhost`.
+Since your tests will be running on remote machines, the servers you are testing against need to be accesible to the remote runners.
+There are two ways to acheive this:
 
-We reccomend using playwright directly when creating tests / running against `localhost`, and to run endform in your ci environment / against your test/stage/preview environments.
+- You are running preview infrastructure or a testing environment that is exposed to the internet anyway.
+- You can use the `endform-proxy-network` addon to shuttle traffic between the remote runners and the machine your CLI runs on. Check out the [guide on proxying traffic via your local network](/docs/guides/proxy-via-local) for more information about this approach.
 
 ## Playwright Requirements
 
 - We support playwright projects written in typescript and javascript.
 - The length of an individual test run is limited to 4 minutes (same as the `testConfig.timeout` option). The playwright default timeout is 30 seconds. This does not include retries.
 - We currently only support the latest minor version of playwright (`1.53.0` at the time of writing).
-- We currently only support Chrome. We run the same version of Chrome as the playwright version you are running ships with.
+- We currently only support Chrome. We run the same version of Chrome as the playwright version you are running ships with. Let us know if you are in need of more browsers and we can prioritise this.
 
 ### Playwright Configuration Options
 
@@ -42,8 +43,7 @@ Options that we currently don't support, but will do in the future (let us know
 
 Options that aren't supported since they don't make sense in a remote context:
 
-- `webWorkers`
-- `fullyParallel` is always `true`
+- `fullyParallel` is always `true`, but you can limit concurrency using settings in the endform dashboard.
 
 ## Node Requirements