Octelium Codespace Playground

What is this?

This is a playground for you to install, run and manage an Octelium Cluster inside a GitHub Codespace. While we recommend you to install a demo Cluster over a cheap cloud VM/VPS instance such as DigitalOcean, Vultr, EC2, Hetzner, etc... (read more in the quick installation guide here) or from within a Linux VM/microVM inside your local machine, this method serves as an additional way for you to play with Octelium and try managing it without having to install it on real machine or a Kubernetes cluster. Note the Cluster domain in our case here is going to be simply localhost.

Steps

1. Run the current Repo in a Codespace via the green "Code" button on top of this page. You might probably also need to wait a minute or 2 after the Codespace is initialized since the microVM host CPUs are usually busy at startup. This has nothing to do with Octelium but due to Codespace's heavy CPU usage upon initialization.

2. Run the install.sh script as follows:

sudo chmod 755 ./install.sh
./install.sh

This script will take a few minutes to complete depending on the Codespace's machine type (i.e. how much RAM and vCPUs it has).

3. Open a new terminal tab in your VSCode and start running octelium or octeliumctl commands. Here are some examples:

octeliumctl get service
#Or simply
octeliumctl get svc

octeliumctl get user

octeliumctl create secret

octelium status

Managing the Cluster

We recommend you to first read the quick guide about managing the Cluster here to get an idea of how the Cluster is managed. Furthermore, this repo has some Cluster configurations inside the directory configs that includes a few resources (e.g. Services, Namespaces, Users and Groups). You can, for example, create and apply all these resources via the octeliumctl apply command as follows:

octeliumctl apply ./configs

You can also apply a certain sub-directory or even a single file as follows:

octeliumctl apply ./configs/services
# OR
octeliumctl apply ./configs/users/main.yaml

You can also read more about managing the Cluster in the following guides:

• Managing Services here
• Secret-less access here to provide seamless access to APIs, databases and SSH servers without sharing API keys or passwords.
• Access control and Policies here
• Managing Users here.
• Managing Namespaces here.
• Managing Groups here.
• Managing Secrets here.
• Managing Credentials here.
• Dynamic Service configuration and routing here.
• Client-less/BeyondCorp here and anonymous access here
• Deploying Services via managed containers here.

You might also want to have a look on some examples:

• Zero trust access to SaaS PostgreSQL-based databases (e.g. NeonDB) here
• Octelium as infrastructure for MCP here
• Octelium as ngrok alternative here
• Octelium as an API gateway here
• Octelium as an AI gateway here
• Deploying and hosting (both securely for authorized Users as well as anonymously) containerized Next.js/Vite/Astro web apps here

Accessing Services

Client-based Mode

You can actually currently connect to the Cluster via the rootless gVisor mode and map the Services you would like to use. Here is an example:

octelium connect -p nginx:8090 -p postgres-main:5432

Now you can access the protected nginx Service which is mapped to the local machine's port 8090 as follows:

curl http://localhost:8090

And you can also access to the postgres-main PostgreSQL database in a secret-less way without having to know the database's password, which is actually the main store for the Octelium Cluster itself, as follows:

psql -h localhost -U octelium

You can play with the embedded SSH mode (read more here) where you can SSH into the Codespace (let's pretend that it is some remote container, machine, IoT, etc...) from within the Codespace machine.

octelium connect --essh -p essh:2022

You can get the name of your own Session as follows:

octeliumctl get sess

And use the name to SSH into the Codespace as follows:

ssh -p 2022 root-abcdef@localhost

Client-less Mode

You can also access HTTP-based Services via the client-less (i.e. BeyondCorp) mode simply by using Octelium access tokens as a standard bearer token (read more about Credentials here). You can, for example, directly create an access token Credential as follows:

octeliumctl create cred cred01 --user root --policy allow-all --type access-token

# The output is something like
Access Token: AQpAoWCZWpulnpQMRF3Nj45...

And you can use the access token to access, for example, the protected nginx Service defined in configs/services/main.yaml via curl as follows:

curl -H "Authorization: Bearer AQpAoWCZWpulnpQMRF3Nj45..." https://nginx.localhost

# Note that the Service FQDN is "nginx.localhost" because the Cluster domain is "localhost"

For anonymous Services such as nginx-anonymous defined in configs/services/main.yaml you can publicly access it without using bearer authentication as follows:

curl https://nginx-anonymous.localhost