File: README.md

Thanks to the sponsors:

☁️ Cosmos is the most secure and easy way to self-host a Home Server. It acts as a secure gateway to your application, as well as a server manager. It aims to solve the increasingly worrying problem of vulnerable self-hosted applications and personal servers.

Whether you have a server, a NAS, or a Raspberry Pi with applications such as Plex, HomeAssistant or even a blog, Cosmos is the perfect solution to run and secure them all. Simply install Cosmos on your server and connect to your applications through it to enjoy built-in security and robustness for all your services, right out of the box.

Cosmos is:

App Store 📦📱 To easily install and manage your applications, with simple installers, automatic updates and security checks. This works alongside manual installation methods, such as importing docker-compose files, or the docker CLI
Storage Manager 📂🔐 To easily manage your disks, including Parity Disks and MergerFS
Network Storages 📡📂 Based on RClone, To easily manage your network storages, including accessing remote ones (ex. Dropbox) or share NFS / FTP / ... from the UI, protected by the smart shield
Reverse-Proxy 🔄🔗 Targeting containers, other servers, or serving static folders / SPA with automatic HTTPS, and a nice UI
Authentication Server 🔐👤 With strong security, multi-factor authentication and multiple strategies (OpenId, forward headers, HTML)
Customizable Homepage 🏠🖼 To access all your applications from a single place, with a beautiful and customizable UI
Container manager 🐋🔧 To easily manage your containers and their settings, keep them up to date as well as audit their security. Includes docker-compose support!
VPN 🌐🔒 To securely access your applications from anywhere, without having to open ports on your router.
Backups 📦🔒 To easily backup your applications, with incremental backups, encryption, and remote backups. Using Restic under the hood
Monitoring 📈📊 Fully persisting and real-time monitoring with customizable alerts and notifications, so you can be notified of any issue.
Identity Provider 👦👩 To easily manage your users, invite your friends and family to your applications without awkardly sharing credentials. Let them request a password change with an email rather than having you unlock their account manually!
SmartShield technology 🧠🛡 Automatically secure your applications without manual adjustments (see below for more details). Includes anti-bot and anti-DDOS strategies. Now includes TCP protection (FTP, SSH, Games, ...)
CRON 🕒🔧 To easily schedule tasks on the server or inside containers

It has been built to be:

Easy to use 🚀👍 to install and use, with a simple web UI to manage your applications from any device
Powerful 🧠🔥 Being easy does not mean being dumb: while Cosmos is easy to use, it is also powerful and flexible, you can even use it from the terminal if you want to!
User-friendly 🧑‍🎨 For both new and experienced users: easily integrates into your existing home server, the already existing applications you have, and the new ones you want to install
Secure 🔒🔑 Connect to all your applications with the same account, including strong security, multi-factor authentication and OpenId. Cosmos encrypt your data and protect your privacy. Security by design, and not as an afterthought
Anti-Bot 🤖❌ Collection of tools to prevent bots from accessing your applications, such as common bot detection, IP based detection, and more
Anti-DDOS 🔥⛔️ Additional protections such as variable timeouts/throttling, IP rate limiting and geo-blacklisting
Modular 🧩📦 to easily add new features and integrations, but also run only the features you need (for example No docker, no Databases, or no HTTPS)

And a lot more planned features are coming!

What are the differences with other alternatives?

Cosmos has a few key differences with other alternatives such as YunoHost, Unraid, etc...

Feature	Cosmos	Unraid	Yunohost	CasaOS	Cloudron
Reverse Proxy	✅	❌	✅	❌	~ *
Container Management	✅	~ *	❌	~ *	❌
Automatic HTTPS	✅	❌	❌	❌	✅
Multi-users	✅	✅	✅	❌	✅
2FA	✅	❌	❌	❌	✅
OpenID/SSO	✅	❌	❌	❌	~ *
App Store	✅	✅	✅	✅	✅
Docker Compose support	✅	✅	❌	✅	✅
File manager	❌	✅	❌	✅	❌
Anti-bot / anti-DDOS	✅	❌	❌	❌	❌
VPN	✅	~ **	❌	❌	❌
Monitoring (w/ historical data & alerts)	✅	❌	❌	❌	❌
Hard VM Management	❌	✅	❌	❌	❌

text

* denotes support limited to apps installed with the software itself** Wireguard only. Does not support meshing or bypassing CGNAT

Security: Cosmos has a unique strong focus on securing your application with exclusive features such as the smart-shield. It has 2FA, OpenID, anti-DDOS, and other security features built-in. It also has a strong focus on privacy, with the latest encryption methods and a strong focus on data protection. Unlike any other solutions, it assumes the software you run are not trustworthy, and protects you from them.
Power-user friendly: Some of those alternatives can feel a bit "limiting" to someone who knows what they are doing. On the other hand, while Cosmos is designed to be easy to use, it is also powerful and flexible. It is designed to be used by both new and experienced users, and to integrate into your existing home server, the already existing applications you have, and the new ones you want to install. It can even be used from the terminal if you want to!
Flexible: Unlike the alternatives, Cosmos is not exclusively focused around its app-store. Instead, it lets you freely install any application any way you want, and manage them from the UI, from Portainer, or from docker directly. Any of those applications will still be integrated into Cosmos and will also benefit from all the security features, Let's Encrypt, etc..
Learning experience: If you are new to self-hosting, using a software that hides all the complexity from you can prevent you from learning how to properly manage your server. Cosmos is designed to be easy to use, but also to be a learning experience. It does not hide things away but instead guides you and incentivizes learning more about the tools you are using.
No vendor-locking: Unlike solution that tightly couple their applications to the containers, Cosmos can manage apps created from anywhere all the same, and converting an existing container to a Cosmos app is as simple as adding a URL in the UI. You can also migrate out of Cosmos at any time, as it only uses vanilla docker containers.

You might also wonder about cloudflare proxy and cloudflare tunnel when it comes to security. But unlike popular beliefs those are not solutions on their own as:

While they protect your remote access to your applications, they leave your origin server completely unprotected. A rogue device / application in your local network would have no troubles taking advantage of it
Those options let Cloudflare see your entire network unencrypted. Yes, even if you use HTTPS: Cloudflare proxy de-encrypt your traffic, to re-encrypt it. Meaning that everything that goes through your traffic is plain readable text to Cloudflare. On the other hand, Cosmos is self-hosted so you stay in control of your data.

SDK and Terraform

A JavaScript/TypeScript SDK is available for programmatic access to the Cosmos API. See the JS SDK documentation for installation, usage, and examples.

The GO SDK can be found in the go-sdk folder and used with Go SDK documentation

Finally a Terraform provider is available to fully automate your setup: Terraform documentation

What is the SmartShield?

SmartShield is a modern API protection package designed to secure your API by implementing advanced rate-limiting and user restrictions. This helps efficiently allocate and protect your resources without manual adjustment of limits and policies.

Key Features:

Dynamic Rate Limiting ✨ SmartShield calculates rate limits based on user behavior, providing a flexible approach to maintain API health without negatively impacting user experience.
Adaptive Actions 📈 SmartShield automatically throttles users who exceed their rate limits, preventing them from consuming more resources than they are allowed without abruptly terminating their requests.
User Bans & Strikes 🚫 Implement temporary or permanent bans and issue strikes automatically to prevent API abuse from malicious or resource-intensive users.
Global Request Control 🌐 Monitor and limit with queues the total number of simultaneous requests on your server, ensuring optimal performance and stability.
User-based Metrics 📊 SmartShield tracks user consumption in terms of requests, data usage, and simultaneous connections, allowing for detailed control.
Privileged Access 🔑 Assign privileged access to specific user groups, granting them exemption from certain restrictions and ensuring uninterrupted service even durin attacks.
Customizable Policies ⚙️ Modify SmartShield's default policies to suit your specific needs, such as request limits, time budgets, and more.

Why use Cosmos?

If you have your own self-hosted data, such as a Plex server, or may be your own photo server, you expose your data to being hacked, or your server to being highjacked (even on your local network!).

It is becoming an important threat to you. Managing servers, applications and data is very complex, and the problem is that you cannot do it on your own: how do you know that the server application where you store your family photos has a secure code? it was never audited.

Even a major application such as Plex has been hacked in the past, and the data of its users has been exposed. In fact, the recent LastPass leak happened because a LastPass employee had a Plex server that wasn't updated to the last version and was missing an important security patch!

That is the issue Cosmos Server is trying to solve: by providing a secure and robust way to run your self-hosted applications, you can be sure that your data is safe and that you can access it without having to worry about your security.

Here's a simple example of how Cosmos can help you:

Another example:

Additionally, because every new self-hosted applications re-implement crucial systems such as authentication from scratch everytime, the large majority of them are very susceptible to being hacked without too much trouble. This is very bad because not only Docker containers are not isolated, but they also run as root by default, which means it can easily be used to offer access to your entire server or even infrastructure.

Most tools currently used to self-host not specifically designed to be secure for your scenario. Entreprise tools such as Traefik, NGinx, etc... Are designed for different use-cases that assume that the code you are running behind them is trustworthy. But who knows what server apps you might be running? On top of that, a lot of reverse-proxies and security tools lock important security features behind 3 to 4 figures business subscriptions that are not realistic for self-hosting.

If you have any further questions, feel free to join our Discord!

Let's Encrypt

Cosmos Server can automatically generate and renews HTTPS certificates for your applications using Let's Encrypt. It is compatible with wildcard certificates, using the DNS challenge. In order to do it, you need to add DNSChallengeProvider to the HTTPConfig in your config (or in the UI). And then add the proper API token via environment variables. To know what providers are supported and what environment variable they need, please refer to this page.

As A Developer

If you're a self-hosted application developer, integrate your application with Cosmos and enjoy secure authentication, robust HTTP layer protection, HTTPS support, user management, encryption, logging, backup, and more - all with minimal effort. And if your users prefer not to install Cosmos, your application will still work seamlessly.

Authentication is very hard (how do you check the password match? What encryption do you use? How do you store tokens? How do you check if the user is allowed to access the application?). Cosmos Server provides a secure authentication system that can be used by any application, and that is easy to integrate.

Licence

Cosmos is using the Apache 2.0 Licence with the Commons Clause 1.0. This is a common clause among open source infrastructure software, such as databases, reverse proxies, etc...

TL;DR: You can use it freely. You can also fork it and redistribute it, But you are not allowed to sell it, a derivative or to sell a service based on it (ex. SaaS or PaaS).

Note that you are allowed to use it to host a monetized business website, a blog etc... as long as your business does not involve selling Cosmos or its features.

Installation

Installation is simple using Docker:

text

sudo docker run -d --network host  --privileged --name cosmos-server -h cosmos-server --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket -v /:/mnt/host -v /var/lib/cosmos:/config azukaar/cosmos-server:latest

DO NOT USE UNRAID TEMPLATES, CASAOS OR PORTAINER STACKS TO INSTALL COSMOS. IT WILL NOT WORK PROPERLY. JUST RUN THE DOCKER RUN COMMAND!. You can use Docker-Compose but if you are on mac or windows (so no host mode) without a domain, that will prevent Cosmos from binding ports to itself! (preventing ip:port from working properly)

IF YOU ARE USING WINDOWS OR MAC OS YOU CANNOT USE THE HOST MODE OF DOCKER. Please replace --network host with -p 80:80 -p 443:443 -p 4242:4242/udp

In this command, -v /:/mnt/host is optional and allow to manage folders from Cosmos, you can remove it if you don't want it but you will have to create your container's bind folders manually.

--privileged is also optional, but it is required if you use hardening software like AppArmor or SELinux, as they restrict access to the docker socket. It is also required for Constellation to work. If you don't want to use it, you can add the following capabilities: NET_ADMIN for Constellation.

Once installed, simply go to http://your-server-ip and follow the instructions of the setup wizard. always start the install with the browser in incognito mode to avoid issues with your browser cache.

Port 4242 is a UDP port used for the Constellation VPN.

Make sure you expose the right ports (by default 80 / 443). It is best to keep those ports intacts, as Cosmos is meant to run as your reverse proxy. Trying to setup Cosmos behind another reverse proxy is possible but will only create headaches.

You also need to keep the docker socket mounted, as Cosmos needs to be able to manage your containers.

You can tweak the config file accordingly. Some settings can be changed before end with env var. see here.

If you are having issues with the installation, please contact us on Discord!

Contribute

Contribute.md

File: Readme.md

Thanks to the sponsors:

Cosmos is:

App Store 📦📱 To easily install and manage your applications, with simple installers, automatic updates and security checks. This works alongside manual installation methods, such as importing docker-compose files, or the docker CLI
Storage Manager 📂🔐 To easily manage your disks, including Parity Disks and MergerFS
Network Storages 📡📂 Based on RClone, To easily manage your network storages, including accessing remote ones (ex. Dropbox) or share NFS / FTP / ... from the UI, protected by the smart shield
Reverse-Proxy 🔄🔗 Targeting containers, other servers, or serving static folders / SPA with automatic HTTPS, and a nice UI
Authentication Server 🔐👤 With strong security, multi-factor authentication and multiple strategies (OpenId, forward headers, HTML)
Customizable Homepage 🏠🖼 To access all your applications from a single place, with a beautiful and customizable UI
Container manager 🐋🔧 To easily manage your containers and their settings, keep them up to date as well as audit their security. Includes docker-compose support!
VPN 🌐🔒 To securely access your applications from anywhere, without having to open ports on your router.
Backups 📦🔒 To easily backup your applications, with incremental backups, encryption, and remote backups. Using Restic under the hood
Monitoring 📈📊 Fully persisting and real-time monitoring with customizable alerts and notifications, so you can be notified of any issue.
Identity Provider 👦👩 To easily manage your users, invite your friends and family to your applications without awkardly sharing credentials. Let them request a password change with an email rather than having you unlock their account manually!
SmartShield technology 🧠🛡 Automatically secure your applications without manual adjustments (see below for more details). Includes anti-bot and anti-DDOS strategies. Now includes TCP protection (FTP, SSH, Games, ...)
CRON 🕒🔧 To easily schedule tasks on the server or inside containers

It has been built to be:

Easy to use 🚀👍 to install and use, with a simple web UI to manage your applications from any device
Powerful 🧠🔥 Being easy does not mean being dumb: while Cosmos is easy to use, it is also powerful and flexible, you can even use it from the terminal if you want to!
User-friendly 🧑‍🎨 For both new and experienced users: easily integrates into your existing home server, the already existing applications you have, and the new ones you want to install
Secure 🔒🔑 Connect to all your applications with the same account, including strong security, multi-factor authentication and OpenId. Cosmos encrypt your data and protect your privacy. Security by design, and not as an afterthought
Anti-Bot 🤖❌ Collection of tools to prevent bots from accessing your applications, such as common bot detection, IP based detection, and more
Anti-DDOS 🔥⛔️ Additional protections such as variable timeouts/throttling, IP rate limiting and geo-blacklisting
Modular 🧩📦 to easily add new features and integrations, but also run only the features you need (for example No docker, no Databases, or no HTTPS)

And a lot more planned features are coming!

What are the differences with other alternatives?

Cosmos has a few key differences with other alternatives such as YunoHost, Unraid, etc...

Feature	Cosmos	Unraid	Yunohost	CasaOS	Cloudron
Reverse Proxy	✅	❌	✅	❌	~ *
Container Management	✅	~ *	❌	~ *	❌
Automatic HTTPS	✅	❌	❌	❌	✅
Multi-users	✅	✅	✅	❌	✅
2FA	✅	❌	❌	❌	✅
OpenID/SSO	✅	❌	❌	❌	~ *
App Store	✅	✅	✅	✅	✅
Docker Compose support	✅	✅	❌	✅	✅
File manager	❌	✅	❌	✅	❌
Anti-bot / anti-DDOS	✅	❌	❌	❌	❌
VPN	✅	~ **	❌	❌	❌
Monitoring (w/ historical data & alerts)	✅	❌	❌	❌	❌
Hard VM Management	❌	✅	❌	❌	❌

text

* denotes support limited to apps installed with the software itself** Wireguard only. Does not support meshing or bypassing CGNAT

Security: Cosmos has a unique strong focus on securing your application with exclusive features such as the smart-shield. It has 2FA, OpenID, anti-DDOS, and other security features built-in. It also has a strong focus on privacy, with the latest encryption methods and a strong focus on data protection. Unlike any other solutions, it assumes the software you run are not trustworthy, and protects you from them.
Power-user friendly: Some of those alternatives can feel a bit "limiting" to someone who knows what they are doing. On the other hand, while Cosmos is designed to be easy to use, it is also powerful and flexible. It is designed to be used by both new and experienced users, and to integrate into your existing home server, the already existing applications you have, and the new ones you want to install. It can even be used from the terminal if you want to!
Flexible: Unlike the alternatives, Cosmos is not exclusively focused around its app-store. Instead, it lets you freely install any application any way you want, and manage them from the UI, from Portainer, or from docker directly. Any of those applications will still be integrated into Cosmos and will also benefit from all the security features, Let's Encrypt, etc..
Learning experience: If you are new to self-hosting, using a software that hides all the complexity from you can prevent you from learning how to properly manage your server. Cosmos is designed to be easy to use, but also to be a learning experience. It does not hide things away but instead guides you and incentivizes learning more about the tools you are using.
No vendor-locking: Unlike solution that tightly couple their applications to the containers, Cosmos can manage apps created from anywhere all the same, and converting an existing container to a Cosmos app is as simple as adding a URL in the UI. You can also migrate out of Cosmos at any time, as it only uses vanilla docker containers.

You might also wonder about cloudflare proxy and cloudflare tunnel when it comes to security. But unlike popular beliefs those are not solutions on their own as:

While they protect your remote access to your applications, they leave your origin server completely unprotected. A rogue device / application in your local network would have no troubles taking advantage of it
Those options let Cloudflare see your entire network unencrypted. Yes, even if you use HTTPS: Cloudflare proxy de-encrypt your traffic, to re-encrypt it. Meaning that everything that goes through your traffic is plain readable text to Cloudflare. On the other hand, Cosmos is self-hosted so you stay in control of your data.

SDK and Terraform

A JavaScript/TypeScript SDK is available for programmatic access to the Cosmos API. See the JS SDK documentation for installation, usage, and examples.

The GO SDK can be found in the go-sdk folder and used with Go SDK documentation

Finally a Terraform provider is available to fully automate your setup: Terraform documentation

What is the SmartShield?

Key Features:

Dynamic Rate Limiting ✨ SmartShield calculates rate limits based on user behavior, providing a flexible approach to maintain API health without negatively impacting user experience.
Adaptive Actions 📈 SmartShield automatically throttles users who exceed their rate limits, preventing them from consuming more resources than they are allowed without abruptly terminating their requests.
User Bans & Strikes 🚫 Implement temporary or permanent bans and issue strikes automatically to prevent API abuse from malicious or resource-intensive users.
Global Request Control 🌐 Monitor and limit with queues the total number of simultaneous requests on your server, ensuring optimal performance and stability.
User-based Metrics 📊 SmartShield tracks user consumption in terms of requests, data usage, and simultaneous connections, allowing for detailed control.
Privileged Access 🔑 Assign privileged access to specific user groups, granting them exemption from certain restrictions and ensuring uninterrupted service even durin attacks.
Customizable Policies ⚙️ Modify SmartShield's default policies to suit your specific needs, such as request limits, time budgets, and more.

Why use Cosmos?

Here's a simple example of how Cosmos can help you:

Another example:

If you have any further questions, feel free to join our Discord!

Let's Encrypt

As A Developer

Licence

Cosmos is using the Apache 2.0 Licence with the Commons Clause 1.0. This is a common clause among open source infrastructure software, such as databases, reverse proxies, etc...

TL;DR: You can use it freely. You can also fork it and redistribute it, But you are not allowed to sell it, a derivative or to sell a service based on it (ex. SaaS or PaaS).

Note that you are allowed to use it to host a monetized business website, a blog etc... as long as your business does not involve selling Cosmos or its features.

Installation

Installation is simple using Docker:

text

sudo docker run -d --network host  --privileged --name cosmos-server -h cosmos-server --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket -v /:/mnt/host -v /var/lib/cosmos:/config azukaar/cosmos-server:latest

IF YOU ARE USING WINDOWS OR MAC OS YOU CANNOT USE THE HOST MODE OF DOCKER. Please replace --network host with -p 80:80 -p 443:443 -p 4242:4242/udp

In this command, -v /:/mnt/host is optional and allow to manage folders from Cosmos, you can remove it if you don't want it but you will have to create your container's bind folders manually.

Port 4242 is a UDP port used for the Constellation VPN.

You also need to keep the docker socket mounted, as Cosmos needs to be able to manage your containers.

You can tweak the config file accordingly. Some settings can be changed before end with env var. see here.

If you are having issues with the installation, please contact us on Discord!

Contribute

Contribute.md

File: readme.md

Thanks to the sponsors:

Cosmos is:

App Store 📦📱 To easily install and manage your applications, with simple installers, automatic updates and security checks. This works alongside manual installation methods, such as importing docker-compose files, or the docker CLI
Storage Manager 📂🔐 To easily manage your disks, including Parity Disks and MergerFS
Network Storages 📡📂 Based on RClone, To easily manage your network storages, including accessing remote ones (ex. Dropbox) or share NFS / FTP / ... from the UI, protected by the smart shield
Reverse-Proxy 🔄🔗 Targeting containers, other servers, or serving static folders / SPA with automatic HTTPS, and a nice UI
Authentication Server 🔐👤 With strong security, multi-factor authentication and multiple strategies (OpenId, forward headers, HTML)
Customizable Homepage 🏠🖼 To access all your applications from a single place, with a beautiful and customizable UI
Container manager 🐋🔧 To easily manage your containers and their settings, keep them up to date as well as audit their security. Includes docker-compose support!
VPN 🌐🔒 To securely access your applications from anywhere, without having to open ports on your router.
Backups 📦🔒 To easily backup your applications, with incremental backups, encryption, and remote backups. Using Restic under the hood
Monitoring 📈📊 Fully persisting and real-time monitoring with customizable alerts and notifications, so you can be notified of any issue.
Identity Provider 👦👩 To easily manage your users, invite your friends and family to your applications without awkardly sharing credentials. Let them request a password change with an email rather than having you unlock their account manually!
SmartShield technology 🧠🛡 Automatically secure your applications without manual adjustments (see below for more details). Includes anti-bot and anti-DDOS strategies. Now includes TCP protection (FTP, SSH, Games, ...)
CRON 🕒🔧 To easily schedule tasks on the server or inside containers

It has been built to be:

Easy to use 🚀👍 to install and use, with a simple web UI to manage your applications from any device
Powerful 🧠🔥 Being easy does not mean being dumb: while Cosmos is easy to use, it is also powerful and flexible, you can even use it from the terminal if you want to!
User-friendly 🧑‍🎨 For both new and experienced users: easily integrates into your existing home server, the already existing applications you have, and the new ones you want to install
Secure 🔒🔑 Connect to all your applications with the same account, including strong security, multi-factor authentication and OpenId. Cosmos encrypt your data and protect your privacy. Security by design, and not as an afterthought
Anti-Bot 🤖❌ Collection of tools to prevent bots from accessing your applications, such as common bot detection, IP based detection, and more
Anti-DDOS 🔥⛔️ Additional protections such as variable timeouts/throttling, IP rate limiting and geo-blacklisting
Modular 🧩📦 to easily add new features and integrations, but also run only the features you need (for example No docker, no Databases, or no HTTPS)

And a lot more planned features are coming!

What are the differences with other alternatives?

Cosmos has a few key differences with other alternatives such as YunoHost, Unraid, etc...

Feature	Cosmos	Unraid	Yunohost	CasaOS	Cloudron
Reverse Proxy	✅	❌	✅	❌	~ *
Container Management	✅	~ *	❌	~ *	❌
Automatic HTTPS	✅	❌	❌	❌	✅
Multi-users	✅	✅	✅	❌	✅
2FA	✅	❌	❌	❌	✅
OpenID/SSO	✅	❌	❌	❌	~ *
App Store	✅	✅	✅	✅	✅
Docker Compose support	✅	✅	❌	✅	✅
File manager	❌	✅	❌	✅	❌
Anti-bot / anti-DDOS	✅	❌	❌	❌	❌
VPN	✅	~ **	❌	❌	❌
Monitoring (w/ historical data & alerts)	✅	❌	❌	❌	❌
Hard VM Management	❌	✅	❌	❌	❌

text

* denotes support limited to apps installed with the software itself** Wireguard only. Does not support meshing or bypassing CGNAT

Security: Cosmos has a unique strong focus on securing your application with exclusive features such as the smart-shield. It has 2FA, OpenID, anti-DDOS, and other security features built-in. It also has a strong focus on privacy, with the latest encryption methods and a strong focus on data protection. Unlike any other solutions, it assumes the software you run are not trustworthy, and protects you from them.
Power-user friendly: Some of those alternatives can feel a bit "limiting" to someone who knows what they are doing. On the other hand, while Cosmos is designed to be easy to use, it is also powerful and flexible. It is designed to be used by both new and experienced users, and to integrate into your existing home server, the already existing applications you have, and the new ones you want to install. It can even be used from the terminal if you want to!
Flexible: Unlike the alternatives, Cosmos is not exclusively focused around its app-store. Instead, it lets you freely install any application any way you want, and manage them from the UI, from Portainer, or from docker directly. Any of those applications will still be integrated into Cosmos and will also benefit from all the security features, Let's Encrypt, etc..
Learning experience: If you are new to self-hosting, using a software that hides all the complexity from you can prevent you from learning how to properly manage your server. Cosmos is designed to be easy to use, but also to be a learning experience. It does not hide things away but instead guides you and incentivizes learning more about the tools you are using.
No vendor-locking: Unlike solution that tightly couple their applications to the containers, Cosmos can manage apps created from anywhere all the same, and converting an existing container to a Cosmos app is as simple as adding a URL in the UI. You can also migrate out of Cosmos at any time, as it only uses vanilla docker containers.

You might also wonder about cloudflare proxy and cloudflare tunnel when it comes to security. But unlike popular beliefs those are not solutions on their own as:

While they protect your remote access to your applications, they leave your origin server completely unprotected. A rogue device / application in your local network would have no troubles taking advantage of it
Those options let Cloudflare see your entire network unencrypted. Yes, even if you use HTTPS: Cloudflare proxy de-encrypt your traffic, to re-encrypt it. Meaning that everything that goes through your traffic is plain readable text to Cloudflare. On the other hand, Cosmos is self-hosted so you stay in control of your data.

SDK and Terraform

A JavaScript/TypeScript SDK is available for programmatic access to the Cosmos API. See the JS SDK documentation for installation, usage, and examples.

The GO SDK can be found in the go-sdk folder and used with Go SDK documentation

Finally a Terraform provider is available to fully automate your setup: Terraform documentation

What is the SmartShield?

Key Features:

Dynamic Rate Limiting ✨ SmartShield calculates rate limits based on user behavior, providing a flexible approach to maintain API health without negatively impacting user experience.
Adaptive Actions 📈 SmartShield automatically throttles users who exceed their rate limits, preventing them from consuming more resources than they are allowed without abruptly terminating their requests.
User Bans & Strikes 🚫 Implement temporary or permanent bans and issue strikes automatically to prevent API abuse from malicious or resource-intensive users.
Global Request Control 🌐 Monitor and limit with queues the total number of simultaneous requests on your server, ensuring optimal performance and stability.
User-based Metrics 📊 SmartShield tracks user consumption in terms of requests, data usage, and simultaneous connections, allowing for detailed control.
Privileged Access 🔑 Assign privileged access to specific user groups, granting them exemption from certain restrictions and ensuring uninterrupted service even durin attacks.
Customizable Policies ⚙️ Modify SmartShield's default policies to suit your specific needs, such as request limits, time budgets, and more.

Why use Cosmos?

Here's a simple example of how Cosmos can help you:

Another example:

If you have any further questions, feel free to join our Discord!

Let's Encrypt

As A Developer

Licence

Cosmos is using the Apache 2.0 Licence with the Commons Clause 1.0. This is a common clause among open source infrastructure software, such as databases, reverse proxies, etc...

TL;DR: You can use it freely. You can also fork it and redistribute it, But you are not allowed to sell it, a derivative or to sell a service based on it (ex. SaaS or PaaS).

Note that you are allowed to use it to host a monetized business website, a blog etc... as long as your business does not involve selling Cosmos or its features.

Installation

Installation is simple using Docker:

text

sudo docker run -d --network host  --privileged --name cosmos-server -h cosmos-server --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket -v /:/mnt/host -v /var/lib/cosmos:/config azukaar/cosmos-server:latest

IF YOU ARE USING WINDOWS OR MAC OS YOU CANNOT USE THE HOST MODE OF DOCKER. Please replace --network host with -p 80:80 -p 443:443 -p 4242:4242/udp

In this command, -v /:/mnt/host is optional and allow to manage folders from Cosmos, you can remove it if you don't want it but you will have to create your container's bind folders manually.

Port 4242 is a UDP port used for the Constellation VPN.

You also need to keep the docker socket mounted, as Cosmos needs to be able to manage your containers.

You can tweak the config file accordingly. Some settings can be changed before end with env var. see here.

If you are having issues with the installation, please contact us on Discord!

Contribute

Contribute.md

File: go-sdk/README.md

Cosmos Server Go SDK

Auto-generated Go client for the Cosmos Server API.

Installation

bash

go get github.com/azukaar/cosmos-server/go-sdk

Usage

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"net/http"

	cosmossdk "github.com/azukaar/cosmos-server/go-sdk"
)

func main() {
	httpClient := &http.Client{
		Transport: &http.Transport{
			TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
		},
	}

	addToken := func(ctx context.Context, req *http.Request) error {
		req.Header.Set("Authorization", "Bearer "+token)
		return nil
	}

	client, err := cosmossdk.NewClient(
		"https://cosmos.example.com/cosmos",
		cosmossdk.WithHTTPClient(httpClient),
		cosmossdk.WithRequestEditorFn(addToken),
	)
	if err != nil {
		panic(err)
	}

	// List routes
	resp, err := client.GetApiRoutes(context.Background())
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	fmt.Println(resp.StatusCode)
}

Generation

The SDK is auto-generated from the OpenAPI spec using oapi-codegen. To regenerate:

bash

bash scripts/generate-api.sh

This runs on every commit via a pre-commit hook.

File: sdk/README.md

cosmos-cloud-sdk

JavaScript/TypeScript SDK for the Cosmos Server API.

Install

bash

npm install cosmos-cloud-sdk

Quick Start

const { createClient } = require('cosmos-cloud-sdk');
// or: import { createClient } from 'cosmos-cloud-sdk';

const cosmos = createClient({
  baseUrl: 'https://my-cosmos.example.com',
  token: 'cosmos_abc123...',
});

// List containers
const containers = await cosmos.docker.list();
console.log(containers.data);

// List users
const users = await cosmos.users.list();

// Get server status
const status = await cosmos.getStatus();

API Reference

`createClient({ baseUrl, token })`

Creates a Cosmos API client.

baseUrl — Your Cosmos server URL (e.g. https://my-cosmos.example.com)
token — API token (starts with cosmos_)

Returns an object with namespaced API methods:

Namespaces

Namespace	Description
`cosmos.docker`	Containers, volumes, networks, images
`cosmos.users`	User management, 2FA, notifications
`cosmos.config`	Server configuration, routes, DNS
`cosmos.storage`	Disks, mounts, RAID, SnapRAID
`cosmos.constellation`	VPN devices, tunnels
`cosmos.cron`	Job management
`cosmos.backups`	Backup & restore
`cosmos.metrics`	Metrics & events
`cosmos.market`	Marketplace
`cosmos.rclone`	Cloud storage (rclone)
`cosmos.apiTokens`	API token management
`cosmos.auth`	Login, logout, sudo

Top-level methods

Method	Description
`cosmos.getStatus()`	Server status
`cosmos.isOnline()`	Check connectivity
`cosmos.restartServer()`	Restart server
`cosmos.forceAutoUpdate()`	Force update
`cosmos.terminal(cmd?)`	Host terminal (WebSocket)
`cosmos.uploadImage(file, name)`	Upload image
`cosmos.checkHost(host)`	DNS check
`cosmos.getDNS(host)`	DNS lookup

Examples

// Docker
const containers = await cosmos.docker.list();
await cosmos.docker.manageContainer('my-app', 'stop');
await cosmos.docker.manageContainer('my-app', 'start');
const logs = await cosmos.docker.getContainerLogs('my-app', 'error', 100);

// Streaming (image pull with progress)
await cosmos.docker.pullImage('nginx:latest', (line) => {
  console.log('Progress:', line);
});

// Users
await cosmos.users.create({ nickname: 'bob', password: '...' });
const user = await cosmos.users.get('bob');

// Config
const config = await cosmos.config.get();
await cosmos.config.set(config.data);
await cosmos.config.updateDNS({ dnsPort: '53' });

// API tokens
const tokens = await cosmos.apiTokens.list();
const newToken = await cosmos.apiTokens.create({
  name: 'my-automation',
  readOnly: true,
});

// Backups
const snapshots = await cosmos.backups.listSnapshots('daily');
await cosmos.backups.restoreBackup('daily', { snapshotId: 'abc', target: '/data' });

// WebSocket (terminal)
const ws = cosmos.docker.attachTerminal('my-container');
ws.onmessage = (e) => console.log(e.data);

More Examples

See the examples directory for full, runnable scripts covering dashboards, CI/CD deployments, container management, and backups.

Response Format

All methods return the raw API response:

{
  status: 'OK',
  data: { /* endpoint-specific data */ },
  message: '...'
}

On error, a CosmosError is thrown with message, status, and code properties.

Requirements

Node.js 18+ (uses built-in fetch)
Works in browsers too (bundled as ESM and CJS)
WebSocket support requires ws package in Node.js < 22

Version

The SDK version is synced with the Cosmos Server version.

File: terraform-provider-cosmos/README.md

Terraform Provider for Cosmos Server

Manage Cosmos Server resources with Terraform.

Requirements

Terraform >= 1.0
Go >= 1.22 (for development)
A running Cosmos Server instance with an API token

Installation

hcl

terraform {
  required_providers {
    cosmos = {
      source = "cosmos-cloud.io/azukaar/cosmos"
      # explicit version (for beta release for ex.)
      # version = "0.22.0-unstable08"
    }
  }
}

provider "cosmos" {
  base_url = "https://cosmos.example.com"  # or COSMOS_BASE_URL env
  token    = var.cosmos_token               # or COSMOS_TOKEN env
  insecure = true                           # or COSMOS_INSECURE env
}

terraform init will automatically download the provider for your platform.

Manual installation

Alternatively, download the binary from GitHub Releases and place it in:

text

~/.terraform.d/plugins/cosmos-cloud.io/azukaar/cosmos/<VERSION>/<OS>_<ARCH>/

Provider Configuration

Attribute	Type	Required	Description
`base_url`	string	yes	Cosmos Server URL (e.g. `https://cosmos.example.com`)
`token`	string	yes	API token (sensitive)
`insecure`	bool	no	Skip TLS verification. Default: `false`

All attributes can be set via environment variables: COSMOS_BASE_URL, COSMOS_TOKEN, COSMOS_INSECURE.

Resources

Resource	Description
`cosmos_route`	Proxy route with smart shield, auth, and filtering
`cosmos_docker_service`	Docker container (JSON blob config, recreate on change)
`cosmos_docker_volume`	Docker volume
`cosmos_docker_network`	Docker network
`cosmos_api_token`	API token (token value returned once on create)
`cosmos_user`	User account
`cosmos_backup`	Backup configuration (password managed server-side)
`cosmos_alert`	Alert with conditions and actions
`cosmos_cron_job`	Scheduled cron job
`cosmos_openid_client`	OpenID Connect client (secret generated server-side, returned once)
`cosmos_constellation`	Initialize Constellation VPN (destroy resets the VPN)
`cosmos_constellation_device`	VPN device (config YAML returned once on create)
`cosmos_constellation_dns`	Constellation DNS entry
`cosmos_snapraid`	SnapRAID array configuration
`cosmos_storage_mount`	Storage mount (all fields require replacement)

Data Sources

Data Source	Description
`cosmos_status`	Server status (hostname, version, docker/constellation status)
`cosmos_containers`	List of running Docker containers

Examples

See the examples/ directory for complete, working configurations:

web-app — Token, volume, container, route with smart shield, backup, and alert
vpn — Constellation VPN init, device, and DNS

Development

Build and install locally

bash

cd terraform-provider-cosmos
make build    # compile
make install  # copy to ~/.terraform.d/plugins/

After installing, in your Terraform project:

bash

rm .terraform.lock.hcl && terraform init

Dev overrides (faster iteration)

Add to ~/.terraformrc:

hcl

provider_installation {
  dev_overrides {
    "cosmos-cloud.io/azukaar/cosmos" = "/path/to/terraform-provider-cosmos"
  }
  direct {}
}

Then just make build and run terraform plan directly — no terraform init needed.

Project structure

text

main.go                           # Entry point
internal/
  provider/provider.go            # Provider config
  client/client.go                # SDK wrapper, response parsing, retry logic
  resources/                      # All resource implementations
  datasources/                    # Data source implementations
examples/                         # Usage examples

Adding a new resource

Create internal/resources/my_resource.go
Implement resource.Resource and resource.ResourceWithImportState
Register it in internal/provider/provider.go -> Resources()
Run make build to verify

Common patterns

Response parsing: client.ParseResponse[T]() for typed, client.CheckResponse() for status-only, client.CheckStreamingResponse() for streaming endpoints
404 handling: client.IsNotFound(err) — Read methods should call resp.State.RemoveResource(ctx) on 404
Create-time secrets: Computed + Sensitive with UseStateForUnknown — capture on create, preserve on read
Optional with server defaults: Optional + Computed + Default to avoid phantom diffs
Nested objects: Use types.Object (not Go struct pointers) for SingleNestedAttribute

Docker & Self-Hosted Deployment Verified OCI

File: README.md Copy Chapter

Thanks to the sponsors:

What are the differences with other alternatives?

SDK and Terraform

What is the SmartShield?

Why use Cosmos?

Let's Encrypt

As A Developer

Licence

Installation

Contribute

File: Readme.md Copy Chapter

Thanks to the sponsors:

What are the differences with other alternatives?

SDK and Terraform

What is the SmartShield?

Why use Cosmos?

Let's Encrypt

As A Developer

Licence

Installation

Contribute

File: readme.md Copy Chapter

Thanks to the sponsors:

What are the differences with other alternatives?

SDK and Terraform

What is the SmartShield?

Why use Cosmos?

Let's Encrypt

As A Developer

Licence

Installation

Contribute

File: go-sdk/README.md Copy Chapter

Cosmos Server Go SDK

Installation Copy Chapter

Usage Copy Chapter

Generation Copy Chapter

File: sdk/README.md Copy Chapter

cosmos-cloud-sdk

Install Copy Chapter

Quick Start Copy Chapter

API Reference Copy Chapter

`createClient({ baseUrl, token })` Copy Section

Namespaces Copy Section

Top-level methods Copy Section

Examples Copy Section

More Examples Copy Chapter

Response Format Copy Chapter

Requirements Copy Chapter

Version Copy Chapter

File: terraform-provider-cosmos/README.md Copy Chapter

Terraform Provider for Cosmos Server

Requirements Copy Chapter

Installation Copy Chapter

Manual installation Copy Section

Provider Configuration Copy Chapter

Resources Copy Chapter

Data Sources Copy Chapter

Examples Copy Chapter

Development Copy Chapter

Build and install locally Copy Section

Dev overrides (faster iteration) Copy Section

Project structure Copy Section

Adding a new resource Copy Section

Common patterns Copy Section

Explore Related Technologies & Topics

File: README.md

File: Readme.md

File: readme.md

File: go-sdk/README.md

Installation

Usage

Generation

File: sdk/README.md

Install

Quick Start

API Reference

`createClient({ baseUrl, token })`

Namespaces

Top-level methods

Examples

More Examples

Response Format

Requirements

Version

File: terraform-provider-cosmos/README.md

Requirements

Installation

Manual installation

Provider Configuration

Resources

Data Sources

Examples

Development

Build and install locally

Dev overrides (faster iteration)

Project structure

Adding a new resource

Common patterns