Octelium documentation · Latest
Quick Installation Guide
On this page +
This is a quick guide for you to install a full-fledged single-node Octelium Cluster on any cheap Linux machine, VM or cloud VPS (e.g. DigitalOcean droplet, Hetzner, AWS EC2, etc...). This single-node Cluster is good enough for development, personal, or undemanding production use cases. If you would like to look around before installing, the live demo lets you explore a running Cluster right from your browser.
You can also use Octelium Agent Skills with AI coding agents (e.g. Claude Code, Codex, etc...) to help you install and initialize your Cluster, set up DNS and TLS, and create your first Users, Services and Policies. Simply describe what you want to do, and your agent can prepare the configuration and run the relevant CLIs for you. You can find the installation instructions here or via Ask AI → AI agent skills above.
To install a production, scalable multi-node Cluster over a typical cloud-based or on-premise Kubernetes installation, we recommend referring to this guide here.
Requirements
This guide only needs 2 requirements:
Having a cheap cloud server/VM instance (e.g. DigitalOcean Droplet, Hetzner server, AWS EC2, etc...) that's running a recent Linux distribution (e.g. Ubuntu 24.04 LTS or later, Debian 12+, etc...), preferably freshly installed, with at the very least 2GB of RAM, 2vCPUs and 20 GB of disk storage as a sensible minimum requirement.
Having a domain or a subdomain of a domain name that you actually own (e.g.
example.com,octelium.example.com,sub.sub.example.com, etc...). This domain is the Cluster's domain since an Octelium Cluster is defined and addressed by its domain once installed (e.g. through theocteliumandocteliumctlcommands).
The installer script in this guide takes care of automatically installing the Octelium Cluster and all of its dependencies. In other words, you only need a fresh VM/VPS and the installer will take care of installing everything.
Installation
Once you SSH into your VPS/VM as the Linux root user, you install the Cluster by running the following commands:
The above installation command should work flawlessly with any VM with a public IP address (e.g. DigitalOcean droplets, Hetzner VMs, etc...). For more advanced installation options (e.g. the Cluster's VM is behind NAT/firewall such as EC2 machines and Google Cloud Compute instances), please refer to this section below.
The script should take a few minutes depending on your VM's capabilities to finish. Here is what the installation process looks like, replayed from a real run:
1/8 DownloadDownload the installer script and make it executable.
0:00 / 1:39Terminal output of the Octelium Cluster quick installer:
root@octelium-vm:~# curl -o install-cluster.sh https://octelium.com/install-cluster.sh
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 96549 100 96549 0 0 104k 0 --:--:-- --:--:-- --:--:-- 104k
root@octelium-vm:~# chmod +x install-cluster.sh
root@octelium-vm:~# ./install-cluster.sh --domain example.com
[octelium] Octelium installer 2.3, log: /var/log/octelium-install.log
[octelium] architecture: amd64
[octelium] primary interface eth0 (203.0.113.10)
[octelium] detected public IPv4 203.0.113.10
[octelium] WARN: example.com does not resolve yet
Octelium needs an A record for example.com and a wildcard A record for *.example.com
pointing at 203.0.113.10, otherwise certificate issuance will fail
[octelium] adding ufw rules for Kubernetes and Octelium
[octelium] WARN: the host firewall was adjusted for Octelium and K3s pod/service networking
[octelium] installing the latest Octelium CLI release
Installing the binaries from GitHub since INSTALL_DIR is set.
Downloading https://github.com/octelium/octelium/releases/download/v0.51.0/octelium-linux-amd64.tar.gz
Downloading https://github.com/octelium/octelium/releases/download/v0.51.0/octeliumctl-linux-amd64.tar.gz
Downloading https://github.com/octelium/octelium/releases/download/v0.51.0/octops-linux-amd64.tar.gz
Octelium binaries have been successfully installed
Docs: https://octelium.com/docs
Repo: https://github.com/octelium/octelium
[octelium] installing K3s
[INFO] Finding release for channel stable
[INFO] Using v1.37.2+k3s1 as release
[INFO] Downloading hash https://github.com/k3s-io/k3s/releases/download/v1.37.2%2Bk3s1/sha256sum-amd64.txt
[INFO] Downloading binary https://github.com/k3s-io/k3s/releases/download/v1.37.2%2Bk3s1/k3s
[INFO] Verifying binary download
[INFO] Installing k3s to /usr/local/bin/k3s
[INFO] Skipping installation of SELinux RPM
[INFO] Creating /usr/local/bin/kubectl symlink to k3s
[INFO] Creating /usr/local/bin/crictl symlink to k3s
[INFO] Creating /usr/local/bin/ctr symlink to k3s
[INFO] Creating killall script /usr/local/bin/k3s-killall.sh
[INFO] Creating uninstall script /usr/local/bin/k3s-uninstall.sh
[INFO] env: Creating environment file /etc/systemd/system/k3s.service.env
[INFO] systemd: Creating service file /etc/systemd/system/k3s.service
[INFO] systemd: Enabling k3s unit
Created symlink /etc/systemd/system/multi-user.target.wants/k3s.service → /etc/systemd/system/k3s.service.
[INFO] systemd: Starting k3s
[octelium] waiting for the Kubernetes API
node/octelium-vm condition met
[octelium] node octelium-vm is Ready
[octelium] labelling node octelium-vm
[octelium] CNI binary directory: /var/lib/rancher/k3s/data/cni
[octelium] pre-pulling container images in parallel
[octelium] pulled docker.io/library/postgres:17-alpine
[octelium] pulled docker.io/valkey/valkey:9.1.1-alpine
[octelium] pulled ghcr.io/k8snetworkplumbingwg/multus-cni:v4.3.0
[octelium] applying datastore credentials
[octelium] configuring PostgreSQL storage
[octelium] installing Multus
[octelium] deploying PostgreSQL and Valkey
[octelium] waiting for PostgreSQL
Waiting for 1 pods to be ready...
partitioned roll out complete: 1 new pods have been updated...
[octelium] PostgreSQL is ready
[octelium] waiting for Valkey
deployment "octelium-valkey" successfully rolled out
[octelium] Valkey is ready
[octelium] waiting for Multus
daemon set "octelium-multus" successfully rolled out
[octelium] Multus is ready
[octelium] verifying datastore authentication
[octelium] datastore authentication verified
[octelium] initializing the Octelium Cluster (this takes a few minutes)
✓ Waiting for Cluster installation to finish (52s)
The Cluster installation is now complete!
You can start interacting with the Cluster once you set the Cluster TLS certificate and the public DNS.For more information, you might want to visit the docs at https://octelium.com/docs
You can also interact with the Cluster before setting the Cluster TLS certificate by setting the "OCTELIUM_INSECURE_TLS" environment variable to "true" (i.e. via the "export OCTELIUM_INSECURE_TLS=true" command) before running "octelium" and "octeliumctl" commands
Once you set up your public DNS and Cluster TLS certificate,
use the following command to login and start interacting with the Cluster.
octelium login --domain example.com --auth-token AQpAy3u0hLbFnDf58tgFQZD-sXFc3A5Gmwytqi65SAebfIFUTM-PjTcOATs5eg_t9ipQYwCx-80OI_iIUDY0k9pDFm3K13DZnDmGTQu6qZzB3Dha-gYV6Rh3LWmiZw181e3Ikt24qEUSlj6Y1i6s89F7d_xoOW5_KMh7A1cQu3sgsInccy
[octelium] installation complete
[octelium] domain example.com
[octelium] public IPv4 203.0.113.10
[octelium] Region external IP 203.0.113.10
[octelium] database directory /mnt/octelium/db
[octelium] installer state /etc/octelium/installer
[octelium] initial auth token /etc/octelium/installer/init-token
[octelium] kubeconfig /etc/rancher/k3s/k3s.yaml (copied to /root/.kube/config)
[octelium] CNI conf directory /var/lib/rancher/k3s/agent/etc/cni/net.d
[octelium] install log /var/log/octelium-install.log
root@octelium-vm:~#Then, from your own machine, once DNS and TLS are set up:
~ ❯ octelium login --domain example.com --auth-token AQpAy3u0hLbFnDf58tgFQZD-sXFc3A5Gmwytqi65SAebfIFUTM-PjTcOATs5eg_t9ipQYwCx-80OI_iIUDY0k9pDFm3K13DZnDmGTQu6qZzB3Dha-gYV6Rh3LWmiZw181e3Ikt24qEUSlj6Y1i6s89F7d_xoOW5_KMh7A1cQu3sgsInccy
~ ❯ octelium status
cluster:
metadata: {}
domain: example.com
session:
metadata:
name: root-k2v9xd
uid: 0b7c51d2-6f4e-4a8b-9d3e-5c2a7f18e940
spec: {}
status:
type: CLIENT
user:
metadata:
name: root
uid: 4e9a0c37-2b85-4f61-a1d4-83f6c5b2e07a
spec:
type: WORKLOAD
status: {}
~ ❯To install Cordium, add the --cordium flag to the ./install-cluster.sh command. Cordium is an open source sandbox platform built on Octelium and Kubernetes that allows developers and workloads, including AI agents, to access Octelium Services from within remote, reproducible, sandboxes via browsers, CLI, API and SSH (read more).
To install the enterprise package (read more here), add the --enterprise flag to the ./install-cluster.sh command. The enterprise package is free to use, forever, for personal (e.g. homelab) and evaluation use cases. It includes enterprise-grade features such as a web-based console with an AI assistant for management and real-time visibility, just-in-tim access, as well as other features such as SCIM 2.0, SIEM integrations, TLS and DNS management, secret encryption at rest, managed upgrades, UI policy builders and testers, etc...
Upon completion of the Cluster installation, you will see the following message, which includes an octelium login command at the end of it:
You can now copy that octelium login command in order to use it later from your own machine to log in to the Cluster and begin using it.
Post-Installation
To complete the installation and start interacting with the Cluster, 2 final steps are required: Setting the public DNS for the Cluster domain and Setting the Cluster domain TLS certificate.
Public DNS
You need to set two DNS entries in your DNS provider (e.g. Cloudflare, Namecheap, GoDaddy, etc...) in order for the Cluster to be publicly addressable via its domain name:
An
Aentry to resolve<DOMAIN>to the VM/VPS's public IP address as follows:
| Entry Field | Value |
| Type | A |
| Name / Host | <DOMAIN> |
| Value | <PUBLIC_IP_ADDRESS> |
A
CNAMEentry resolving the wildcard domain*.<DOMAIN>to<DOMAIN>. This entry effectively resolves all of the<DOMAIN>sub-domains to the VM/VPS public IP address. You simply need to set yourCNAMEDNS entry as follows:
| Entry Field | Value |
| Type | CNAME |
| Name / Host | *.<DOMAIN> |
| Value | <DOMAIN> |
TLS Certificate
You need to set the Cluster domain TLS certificate in order for the Cluster, its API Server as well as its public Services to be able to communicate over HTTPS. For example, you can use Let's Encrypt via Certbot to issue a certificate for your Cluster domain (you can read more here) and then provide the issued certificate to the Cluster. This x509 certificate needs to be issued for the following domains (i.e. the domains that need to be included in the certificate's SAN list):
<DOMAIN>.*.<DOMAIN>wildcard.*.local.<DOMAIN>wildcard. This is not required but recommend if you want to have TLS-based Services (read more here).
Here is an example of certbot issuing a certificate via the DNS-01 challenge (read more in the Let's Encrypt docs):
The newly issued certificate is now stored in the /etc/letsencrypt/live/<DOMAIN> directory. Now, from your VPS/VM, you can provide the certificate to the Cluster simply via the octops cert command as follows:
Login to the Cluster
Now that we did set the Cluster public DNS and TLS certificate, we can now use the octelium login command that we copied earlier to login to the Cluster from our local machine (e.g. your own laptop) as follows:
If you try to invoke the command above before setting your actual domain's certificate, you will be met with an authentication handshake failed since the current Cluster TLS certificate is an initial self-signed certificate created by the Cluster during installation. You can skip that error, for now until you set your own real TLS certificate, by setting the OCTELIUM_INSECURE_TLS environment variable to true. Here is an example:
In addition to using OCTELIUM_INSECURE_TLS environment variable to skip verifying the server TLS certificate, you can also use the OCTELIUM_DEV environment variable which is generally used for development and debugging and it throws the debug logs of the Octelium clients as follows:
Initial Configuration
This step is not required; however, it might be useful if this is your first Octelium Cluster. In Octelium, Cluster resources are mainly managed via the octeliumctl apply command, which is very similar to how kubectl apply works (read more here). For now, we are going to use an initial configuration for your Cluster that includes only two resources:
A User for yourself that includes your primary email. We use the name
aliceand the emailalice@example.comin the example configuration below.An IdentityProvider in order for you to login to the Cluster using your User's email via the web Portal. Octelium supports three types of such IdentityProviders:
In this guide, we're going to use a Gitlab OpenID Connect IdentityProvider for the sake of simplicity. Once you create the Gitlab OIDC application and obtain your Gitlab client ID and client secret, you now store the client secret as an Octelium Secret as follows:
Now, you create a YAML file in the machine you just logged in via octelium login and add the initial configuration as follows:
And now, we apply the creation of these two resources to the Cluster via the octeliumctl apply as follows:
Tips
If this is your first Octelium Cluster, the following tips might be useful for you:
Once you login for the first time via the
octelium logincommand as shown above, you should create at least one User with enough access permissions for yourself (see the initial configuration example here). The authentication token Credential (read more about Credentials here) used in this initialoctelium logincommand is issued for therootUser, which is installed automatically by the Cluster during the installation process. It should be noted that there is nothing special about therootUser in Octelium and you can actually delete it once you add your own Users and other resources. Once you add your own Users with enough permissions to act as the Cluster administrators, IdentityProviders, and other resources, you can safely remove the initial authentication token _Credential as follows:
Octelium CLIs, namely
octeliumandocteliumctl, are designed to simultaneously work with multiple Octelium Clusters. That's why you need to add the--domain <DOMAIN>flag to each command. Obviously, this becomes tiresome and annoying if you're doing too many commands in the same shell for a single Cluster. That's why it's recommended to set the environment variableOCTELIUM_DOMAINto your domain to use all your commands without having to use the--domainflag for each command. Here is an example:
After you login for the first time via the
octelium logincommand, you might want to connect to the Cluster and access its available Services (read more about connecting via theocteliumCLI here). For example, the Cluster creates ademo-nginxService during the installation. You can access it as follows:
TLS certificates usually expire within a few months. For example, certificates issued by Let's Encrypt expire after 90 days by default. It would be better for you to automate the process of rotating TLS certificates and providing them to your Octelium Cluster either via
octops certor by re-creating the TLS secret withkubectlusing some simple bash scripts, or, even better, by using a FOSS solution like cert-manager (read more here).Since Octelium is a zero trust architecture, all access to protected resources, represented by Services, must be explicitly allowed by Policies (read more about Policies and access control here). As shown in the initial configuration example here, the User
alicehas theallow-allPolicy attached, which grants her access to all Services, unless there are further Policies that override it by explicitly denying her access. Octelium installs theallow-allanddeny-allPolicies during the installation process to make it easier for you to directly use them and attach them to your different resources. Attaching Policies is not restricted to just Users as in the example above, you can actually attach Policies to Users (read more here), Services (read more here), Groups (read more here), Namespaces (read more here). You can also attach Policies to your issued Credentials (read more here).The installer in this guide automatically installs k3s as the underlying Kubernetes cluster, and then installs the Octelium Cluster on top of it. You can access that Kubernetes cluster, typically via
kubectl, by setting the kubeconfig file to/etc/rancher/k3s/k3s.yaml. Here is an example:
What Now?
Your Cluster is up and running. Where you go next depends on what you want to do.
Manage your Cluster. Start with First Steps, then explore Services, Users, Policies, IdentityProviders, Credentials and Authenticators (e.g. FIDO passkeys and TOTP MFA).
Connect and access Services from your own machine via the octelium client.
Explore guides by use case:
Web apps & sites: secure Next.js / Vite apps, host a site from behind NAT, or use Octelium as an ngrok alternative.
Databases: passwordless access to NeonDB.
Cloud, secretless: reach AWS S3 and Lambda without distributing keys.
Homelab: deploy Pi-hole or VS Code, or self-host an IdentityProvider with Keycloak, Authentik or Dex.
Advanced Installation Options
The above ./install-cluster.sh --domain <DOMAIN> should automatically work with any VM/VPS with a public IP address (e.g. DigitalOcean, Hetzner, Vultr, etc...). Therefore, you generally do not need to read this section unless you want to install the Cluster in a special environment (e.g. VM is behind NAT and/or firewall, you want to use QUIC tunneling, the Cluster is meant for internal testing/playground use cases, etc...).
If your VM/VPS is behind NAT where the IP address of the default/main network device of the machine is a private/internal IP address instead of its public IP address (e.g. EC2 and GCP instances under default configurations), then you will need to use the
--natflag as follows:
The --nat flag instructs the Cluster's Ingress to use and listen on the main internal/private VM address instead of using the machine's public address.
If you want to install the Cluster in an internal network behind NAT and access it internally from within that private network (this is only recommended for internal testing use cases), you can add the --force-machine-ip flag in addition to the --nat flag. The --force-machine-ip instructs the WireGuard listener in the Cluster's GatewayAgent to use and listen on the main internal/private IP address instead of the machine's public address.
If the VM/VPS is behind a firewall (e.g. EC2, Google GCP VMs, etc...), you will need to open the TCP port 443 for Octelium ingress and the UDP port 53820 for WireGuard.
By default, the installation script attempts to automatically obtain the public IP address of the VM/VPS, you can explicitly set the public IP address via the
--public-ipflag. Here is an example:
By default the Octelium Cluster uses only WireGuard for tunneling. You can additionally enable the QUIC-based tunneling mode (read more here) via the
--quicv0flag as follows:
If your VPS is behind a firewall, you will also have to open the UDP port 8443 for the QUIC listener. You also need to create an additional public DNS entry as shown in detail here.
By default the
latestCluster version is installed. You can install a specific Cluster version via the--versionflag as follows:
To select package versions independently, use
--cordium-versionwith--cordiumand--enterprise-versionwith--enterprise:
When a package version is omitted, it follows --version (or latest when --version is omitted). These version options do not enable package installation by themselves or upgrade packages already installed by the script.
To install Longhorn and use it as the default Kubernetes storage class, add
--longhorn(alias:--install-longhorn):
The installer installs Longhorn after K3s is ready and waits for its storage components before installing the datastores and initializing Octelium. It uses one volume replica for this single-node Cluster and installs the required iSCSI and NFS client dependencies unless --no-install-deps is set. The host filesystem used for Longhorn data must be ext4 or XFS; see the Longhorn installation requirements.
The Longhorn option also installs the three Kubernetes CSI snapshot CRDs and the shared snapshot controller from external-snapshotter v8.5.0, matching Longhorn's CSI snapshotter. The CRDs are installed before Longhorn starts. An existing shared controller and existing CRDs are reused. The installer waits for both the shared controller and Longhorn's CSI snapshotter, then creates longhorn-snapshot-vsc as the default snapshot class for driver.longhorn.io. This class uses local Longhorn snapshots (type: snap) with a Delete deletion policy, so it does not require an external backup target. Cordium can use it for Workspace snapshots and Template pre-builds; an explicit snapshot-class rule can select another class.
Longhorn becomes the default for new persistent volume claims that do not specify a storage class, such as Cordium workspace volumes. PostgreSQL continues to use its dedicated local volume at --db-dir; existing volumes are not migrated. Omitting --longhorn preserves the current storage setup.
Troubleshooting
Here are some of the common problems you might experience when trying to access the Cluster for the first time, typically via the initial octelium login command, from your own local machine to the Cluster:
Produced Zero Addresses
If your octelium login command produces the following error:
That means you did not set your CNAME DNS entry as shown above. You can even verify that by using ping as follows:
If it does not resolve, it means that your CNAME entry is simply not set.
Also make sure that you did set your A DNS entry. You can verify by using ping as follows:
And if this ping also does not resolve, it means that your A entry is simply not set too.
You might also need to flush your local machine DNS cache to make sure that your local machine is not resolving to any old, now invalid, DNS entries as follows:
In Linux:
In Windows as an Admin:
In macOS:
Certificate Signed by Unknown Authority
If your octelium login command produces the following error:
Then you still have not set your TLS certificate via octops cert or kubectl create secret tls as shown above. You can proceed with the command just by setting the OCTELIUM_INSECURE_TLS or OCTELIUM_DEV environment variables to true as follows:
However, it's recommended to set your own TLS certificate that's signed by a real CA such as Let's Encrypt as soon as possible.
Connection Refused
If your octelium login shows something as follows:
From your Cluster VM itself, verify that the Octelium ingress is actually running and bound to an external IP address as follows:
The EXTERNAL-IP field of the output that command should be set to your actual main IP address and does not have a <pending> or an empty value. If your Cluster VM is behind NAT, you might need to uninstall the Cluster via ./install-cluster.sh --uninstall and re-install by adding the --nat flag as shown above.
You can also try to curl curl -k https://<DOMAIN> to verify that the Octelium ingress is running. The -k flag is used here in order to ignore the TLS certificate errors since the initial TLS certificate is a self-signed certificate that should be replaced with octops cert or kubectl create secret tls as shown above. That curl command should output an HTML of the login web page.
Unable to Access Services
This section assumes that you can successfully access the Cluster via the octelium and octeliumctl commands (e.g. octeliumctl get service, octelium status, etc...) and you are also able to access the Cluster's web login page located at the URL https://<DOMAIN> via your browser.
If you can successfully connect to the Cluster via octelium connect but cannot access any Service at all when connected even though you can access public Services through your web browser, then this might be a NAT-related issue in your Cluster VM/machine. This problem shows up, once connected via sudo -E octelium connect, when you try to access the demo-nginx Service that is created by default during the Cluster installation via curl demo-nginx but you end up getting a timeout error such as Could not resolve host: demo-nginx. You can verify this is a NAT-related issue in your VM as follows:
First verify that you can actually successfully access that
demo-nginxService via your web browser. You can go to portal athttps://portal.<DOMAIN>and visit that Service from the list of Service shown. If you can not accesshttps://portal.<DOMAIN>orhttps://demo-nginx.<DOMAIN>then this is not a NAT-related issue.Now open a terminal and connect to the Cluster as a non-root unprivileged OS user as follows:
You should be getting the same timeout error in this unprivileged mode (read more here). If you can successfully curl the Service now in the unprivileged mode then this is not a NAT-related issue, but most probably a DNS-related issue on your own client-side machine.
Now, from your Cluster VM/machine, obtain your main IP address as follows:
This should be a public IP address (read more in Wikipedia here) if you installed the Cluster via ./install-cluster.sh --domain <DOMAIN> as shown in the beginning of this guide. If you obtained a private IP address as an output to the command above, then the solution to this problem is to add the --nat flag (read more the advanced installation options section here) as follows:
If you want to install the Cluster on some internal virtual machine inside an internal/private network (e.g. microVM inside your host) for internal testing purposes, then add also the --force-machine-ip as follows:
Upgrade the Cluster
You can later upgrade your Octelium Cluster via the octops upgrade command (read more here) from within your VPS/VM as follows:
Uninstall the Cluster
If you ever want to uninstall the Cluster later for whatever reason, including to re-install the Cluster, you can simply do that using the same installation script via the --uninstall flag as follows:
This command removes the Octelium Cluster and its underlying k3s Kubernetes cluster.