feat: add Gluetun integration with VPN status widget by Lok3sh-kumar · Pull Request #5812 · homarr-labs/homarr

Lok3sh-kumar · 2026-05-28T16:18:09Z

Adds a Gluetun integration and accompanying dashboard widget surfacing VPN connection details from a running gluetun container.

GluetunIntegration calls the /v1/vpn/status, /v1/dns/status, /v1/publicip/ip and /v1/vpn/settings control endpoints in parallel and maps the results into a flat GluetunStatusInfo
Auth supports either an X-API-Key header or Basic auth from username/password secrets
Cached request handler with a 30s TTL feeds the widget through the gluetun tRPC router
Widget renders a single card for one VPN or a scroll list for many, with VPN/DNS status, public IP, city/country and provider/protocol
Tests: integration class (mocked HTTP), zod schema parsing, widget status-color helper

Homarr

Thank you for your contribution. Please ensure that your pull request meets the following pull request:

Builds without warnings or errors (pnpm build, autofix with pnpm format:fix)
Pull request targets dev branch
Commits follow the conventional commits guideline
No shorthand variable names are used (eg. x, y, i or any abbrevation)
Documentation is up to date. Create a pull request here.

Adds a Gluetun integration and accompanying dashboard widget surfacing VPN connection details from a running gluetun container. - GluetunIntegration calls the /v1/vpn/status, /v1/dns/status, /v1/publicip/ip and /v1/vpn/settings control endpoints in parallel and maps the results into a flat GluetunStatusInfo - Auth supports either an X-API-Key header or Basic auth from username/password secrets - Cached request handler with a 30s TTL feeds the widget through the gluetun tRPC router - Widget renders a single card for one VPN or a scroll list for many, with VPN/DNS status, public IP, city/country and provider/protocol - Tests: integration class (mocked HTTP), zod schema parsing, widget status-color helper Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

dokploy-homarr-labs · 2026-05-28T16:18:15Z

🚨 Preview Deployment Blocked - Security Protection

Your pull request was blocked from triggering preview deployments

Why was this blocked?

User: Lok3sh-kumar
Repository: homarr
Permission Level: read
Required Level: write, maintain, or admin

How to resolve this:

Option 1: Get Collaborator Access (Recommended)
Ask a repository maintainer to invite you as a collaborator with write permissions or higher.

Option 2: Request Permission Override
Ask a repository administrator to disable security validation for this specific application if appropriate.

For Repository Administrators:

To disable this security check (⚠️ not recommended for public repositories):
Enter to preview settings and disable the security check.

This security measure protects against malicious code execution in preview deployments. Only trusted collaborators should have the ability to trigger deployments.

🛡️ Learn more about this security feature

This protection prevents unauthorized users from:

Executing malicious code on the deployment server
Accessing environment variables and secrets
Potentially compromising the infrastructure

Preview deployments are powerful but require trust. Only users with repository write access can trigger them.

Lok3sh-kumar · 2026-05-28T16:31:15Z

manuel-rw · 2026-05-28T18:31:40Z

+  getVpnInfo: publicProcedure.concat(createManyIntegrationMiddleware("query", "gluetun")).query(async ({ ctx }) => {
+    const results = await Promise.all(
+      ctx.integrations.map(async (integration) => {
+        const innerHandler = gluetunVPNStatusHandler.handler(integration, {});
+        const result = await innerHandler.getCachedOrUpdatedDataAsync({ forceUpdate: false });
+        return result.data;
+      }),
+    );
+
+    return results;
+  }),


This works when you refresh the page, but if the VPN goes down while you are on the page, the status will not be updated. Can you check the other integrations and widgets for example implementations on subscriptions?

manuel-rw · 2026-05-28T18:33:54Z

+    const [vpnStatus, dnsStatus, publicIp, vpnSettings] = await Promise.all([
+      this.getVpnStatusAsync(authHeaders),
+      this.getDnsStatusAsync(authHeaders),
+      this.getPublicIpAsync(authHeaders),
+      this.getVpnSettingAsync(authHeaders),
+    ]);


This works, but is there no endpoint to get all data at once? If there is not, you can leave it as is.

@manuel-rw we can't get all the details from one URL that's why it's like this. here is the documentation.

manuel-rw · 2026-05-28T18:34:37Z

+    const integrationInstance = await createIntegrationAsync(integration);
+    return await integrationInstance.getVpnDetailsAsync();
+  },
+  cacheDuration: dayjs.duration(30, "seconds"),


This cache duration is quite aggressive. I think 5 minutes would be fine.

manuel-rw · 2026-05-28T18:35:00Z

+
+  if (integrations.length === 0) {
+    return <EmptyState />;
+  }


Check the other widgets, you can throw an exception in this case.

Remove this check as it can never happen due to an exception that is thrown in item-content.tsx

manuel-rw · 2026-05-28T18:35:07Z

+  if (integrations.length === 1) {
+    const [vpn] = integrations;
+
+    if (!vpn) return <EmptyState />;


Same here, throw instead

The exception is thrown automatically, so no need to handle this. Just use something like

// It will always have at least one integration as otherwise the NoIntegrationSelectedError would be thrown in item-content.tsx // eslint-disable-next-line @typescript-eslint/no-non-null-assertion const integration = integrations[0]!;

or similar

manuel-rw · 2026-05-28T18:36:39Z

Just to be sure; this IP you posted isn't yours, correct?

Lok3sh-kumar · 2026-05-29T02:30:54Z

Just to be sure; this IP you posted isn't yours, correct?

yeah not mine, just a placeholder for screnshot

Meierschlumpf · 2026-05-29T07:36:38Z

+    iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/gluetun.svg",
+    category: ["gluetun"],
+    defaultUrl: "http://localhost:8001",
+    documentationUrl: createDocumentationLink("/docs/integrations/umami"),


Update documentation url and add @ts-expect-error until docs have been created and merged

Meierschlumpf · 2026-05-29T07:37:23Z

+    secretKinds: [["username", "password"], ["apiKey"]],
+    iconUrl: "https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons@master/svg/gluetun.svg",
+    category: ["gluetun"],
+    defaultUrl: "http://localhost:8001",


We haven't specified defaultUrl for other self hosted integrations, therefore I would suggest to remove it here

Meierschlumpf · 2026-05-29T07:39:25Z

  "tracearr",
  "speedtestTracker",
  "umami",
+  "gluetun",


Maybe it makes more sense to have a vpn widget? What do you guys think?

I can work on that, but what else than gluetun would be a candidate?

Meierschlumpf · 2026-05-29T07:41:17Z

Not sure what's your opinion on this @manuel-rw, but I think the value of this test is very limited. Not sure if we can add e2e tests instead that test with a running docker container?

Meierschlumpf · 2026-05-29T08:00:41Z

+export const gluetunPublicIpSchema = z.object({
+  public_ip: z.string(),
+  region: z.string(),
+  country: z.string(),
+  city: z.string(),
+  location: z.string(),
+  organization: z.string(),
+  postal_code: z.string(),
+  timezone: z.string(),
+});


Where did you get this schema from? Based on the docs it only returns the public_ip

If we don't use the fields it might make more sense to add a link to the docs and remove the property so if the field has another format or does not exist for some users, it does not break the integration for them

Same for all other schemas below

@Meierschlumpf the shemas come from this documentation . Since there was not a single endpoint i bunched them together to get the final schema

Meierschlumpf · 2026-05-29T08:06:04Z

Not sure if it is worth to have a test for one simple ternary operator

Lok3sh-kumar requested a review from a team as a code owner May 28, 2026 16:18

Merge branch 'dev' into feat/gluetun-integration

1e4c4eb

Lok3sh-kumar mentioned this pull request May 28, 2026

feat: Gluetun Integration #5158

Open

manuel-rw assigned Lok3sh-kumar May 28, 2026

manuel-rw requested changes May 28, 2026

View reviewed changes

manuel-rw requested a review from Meierschlumpf May 28, 2026 18:36

Meierschlumpf requested changes May 29, 2026

View reviewed changes

Uh oh!

Conversation

Lok3sh-kumar commented May 28, 2026

Homarr

Uh oh!

dokploy-homarr-labs Bot commented May 28, 2026

🚨 Preview Deployment Blocked - Security Protection

Why was this blocked?

How to resolve this:

For Repository Administrators:

Uh oh!

Lok3sh-kumar commented May 28, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

manuel-rw commented May 28, 2026

Uh oh!

Lok3sh-kumar commented May 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants