zuplo 7.0.1 → 7.1.0

package/docs/articles/connect-to-aws-alb-with-mtls.mdx

@@ -1,6 +1,6 @@
 ---
 title: Connect to an AWS ALB with mTLS
-sidebar_label: Connect to an AWS ALB with mTLS
+sidebar_label: AWS ALB
 description:
   Configure Zuplo to authenticate to an AWS Application Load Balancer using a
   mutual TLS client certificate, so the ALB only accepts traffic that comes

package/docs/articles/gke-with-upstream-auth-policy.mdx

@@ -1,6 +1,6 @@
 ---
 title: Secure a GCP Backend with Zuplo Upstream Auth
-sidebar_label: GCP Backend with Upstream Auth
+sidebar_label: GCP Backend
 ---
 
 When using any API gateway as your API's entry point, it's critical that only

package/docs/articles/secure-tunnel.mdx

@@ -1,84 +1,160 @@
 ---
 title: Secure Tunnel
+sidebar_label: Overview
 ---
 
-For customers running on bare metal, on-premises, or other non-cloud providers
-tunnels provides a way to secure your backend without mTLS or IAM.
-
-The way this system works is by deploying a small service inside your network or
-VPC that makes a secure outbound connection to Zuplo's infrastructure. Your
-Zuplo API Gateway can then use this tunnel to securely route traffic to your
-private API. The benefits of a secure tunnel are:
-
-1. Because the tunnel makes an outbound connection, there is no need for your
-   API to be exposed on the internet at all.
-2. All traffic between Zuplo and your API is fully encrypted.
-3. You eliminate the need to configure complex ingress, firewall, or other types
-   of policies to route traffic into your API. Simply install the tunnel and
-   Zuplo takes care of the rest.
-
-## How does the Tunnel Work?
-
-The Zuplo tunnel can run on virtually any Linux-based infrastructure. The most
-common way users install the tunnel is as a Docker container, but it can also
-run directly on a Linux virtual machine or bare-metal server. The tunnel itself
-is a lightweight service that when started makes an outbound connection to the
-Zuplo network and then through to your Zuplo Gateway.
-
-When the tunnel service connects to the Zuplo network, traffic from your gateway
-can be routed to internal services running in your network or VPC. For example,
-if your API is running on the internal DNS address `external-api.local`, the
-tunnel will route traffic from the Zuplo API Gateway to your internal service
-based only on the code and policies you have set up in your Zuplo Gateway.
-
-The example below illustrates how the Zuplo tunnel would be configured in an AWS
-ECS Cluster. Notice that there is no public IP address or ingress traffic in
-this configuration. This is a completely private VPC. The tunnel makes an
-outbound connection to the Zuplo Gateway and then uses internal DNS to route
-requests to the Private API.
-
-![System diagram](../../public/media/secure-tunnel/fefdc7fb-f3b6-4908-8485-3d20cb769cfd.png)
-
-## Is this Secure?
-
-Zuplo builds on top of many different tools to ensure that your gateway and API
-stay secure. Each tunnel uses a secret key that allows it to securely connect to
-Zuplo's network. Under the hood, Zuplo relies on Cloudflare's network for
-establishing secure and reliable tunnel connections. Each tunnel is configured
-with unique access policies that allow only the Zuplo Gateway that you have
-authorized to make connections over that tunnel. Every incoming request is
-terminated using Cloudflare's network which provides sophisticated DDoS, bot,
-and threat protections. Next, the request is routed through your Zuplo Gateway
-which can be configured with all policies and code you require to control access
-to your API. By default, no requests will be routed from your gateway to your
-API until you configure routes, URL rewrites, and policies in your Gateway.
-
-All traffic is terminated at the edge with SSL certificates and encrypted
-through the entire route to your API. All requests that your gateway makes to
-Zuplo's internal services like API Key Management or Rate Limiting are also
-transported over secure and encrypted tunnels.
-
-Every request is logged and you can configure Zuplo's logs to push to the log
-service of your choice.
-
-## How will tunnels perform?
-
-Most customers are fine running two instances of the tunnel service for
-redundancy in the event one pod/service fails. Each tunnel is able to handle
-millions of requests per minute. For customers that require additional scale,
-simply increase the number of tunnel instances you are running or configure auto
-scaling on your deployment. It's unlikely that the tunnel will become the
-bottleneck in your traffic before other factors, but if you do run into any
-issues [contact support](mailto:support@zuplo.com) and we will work out a
-solution that meets your scale requirements.
-
-## How should I Configure the Tunnel?
-
-You should run your tunnel with an IAM role or other network policies that only
-allow the tunnel to make requests to the network services that you want your
-Gateway to access. This can be done in a variety of ways depending on your
-setup. IAM roles, network segregation, and internal service meshes are common
-means of controlling which services the tunnel can access.
-
-For details on how to configure a tunnel on your network see
-[the setup guide](tunnel-setup.mdx).
+<EnterpriseFeature name="Secure tunneling" />
+
+A secure tunnel connects your Zuplo gateway to a backend API that isn't
+reachable from the public internet. You run a small tunnel service inside your
+network, it opens an outbound connection to Zuplo, and your gateway routes
+requests back through that connection to your private API.
+
+Tunnels suit backends that run where IAM roles and mTLS aren't available — bare
+metal, on-premises data centers, or a non-cloud hosting provider. For the other
+ways to secure gateway-to-backend traffic, see
+[Securing your backend](./securing-your-backend.mdx).
+
+A tunnel gives you three things:
+
+- Your API doesn't need to be exposed on the internet at all, because the tunnel
+  dials out rather than accepting inbound connections.
+- All traffic between Zuplo and your API is encrypted.
+- You don't need to configure ingress, firewall rules, or load balancers to let
+  gateway traffic in. Install the tunnel and Zuplo routes to it.
+
+## How a tunnel works
+
+The tunnel is a lightweight service that runs on Linux, most often as a Docker
+container. On startup it authenticates with a token you generate in Zuplo and
+establishes an outbound connection to Zuplo's network.
+
+Once connected, the tunnel can reach internal services on your network by their
+private DNS names. You tell Zuplo which of those services to expose by naming
+them in a tunnel configuration file. Your gateway then calls each one through
+the `service://` URL scheme instead of a hostname. A service named
+`payments-api` becomes `service://payments-api`, and the tunnel forwards those
+requests to whatever internal endpoint you mapped it to, such as
+`http://payments.internal:8080`.
+
+The following diagram shows the path a request takes. Note that the gateway
+never opens a connection into your network — it reuses the connection the tunnel
+already established.
+
+<Diagram height="h-64" direction="horizontal">
+  <DiagramNode id="client">API client</DiagramNode>
+  <DiagramNode id="gateway" variant="zuplo">
+    Zuplo Gateway
+  </DiagramNode>
+  <DiagramGroup id="private" label="Your private network">
+    <DiagramNode id="tunnel" variant="blue">
+      Tunnel service
+    </DiagramNode>
+    <DiagramNode id="api" variant="green">
+      Private API
+    </DiagramNode>
+  </DiagramGroup>
+  <DiagramEdge from="client" to="gateway" label="HTTPS" />
+  <DiagramEdge from="gateway" to="tunnel" label="service://" animated />
+  <DiagramEdge from="tunnel" to="api" fromSide="bottom" toSide="top" />
+</Diagram>
+
+Because the tunnel controls which internal endpoints it forwards to, and Zuplo
+controls which projects and environments can use each service, no traffic
+reaches your API until you configure both halves.
+
+## Architecture example
+
+The following diagram shows a tunnel running in an AWS ECS cluster. The VPC is
+fully private: there's no public IP address and no inbound traffic. The tunnel
+makes an outbound connection to Zuplo, then uses internal DNS to reach the
+private API.
+
+<Framed>
+
+![A tunnel container running in a private AWS VPC, connecting outbound to the Zuplo Gateway and forwarding requests to a private API in the same ECS cluster](../../public/media/secure-tunnel/fefdc7fb-f3b6-4908-8485-3d20cb769cfd.png)
+
+</Framed>
+
+The same pattern applies to Azure Container Instances, GCP Cloud Run,
+Kubernetes, and plain Linux hosts. Only the deployment mechanics change.
+
+## Security model
+
+Zuplo's tunnel is built on [cloudflared](./tunnel-advanced.mdx), Cloudflare's
+open source tunnel connector, and inherits Cloudflare's network for transport.
+Several layers control what can reach your API:
+
+- **Token authentication.** Each tunnel has its own secret token. Without it, a
+  tunnel instance can't connect.
+- **Per-tunnel access policies.** Each tunnel accepts connections only from the
+  Zuplo gateways you authorize.
+- **Per-service scoping.** Each service in your tunnel configuration names the
+  projects and environments allowed to call it, so a preview environment can't
+  reach a production backend unless you say so.
+- **Edge protections.** Incoming requests terminate on Cloudflare's network,
+  which adds DDoS, bot, and threat protection ahead of your gateway.
+- **Gateway policies.** Requests then pass through your Zuplo gateway, where
+  your own policies and code apply. Until you configure routes and URL rewrites,
+  the gateway sends nothing to your API.
+
+Traffic is terminated with TLS at the edge and encrypted for the rest of the
+path to your API. Requests your gateway makes to Zuplo's internal services, such
+as API key management and rate limiting, travel over encrypted connections as
+well.
+
+Every request is logged, and you can
+[forward gateway logs](./monitoring-your-gateway.mdx) to the log service of your
+choice.
+
+## Availability and scale
+
+Each tunnel instance opens several connections to more than one Cloudflare data
+center, so a single instance survives the loss of an individual connection. Run
+at least two instances so the tunnel keeps serving traffic if a host or pod
+fails. Instances that share a token act as replicas of the same tunnel, and
+Zuplo distributes traffic across whichever ones are available.
+
+A single instance handles a high request volume, and adding instances or
+enabling autoscaling raises the ceiling further. If you have specific throughput
+requirements, [contact support](mailto:support@zuplo.com).
+
+## Network access control
+
+The tunnel can reach anything its host can reach, so treat its network position
+as the security boundary. Restrict it to the services you want your gateway to
+call, using whichever mechanism fits your platform:
+
+- IAM roles or service accounts scoped to specific resources
+- Network segmentation, security groups, or egress rules
+- Service mesh authorization policies
+
+Naming a service in your tunnel configuration is what makes it callable from
+Zuplo. Restricting the host is what limits the damage if the tunnel is
+misconfigured. Do both.
+
+## Requirements
+
+Running a tunnel requires:
+
+- A Linux host or container runtime. The
+  [`zuplo/tunnel` image](https://hub.docker.com/r/zuplo/tunnel) is a Linux
+  container, and non-containerized deployments must target Linux.
+- Outbound internet access from the tunnel host, so it can reach Zuplo's
+  network.
+- Internal DNS resolution from the tunnel host to your backend services.
+
+Managed container platforms such as AWS ECS, Azure Container Instances, GCP
+Cloud Run, and Kubernetes run Linux containers by default and need no extra
+configuration.
+
+## Next steps
+
+- [Set up a tunnel](./tunnel-setup.mdx) — create a tunnel, run the container,
+  and expose your first service.
+- [Connect to tunnel services](./tunnel-services.mdx) — call `service://` URLs
+  from your gateway code and configuration.
+- [Advanced tunnel configuration](./tunnel-advanced.mdx) — the cloudflared
+  foundation, environment variable reference, and self-managed images.
+- [Troubleshoot a tunnel](./tunnel-troubleshooting.mdx) — diagnose a tunnel
+  that's down or not passing traffic.

package/docs/articles/securing-backend-mtls.mdx

@@ -1,5 +1,6 @@
 ---
 title: Gateway to Origin mTLS Authentication
+sidebar_label: Gateway to Origin
 ---
 
 <EnterpriseFeature name="mTLS Client Certificates" />
@@ -496,7 +497,7 @@ For more information on securing your backend, see:
 
 - [Securing your Backend](./securing-your-backend.mdx) - Overview of all backend
   security options
-- [Shared Secret / API Key](./securing-your-backend.mdx#1-shared-secret--api-key) -
+- [Shared Secret / API Key](./securing-your-backend.mdx#shared-secret-or-api-key) -
   Alternative approach using shared secrets
 - [Secure Tunnels](./secure-tunnel.mdx) - Connect to private backends without
   exposing them to the internet

package/docs/articles/securing-your-backend.mdx

@@ -8,10 +8,22 @@ correctly applied to all traffic.
 
 ![Zuplo as an API gateway](../../public/media/securing-your-backend/b7290dd1-43fa-49f8-8629-6b4899e2e9f3.png)
 
-To do this, we need to secure the communication between Zuplo and your backend
-APIs (origin). There are several options to do this securely.
+That means securing the communication between Zuplo and your backend API
+(origin). Several options do this, and the right one depends on where your
+backend runs and what it can already verify.
 
-## 1/ Shared secret / API Key
+| Approach                                                       | Use it when                                                                | Plan       |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------- |
+| [Shared secret](#shared-secret-or-api-key)                     | Your backend can check a header. The most common choice, and the simplest. | All        |
+| [IAM authentication](./upstream-iam-auth.mdx)                  | Your backend runs behind AWS, Azure, or Google Cloud IAM.                  | Enterprise |
+| [mTLS](./securing-backend-mtls.mdx)                            | You want both sides to authenticate each other with certificates.          | Enterprise |
+| [Secure tunnel](./secure-tunnel.mdx)                           | Your backend has no public endpoint, or runs on bare metal or on premises. | Enterprise |
+| [Custom networking](#custom-networking-managed-dedicated-only) | You're on managed dedicated and want VPC peering or PrivateLink.           | Dedicated  |
+
+The rest of this page covers the shared secret approach in full. Each other
+approach has its own section in the sidebar.
+
+## Shared secret or API key
 
 This is the most popular option and is used by companies like Supabase,
 Firebase, and Stripe to secure their own APIs. In this solution the backend
@@ -95,62 +107,55 @@ app.use((req, res, next) => {
 });
 ```
 
-## 2/ Federated Authentication
-
-This is a new option where you can configure your cloud service (for example,
-GCP or AWS) to trust a JWT token created by the Zuplo runtime. If you're
-interested in using this option please contact us at `support@zuplo.com`.
+## IAM authentication
 
-## 3/ Upstream Service Authentication
+Let your cloud provider decide whether a request from Zuplo is allowed through.
+Your gateway proves its identity to AWS, Azure, or Google Cloud, and your
+provider's authorization rules apply — so there's no shared secret to
+distribute.
 
-Utilize the IAM controls provided by your Cloud host to secure inbound requests
-and allow only authorized service principals access to your service.
+Where the provider supports it, Zuplo can present a short-lived OIDC token and
+exchange it for temporary credentials, which means no long-lived key exists at
+all. Otherwise the policies use a key or client secret you store as an
+environment variable.
 
-- For Azure users, you can use the
-  [Upstream Azure AD Service Auth](../policies/upstream-azure-ad-service-auth-inbound.mdx)
-  policy. This uses Microsoft Entra ID (formerly Azure AD) App registrations to
-  create a token that Zuplo sends with requests to Azure.
+For the policy for each provider and the trade-off between the two approaches,
+see [IAM authentication for your backend](./upstream-iam-auth.mdx).
 
-- For GCP users, you can use our
-  [Upstream GCP Service AUth](../policies/upstream-gcp-service-auth-inbound.mdx)
-  or [Upstream GCP JWT](../policies/upstream-gcp-jwt-inbound.mdx) policies.
-  These use a `service.json` credential to create or issue JWT tokens that Zuplo
-  will send to requests to GCP.
+## mTLS authentication
 
-## 4/ mTLS Authentication
+Mutual TLS establishes a trust relationship between your gateway and your
+backend using client certificates. Both sides authenticate each other, which
+gives you a zero trust posture between the two.
 
-Mutual TLS (mTLS) authentication allows the configuration of a trust
-relationship between your Zuplo gateway and your backend API using client
-certificates. With mTLS, both your gateway and backend authenticate each other,
-providing a "Zero Trust" security model that's popular with enterprise
-customers.
-
-To learn how to set up mTLS with client certificates, see the
-[Securing your Backend with mTLS](./securing-backend-mtls.mdx) article. This is
+Zuplo manages the client certificates, presents them on upstream requests, and
+supports rotation and per-environment certificates. See
+[Gateway to origin mTLS authentication](./securing-backend-mtls.mdx). For a
+worked example against an AWS load balancer, see
+[Connect to an AWS ALB with mTLS](./connect-to-aws-alb-with-mtls.mdx). This is
 an [enterprise feature](https://zuplo.com/pricing).
 
-## 5/ Secure Tunneling
+## Secure tunneling
+
+A [secure tunnel](./secure-tunnel.mdx) runs a small connector inside your VPC or
+private data center that makes an outbound connection to your Zuplo gateway. It
+suits workloads without IAM or mTLS capabilities — bare metal, on premises, or a
+non-cloud provider. Your backend needs no public endpoint at all.
 
-Used by some of our larger customers, our [secure tunnels](./secure-tunnel.mdx)
-allow you to create a WireGuard based tunnel from your VPC or private
-data-center that connects directly to your Zuplo gateway. This option is useful
-when running workloads in a non-cloud provider (for example, bare metal, on
-premises, etc.) that don't have IAM or mTLS capabilities. In this solution, your
-backend API doesn't need to be exposed to the internet at all. This is a more
-complex setup and is only available on our
+This is a more involved setup than the other options and is available on the
 [enterprise plan](https://zuplo.com/pricing).
 
-To discuss security and connectivity options, our
-[discord channel](https://discord.zuplo.com) is a great community, with active
-participation from the Zuplo team.
+## Custom networking (managed dedicated only)
+
+On the managed dedicated plan, Zuplo can provide custom networking to reach your
+backend, using your cloud provider's VPC connectivity — AWS Transit Gateway,
+PrivateLink, or VPC peering.
 
-## 6/ Custom Networking (Managed Dedicated Only)
+For more information, see the
+[networking documentation](../dedicated/networking.mdx).
 
-For customers on our managed dedicated plan, we can provide custom networking to
-connect your backend to Zuplo. This can include using VPC connectivity
-capabilities from your cloud provider (for example AWS, Azure, GCP, etc.) such
-as AWS Transit Gateway, PrivateLink, or VPC Peering to connect to your backend
-services.
+## Get help choosing
 
-For more details on networking options for managed dedicated customers, see our
-[Networking documentation](../dedicated/networking.mdx).
+To discuss security and connectivity options, the
+[Zuplo Discord](https://discord.zuplo.com) has active participation from the
+Zuplo team, or contact [support](mailto:support@zuplo.com).

package/docs/articles/tunnel-advanced.mdx

@@ -0,0 +1,202 @@
+---
+title: Advanced Tunnel Configuration
+sidebar_label: Advanced
+---
+
+<EnterpriseFeature name="Secure tunneling" />
+
+The [`zuplo/tunnel`](https://hub.docker.com/r/zuplo/tunnel) image covers most
+deployments without configuration beyond `TUNNEL_TOKEN`. This page is for teams
+that need more control: pinning versions, tuning the transport, rotating tokens,
+or building and running the connector image themselves.
+
+## The cloudflared foundation
+
+Zuplo's tunnel is a thin packaging of
+[cloudflared](https://github.com/cloudflare/cloudflared), Cloudflare's open
+source tunnel connector. It isn't a Zuplo-specific protocol or a proprietary
+agent. The entire `zuplo/tunnel` image is the upstream
+[`cloudflare/cloudflared`](https://hub.docker.com/r/cloudflare/cloudflared)
+image with a fixed entrypoint:
+
+```dockerfile title="Dockerfile"
+FROM cloudflare/cloudflared:2026.7.3-amd64
+ENTRYPOINT ["cloudflared", "tunnel", "--no-autoupdate", "--protocol", "http2", "run"]
+```
+
+Two consequences follow from this. First, everything the
+[cloudflared documentation](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/)
+says about deploying, monitoring, and tuning a connector applies to your Zuplo
+tunnel. Second, you can run the upstream image yourself instead of Zuplo's — see
+[Run your own connector image](#run-your-own-connector-image).
+
+### Entrypoint flags
+
+| Flag               | Why the image sets it                                                                                                                                                                                                                        |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--no-autoupdate`  | Stops cloudflared from replacing its own binary while running. The image tag is then the only thing that determines the version, which keeps containers immutable and deployments reproducible.                                              |
+| `--protocol http2` | Forces the HTTP/2 transport. The cloudflared default, `auto`, prefers QUIC over UDP port 7844 and falls back to HTTP/2 when it can't open UDP connections. Many corporate networks block outbound UDP, so pinning HTTP/2 skips the fallback. |
+| `run`              | Runs a remotely-managed tunnel. The tunnel's routing configuration lives in Zuplo, not in a local config file, and cloudflared reads its credentials from `TUNNEL_TOKEN`.                                                                    |
+
+### Container characteristics
+
+Because the image inherits the upstream cloudflared base, it has properties
+worth knowing when you write a deployment manifest or a security policy:
+
+- **Distroless base, no shell.** You can't exec into a running tunnel container
+  to debug it. Run a separate debug container in the same network namespace
+  instead — see
+  [Check connectivity to your backend](./tunnel-troubleshooting.mdx#check-connectivity-to-your-backend).
+- **Runs as a non-root user** (UID 65532). It needs no elevated privileges, no
+  additional Linux capabilities, and no writable root filesystem.
+- **Needs no persistent volume.** The tunnel holds no state between restarts and
+  fetches its configuration from Zuplo on startup.
+- **Listens on no inbound ports** unless you set `TUNNEL_METRICS`.
+
+## Environment variables
+
+The tunnel reads cloudflared's environment variables. The ones that matter for a
+Zuplo tunnel:
+
+| Variable                    | Default | Description                                                                                            |
+| --------------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `TUNNEL_TOKEN`              | none    | The tunnel's connection token, from `zuplo tunnel describe`. Required.                                 |
+| `TUNNEL_LOGLEVEL`           | `info`  | Log verbosity. One of `debug`, `info`, `warn`, `error`, or `fatal`. Use `debug` when troubleshooting.  |
+| `TUNNEL_METRICS`            | none    | Address to serve Prometheus metrics on, such as `0.0.0.0:2000`. Useful for scraping connection health. |
+| `TUNNEL_TRANSPORT_PROTOCOL` | `auto`  | Transport to Cloudflare's edge. One of `auto`, `http2`, or `quic`.                                     |
+| `NO_AUTOUPDATE`             | `false` | Disables in-place binary updates.                                                                      |
+| `TUNNEL_EDGE_IP_VERSION`    | `4`     | IP version for reaching the edge. One of `4`, `6`, or `auto`.                                          |
+
+:::caution{title="Flags override environment variables"}
+
+The `zuplo/tunnel` image sets `--no-autoupdate` and `--protocol http2` as
+command-line flags in its entrypoint, and cloudflared gives command-line flags
+precedence over environment variables. Setting `NO_AUTOUPDATE` or
+`TUNNEL_TRANSPORT_PROTOCOL` on a `zuplo/tunnel` container has no effect. To
+change either one, build your own image with a different entrypoint.
+
+:::
+
+## Pin and upgrade the image version
+
+The `zuplo/tunnel` tags mirror the cloudflared release they wrap, so
+`zuplo/tunnel:2025.10.1` contains cloudflared 2025.10.1. The `latest` tag always
+points at the most recent release.
+
+For production, pin an explicit tag rather than using `latest`, so a redeploy
+can't silently change connector versions:
+
+```bash
+docker run -d --name zuplo-tunnel \
+  -e TUNNEL_TOKEN=<YOUR_TUNNEL_TOKEN> \
+  zuplo/tunnel:2025.10.1
+```
+
+Then upgrade deliberately. Cloudflare supports cloudflared versions released
+within one year of the most recent release, and may introduce breaking changes
+that affect older versions. Check for a newer tag on a regular cadence and treat
+the upgrade as routine maintenance. Test each new version in a staging
+environment before rolling it out to production.
+
+Because tunnel instances that share a token act as replicas, you can upgrade
+without downtime: start instances on the new version, wait for them to connect,
+then stop the old ones.
+
+## Rotate the tunnel token
+
+Rotate a token on a schedule, and immediately if you suspect it's been exposed.
+With at least two instances running, you can rotate without dropping traffic.
+
+<Stepper>
+
+1. Issue a new token for the tunnel:
+
+   ```bash
+   zuplo tunnel rotate-token --tunnel-id tnl_TRMZwunq2PLNQDwhu6A04Bmx
+   ```
+
+   After rotation, the old token can't establish _new_ connections, but
+   instances already connected with it keep serving traffic.
+
+1. Update the token in your secret manager.
+
+1. Restart half your instances so they pick up the new token, and wait for them
+   to report as connected.
+
+1. Restart the remaining instances.
+
+</Stepper>
+
+Rotating with a single instance running causes a brief interruption while the
+instance restarts. Schedule it during a maintenance window.
+
+## Run your own connector image
+
+Because the tunnel is stock cloudflared, you can build and run the connector
+yourself. Consider this when you need to:
+
+- Change the entrypoint flags, such as running QUIC instead of HTTP/2, or
+  exposing the metrics endpoint.
+- Mirror the image into your own registry to satisfy a policy that forbids
+  pulling from public registries.
+- Meet a scanning, signing, or base-image requirement your platform enforces.
+- Run on `arm64`, using a matching upstream tag.
+
+To match the behavior of `zuplo/tunnel`, build from the upstream image and
+replicate the entrypoint:
+
+```dockerfile title="Dockerfile"
+FROM cloudflare/cloudflared:2026.7.3-amd64
+ENTRYPOINT ["cloudflared", "tunnel", "--no-autoupdate", "--protocol", "http2", "run"]
+```
+
+Replace `2026.7.3` with a current tag from
+[Docker Hub](https://hub.docker.com/r/cloudflare/cloudflared/tags) — a version
+pinned here goes stale, and running a connector more than a year behind the
+latest release falls outside Cloudflare's support window. Use the `-amd64` or
+`-arm64` suffix that matches your host architecture.
+
+Build and run it with the same `TUNNEL_TOKEN` you'd give the Zuplo image:
+
+```bash
+docker build -t my-registry/tunnel:2026.7.3 .
+docker run -d --name tunnel \
+  -e TUNNEL_TOKEN=<YOUR_TUNNEL_TOKEN> \
+  my-registry/tunnel:2026.7.3
+```
+
+You can also run the upstream image directly, without a Dockerfile, by supplying
+the command yourself:
+
+```bash
+docker run -d --name tunnel \
+  -e TUNNEL_TOKEN=<YOUR_TUNNEL_TOKEN> \
+  cloudflare/cloudflared:2026.7.3-amd64 \
+  tunnel --no-autoupdate --protocol http2 run
+```
+
+:::caution
+
+Keep the `run` subcommand and don't add a local configuration file, credentials
+file, or `--url` argument. Your tunnel is remotely managed: Zuplo owns the
+routing configuration, and cloudflared fetches it using the token. Local
+configuration conflicts with that and can stop traffic reaching your services.
+
+:::
+
+:::note
+
+Zuplo tests and supports the `zuplo/tunnel` image. A connector image you build
+and operate yourself is yours to maintain, and support can help with the tunnel
+and its configuration in Zuplo but not with your image or build pipeline. If
+you're unsure whether a change is safe, ask
+[Zuplo support](mailto:support@zuplo.com) before rolling it out.
+
+:::
+
+## Next steps
+
+- [Troubleshoot a tunnel](./tunnel-troubleshooting.mdx) — diagnose a tunnel
+  that's down or not passing traffic.
+- [Connect to tunnel services](./tunnel-services.mdx) — the service
+  configuration reference and `service://` usage.