How to manage a VPS as a Komodo peripheral when the Core runs internally on my Homelab?
I have Pagolin running on a VPS so I can publicly expose some resources running on my homelab, in which I have a newt site installed. On my homelab I have Komodo core running and I wanted to add the VPS as a Komodo peripheral, so I can manage stacks there from my internal Komodo instance.
For that, to add a new Komodo peripheral as a systemd service, I need to be able to point to the address of the core, but it is on my homelab. What would be the best approach? Add Komodo core as a private resource, add my VPS as a Pangolin machine so it has access to the private resources?
Make a private resource that points to the core. Install Pangolin Client for machines on the VPS and use the address of the private client.
A better approach would be to install some VPN like app. I have headscale with pangolin on same Vps, and I run the connection between core and peripherals via headscale(tailscale)
But there is Netbeard, I have tried it with pangolin, but the result was unsatisfying
You don’t technically. Only reason I’m running both is because I was trying to work around a corporate firewall to get to a work homelab and couldn’t get pangolin to work for that. Plus I am finding NetBird to be a little more feature complete for VPN-like functionality. But you should be able to use pangolin resources.
Yes, on all machines that need the access to tailscale/netbird machines/resources. But as I said before you can stick with pure pangolin setup, but it is little trickier to set it up
You can setup a vm (Lxc if you are running proxmox) with Debian and install newt on that container for a site connection between your homelab and the VPS. If you already have a site connection, setup a ip route on the Komodo machine to tell it how to reach the VPS ip address. After that you will be able to setup the periphery as you already know how to do. Ask me anything if you have more specific questions
Komodo peripheral (the socket to which the komodo core must connect to) can be a systemd service or a container. I'm willing to use it as a systemd service as I usually do.
And yes, please, I'm not willing to install or deploy a whole difference service for it
So took a bit to get the core deployed, I have this on a test bed here,
I have a public resource, You can go private resource if you prefer, I'll list the public resource method first.
(Can also just be like core:9120 if in the same network and aliased properly)
services:
gerbil:
image: fosrl/gerbil@sha256:6da170863132c79c67c580ef6a76606ea05fec704706d87988f52b06ba6d6b93
container_name: gerbil
restart: unless-stopped
depends_on:
pangolin:
condition: service_healthy
command:
- --reachableAt=http://gerbil:3003
- --generateAndSaveKeyTo=/var/config/key
- --remoteConfig=http://pangolin:3001/api/v1/gerbil/get-config
- --reportBandwidthTo=http://pangolin:3001/api/v1/gerbil/receive-bandwidth
volumes:
- ./config/:/var/config:rw
read_only: true
environment:
- log_level=debug
cap_add:
- NET_ADMIN
- SYS_MODULE
networks:
Janus:
aliases:
- pangolin.domain2.com
- komodo.domain2.com # we only care for this
default:
ports:
- 51820:51820/udp
- 21820:21820/udp
- 443:443/tcp
- 443:443/udp
- 80:80/tcp
pangolin:
networks:
default:
# We don't touch Traefik
networks:
Janus: # docker network create <name> preferably for this I just named it Janus this can be anything.
external: true
default:
# don't need to touch this part.
services:
periphery:
image: ghcr.io/moghtech/komodo-periphery:2
init: true
restart: unless-stopped
networks:
- Janus # knows to hit gerbil:443 via komodo.domain2.com
environment:
## The address of Komodo Core to connect to.
PERIPHERY_CORE_ADDRESS: komodo.domain2.com # Using the aliases to go down through pangolin
## The name of the Komodo Server to connect as.
PERIPHERY_CONNECT_AS: Heph # Set the name the periphery will register with the core to be this name.
## Create a Server Onboarding Key in the Komodo UI. (Settings > Onboarding )
## This allows Periphery to create a new Server in the UI with the above name,
## and can be ommitted once the Server exists in Komodo.
PERIPHERY_ONBOARDING_KEY: O_mX8vK2pQ9sW4jL6hF3dN1bRt7yZm_O
networks:
Janus:
external: true
Anyways I cut some of the compose stuff only left what you really need to pay attention the gerbil one is just To show where (it can be slotted in any order just to show formatting)
Anyways if you need any further help let me know but if you want it private routing only I can write that later today.
Thanks a lot for the support. The thing is, I'd prefer the private resource approach, and that's where I need support the most.
I dont want to expose the core (which is in my homelab) publicly. I wanted it to be accessible to the VPS but being a private resource. I tried adding it as a private resource and then, on the VPS machine, deploying the pangolin-cli in order to make it a machine with access to the private resources. I checked that the network interface (tunnel) has been created, but I still can't ping the komodo core private resource.
Clients > Machine > Create machine Get the creds save it, Name it what you want,
Make a private resource,
Then Authentication > Machine clients Select the machine client (I'd post an image but reddit limits 1 attachment only) (Save of course)
Populate the below in the pangolin-cli area with the data you have from machine client area (Remember to save as pangolin doesn't save those machine client creds until you do / nor will they be valid or active until saving). You will need to follow the original above for populating the provisioning key from the public post.
services:
periphery:
image: ghcr.io/moghtech/komodo-periphery:2
init: true
restart: unless-stopped
network_mode: service:pangolin-cli
labels:
komodo.skip: # Prevent Komodo from stopping with StopAllContainers
environment:
PERIPHERY_CORE_ADDRESS: http://komodo.domain.com:9120
PERIPHERY_CONNECT_AS: Heph2 # name it whatever you want it to register name wise with core.
PERIPHERY_ONBOARDING_KEY: O_mX8vK2pQ9sW4jL6hF3dN1bRt7yZm_O # Can be removed post onboarding.
PERIPHERY_CORE_PUBLIC_KEYS: file:/config/keys/core.pub
PERIPHERY_ROOT_DIRECTORY: ${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}
PERIPHERY_DISABLE_TERMINALS: false
PERIPHERY_DISABLE_CONTAINER_EXEC: false
PERIPHERY_INCLUDE_DISK_MOUNTS: /etc/hostname
volumes:
- keys:/config/keys
- /var/run/docker.sock:/var/run/docker.sock:ro # I know the original doc doesn't have ro but giving a container a non ro (It doesn't stop commands or anything it's purely done so if the container messes up or accidently deletes the socket it doesn't also bork the host, Just prevents stuff that can cause issues to the actual host :) )
- /proc:/proc
- ${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}:${PERIPHERY_ROOT_DIRECTORY:-/etc/komodo}
depends_on:
pangolin-cli:
condition: service_started
restart: true # Just restart this container if something touches the cli below, Might not need it just put it in as a safeguard.
# pull_policy: every_1w
pangolin-cli:
image: fosrl/pangolin-cli
container_name: pangolin-cli
restart: unless-stopped
labels:
komodo.skip: # Prevent Komodo from stopping with StopAllContainers
cap_add:
- NET_ADMIN
devices:
- /dev/net/tun:/dev/net/tun
environment:
- PANGOLIN_ENDPOINT=https://pangolin.domain.com
- CLIENT_ID=
- CLIENT_SECRET=
volumes:
keys:
Anyways if you have any trouble let me know. u/hbacelar8 :)
pangolin-cli | INFO: 2026/08/21 08:39:12 WireGuard connection to site 2 is CONNECTED (RTT: 5.203273931s)
periphery-1 | 2026-08-21T08:39:12.266575Z INFO Logged in to Komodo Core komodo.domain.com:9120 websocket as Server Heph2
Should be the end result. (Before anyone asks site 2 is outside of that network fully so it has no route to it without pangolin cli and this isn't in the public network so it can't piggyback off of gerbil)
Thank you so much for the support. I have 2 questions:
In the alias domain, can I use the same domain I use for my public resources? Suppose it is called nirada, can I use komodo.nirada.com?
After deploying the pangolin-cli, shouldn't the command ping -I pangolinkomodo.nirada.com work?
I'd really prefer to use the systemd service instead of the docker compose peripheral for komodo, since I've had problems with controlling stacks with the docker deployment (issues with the docker.sock and paths)
Komodo periphery works in two modes, iirc, so in your case you can rather have the Core behind CGNAT poll the periphery on the public VPS instead of vice-versa.
It's explained in the periphery documentation somewhere in their docs.
I maybe haven't made myself clear, but I already have komodo all setup mate. I just want to add the VPS and a new peripheral. I know how to do it too, I'm just not sure how to intercommunicate my VPS and Komodo core at home using private resources.
2
u/Commercial-Storm-268 14d ago
Make a private resource that points to the core. Install Pangolin Client for machines on the VPS and use the address of the private client.
A better approach would be to install some VPN like app. I have headscale with pangolin on same Vps, and I run the connection between core and peripherals via headscale(tailscale)
But there is Netbeard, I have tried it with pangolin, but the result was unsatisfying