What Is Cloudillo

Cloudillo is a versatile Distributed, Self-Hosted, Open-Source Application Platform designed to empower your creativity, facilitate seamless collaboration, and enable easy sharing.

Cloudillo can be:

• Your Document Store: Store all your documents securely, accessible only to you or shared with selected individuals or groups.
• Your Personal or Group Knowledge Base: Compile and organize your knowledge effortlessly, whether it’s for personal use or sharing within your team or community.
• Your Collaboration Platform: Work together with colleagues or friends on projects, documents, or tasks in real-time, enhancing productivity and efficiency.
• Your Community Network: Build a vibrant community network where members can connect, share ideas, and collaborate on common interests or goals.

What sets Cloudillo apart?

Global Accessibility, Local Control

Cloudillo takes a unique approach by storing all your data locally while making it globally accessible through its unparalleled API. This ensures you have full control over your data while enjoying the benefits of a worldwide reach.

Revolutionary Global Authentication and Authorization

Cloudillo introduces a groundbreaking method for Global Authentication, Authorization, and Verification. Share your data securely without requiring users to register on your instance, mirroring the convenience of Cloud-based platforms.

Seamless Interconnectivity

Thanks to this fresh perspective, Cloudillo-based applications can establish connections that might seem impossible on other platforms. This newfound flexibility opens doors to innovative and seamless collaborations between applications.

Ready to experience collaboration on a whole new level? Explore Cloudillo and witness the difference.

Getting started

When you are ready to join the Cloudillo Network, you’ll need to make two decisions:

1. Identity

You identity is like your unique username on the network. Cloudillo uses the Domain Name System — the backbone of the internet — to create profile identities. This approach eliminates the need for a central provider, although it might seem overwhelming for newcomers. To simplify the process, you have two options:

• Option 1: If you already have a domain name, you can use it to create your identity. This option may require technical know-how — but we’ve got you covered.
• Option 2: If you don’t have a domain name or prefer to avoid the hassle, you can choose a Cloudillo Identity Provider. These services make it super easy to create your identity. We are planning to start cloudillo.net, a low-cost Identity Provider service, but in the future you might have other options.

2. Storage Provider

This is where your data will be stored.

• Option 1: If you have your own server or a home NAS (Network Attached Storage), you can use that as your storage provider. You can even invite your family and friends to use it.

• Option 2: Don’t want to manage your own storage? No problem. You can opt for a Cloudillo Storage Provider. They handle all the technical stuff for you.

Why Two Services?

Cloudillo is all about giving you control and keeping your data secure. Separating your identity from your storage provider makes it easy to switch storage options whenever you need to.

Using Your Own Domain

Many people and organizations already have domain names. You can use yours as your identity and even create sub-identities for different purposes. This helps organizations give their members identities tied to their domain.

Changing Your Storage Provider

If you control your identity, switching storage providers is simple. Whether you move to self-hosting or another provider, your identity remains intact, making the transition seamless.

Can You Use the Same Provider for Both?

Technically, yes. However, for security reasons, it’s better to choose different providers. Using separate providers avoids potential conflicts of interest if you ever need to switch storage providers.

Trust Your Identity Provider

Your identity provider is crucial. Ensure you trust them, as they could theoretically take control of your identity. If this concerns you, registering your own domain name can offer maximum security.

Installing Cloudillo Yourself

You have several options for installing Cloudillo. The simplest and most versatile is using Docker Another thing you should decide is whether you want to run Cloudillo in standalone mode or in proxy mode. The latter is useful if you want to run Cloudillo behind a reverse proxy.

Running Cloudillo using Docker in Standalone Mode

Here is a simple one-liner:

docker run -d --name cloudillo \
  -v /var/vol/cloudillo:/data \
  -p 443:443 -p 80:80 \
  -e LOCAL_IPS=1.2.3.4 \
  -e BASE_ID_TAG=agatha.example.com \
  -e BASE_APP_DOMAIN=agatha.example.com \
  -e BASE_PASSWORD=SomeSecret \
  -e ACME_EMAIL=user@example.com \
  -e ACME_TERMS_AGREED=true \
  cloudillo/cloudillo:latest

You basically need a local directory on your server and mount it to /data inside the container and publish port 443 (HTTPS) and 80 (HTTP). You can read about the configuration environment variables below.

Cloudillo in standalone mode uses TLS certificates managed by Let’s Encrypt. If you want to use different certificates then you have to use Proxy Mode.

Here is a docker-compose for the same:

version: "3"
services:
  cloudillo:
    image: cloudillo/cloudillo:latest
    container_name: cloudillo
    volumes:
      - /var/vol/cloudillo:/data
    ports:
      - 443:443
      - 80:80
    environment:
      - LOCAL_IPS: 1.2.3.4
      - BASE_ID_TAG: agatha.example.com
      - BASE_APP_DOMAIN: agatha.example.com
      - BASE_PASSWORD: SomeSecret
      - ACME_EMAIL: user@example.com
      - ACME_TERMS_AGREED: true

Configuration Environment Variables

In case you are not familiar with the Cloudillo Identity System we provide some information about the notions used above:

The ID tag is the unique identifier of a Cloudillo profile. It can be any domain name associated with a user.

The App Domain is the domain address used by the user to access their Cloudillo shell. Currently the App Domain is also unique for every user, but it might change in the future. It is preferably the same as the ID tag of the user, but it can be different when the domain is used by an other site.

For a domain to work as a Cloudillo Identity it must serve a Cloudillo API endpoint accessable at the cl-o subdomain. In the above example you have to create the following DNS records:

Running Cloudillo using Docker in Proxy Mode

An other one-liner:

docker run -d --name cloudillo \
  -v /var/vol/cloudillo:/data \
  -p 1443:1443 \
  -e MODE=proxy \
  -e LOCAL_IPS=1.2.3.4 \
  -e BASE_ID_TAG=agatha.example.com \
  -e BASE_APP_DOMAIN=agatha.example.com \
  -e BASE_PASSWORD=SomeSecret

In proxy mode you have to provide your own solution for TLS certificates. In proxy mode Cloudillo serves its API port on 1443 but using HTTP and it doesn’t serve the HTTP port by default. You should provide your own redirections. However, you can turn it on with the LISTEN_HTTP=1080 environment variable.

We provide an example nginx configuration:

server {
	listen   80;
	server_name  agatha.example.com cl-o.agatha.example.com;

	location /.well-known/ {
		root    /var/www/certbot;
		autoindex off;
	}
	location / {
		return 301 https://$host$request_uri;
	}
}

server {
	listen 443 ssl;
	server_name agatha.example.com cl-o.agatha.example.com;
	ssl_certificate /etc/letsencrypt/live/agatha.example.com/fullchain.pem;
	ssl_certificate_key /etc/letsencrypt/live/agatha.example.com/privkey.pem;

	location /.well-known/cloudillo/id-tag {
		add_header 'Access-Control-Allow-Origin' '*';
		return 200 '{"idTag":"agatha.example.com"}\n';
	}
	location /api {
		rewrite /api/(.*) /api/$1 break;
		proxy_pass http://localhost:1443/;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Forwarded-Proto https;
		proxy_set_header X-Forwarded-Host $host;
		client_max_body_size 100M;
	}
	location /ws {
		proxy_pass http://localhost:1443;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Forwarded-Proto https;
		proxy_set_header X-Forwarded-Host $host;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection "Upgrade";
	}
	location / {
		# You can serve the cloudillo shell locally, or proxy it.
		root /home/agatha/cloudillo/shell;
		try_files $uri /index.html;
		autoindex off;
		expires 0;
	}
}

Installing Cloudillo from Source

You can visit Cloudillo’s GitHub page for instructions:

https://github.com/cloudillo/cloudillo

First Steps

Once you’ve set up your Cloudillo Identity and Storage, it’s time to get creative and start sharing content.

Accessing your Cloudillo Space

To access your Cloudillo Space, use your own URL, which usually matches your Identity. First, authenticate yourself using the method you set up during installation or registration.

Inside your Cloudillo Space you’ll run various applications from other spaces. Cloudillo will always let you know when this happens and shows the trust level of the application.

The Cloudillo Shell

When you enter your Cloudillo Space, you’ll see the Cloudillo Shell. This is the main application and it typically displays a header on the top of the window, unless you are running a full-screen application.

Connecting with Others

Cloudillo doesn’t have a central database, so you’ll need to know the identities of other users, organizations, or groups to connect with them. Once you’ve joined some groups, you can connect with others through those groups.

You can start by following the cloudillo.net identity, which is the official identity of the Cloudillo Community. From there you can find and join other groups.

Identity System & User Profiles

Cloudillo Profiles are located using a DNS-based identity system. Each Cloudillo Identity is associated with a specific API endpoint, which can be accessed via the “cl-o” subdomain of the identity. For example, the API domain of the cloudillo.net identity is available at https://cl-o.cloudillo.net/.

Retrieving a Cloudillo Profile

You can retrieve a Cloudillo profile by making an API request to the /api/me endpoint of the identity’s API domain:

curl https://cl-o.cloudillo.net/api/me

Example response:

{
  "idTag": "cloudillo.net",
  "name": "Cloudillo",
  "type": "community",
  "profilePic": "QoEYeG8TJZ2HTGhVlrtTDBpvBGOp6gfGhq4QmD6Z46w",
  "keys": [
    {
      "keyId": "20250205",
      "publicKey": "MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAENSq6EZZ+xCypWNkm+0+MHIZfLX7I01wTT+SOw7DoOUOuDAWKMkhBVG+SUb9AzCxEOlmkefuEW5zmXNwmH2MphEQW/r18RDjd+Nt5nbemBsoQzsm2Wg/mUyWBsKYs1oe5"
    }
  ]
}

Profile Fields Explained

• idTag: The Identity Tag associated with the profile.
• name: The display name of the profile.
• type: Either empty for a personal profile or contains “community” for community profiles.
• profilePic: The identifier for the profile picture, which can be retrieved via the storage API.
• keys: A list of cryptographic keys associated with the profile.

Profile Picture Retrieval

The profilePic field contains an identifier that allows retrieval of the profile’s profile picture using the Cloudillo Storage API. A request to retrieve the profile picture may look like this:

curl https://cl-o.nikita.cloudillo.net/api/store/NMzE4gNI29aEkiV6Q7I1UNWh4x2gFZ7753Pl74veYtU

Key Management & Future Enhancements

A profile supports multiple cryptographic keys, enabling periodic key rotation for enhanced security. Older keys can be deprecated while maintaining account integrity.

Future enhancements will introduce key usage declarations, allowing users to assign specific permissions to different keys. This will enable finer security control and multi-purpose authentication, such as signing different actions

Actions & Action Tokens

An Action Token represents a user action within Cloudillo. It can contain a post, comment, like, or other interaction. Each Action Token is:

• Cryptographically signed by it’s creator.
• Time-stamped with an issue time.
• Structured with relevant metadata about the action.

Action Token Fields

Attachment and Token IDs

Attachment and token IDs are derived using SHA256 hashes of their content, ensuring immutable references to external objects.

Overriding Action Tokens

• Each token type is linked to a database key, allowing previous tokens to be overridden where applicable.
• The database key always contains the “iss” (issuer) field and may include other relevant fields.
• Example: A REACT token (representing a reaction to a post) uses a key composed of “iss” and “p” (parent post ID). If a user reacts to the same post multiple times, the latest reaction replaces the previous one.

Action Token Types

User relationships

CONN: Connect

Represents one side of a connection between two profiles. A connection is established when both parties issued a connection token to each other

FLLW: Follow

Represents a follow relationship (a profile follows another profile).

Content

POST: Post

Represents a post created by a profile.

ACK: Acknowledge

Represents an acknowledge of a token issued to an other profile. It is issued by the audience of the original token.

CMNT: Comment

Represents a comment, attached to some other token.

REACT: React

Represents a reaction (like, dislike, etc.) to some other token, issued by a user.

RESP: Response (TODO)

Represents a response to a question

can be a response to a POST:VOTE, or POST:EVENT type token

STAT: Statistics

Represents statistics about some other token (number of reactions, comments, votes, etc.)

Repost / share action (TODO)

Represents the reposting of an other content to a different profile

File sharing

FSHR: File share

Represents a file share issued to a profile

Communication

CONV: Conversation (TODO)

Represents a conversation between several profiles (group chat)

INV: Invitation (TODO)

Represents an invitation for a profile to join a conversation

JOIN: Join (TODO)

Represents that a profile joined a conversation

MSG: Message

Represents a message sent by one profile to an other

TODO

Permissions

• Public
• Followers
• Connections
• Tags

Flags

• Can react
• Can comment
• With permissions?

Tokens

Review

Represents a review post with a rating, attached to something

Patch

Represents a patch of a token (modify the content, or flags for example)

Resource

Represents a resource that can be booked (e.g. a conference room)

Book

Represents a booking of a resource.

Access Control & Resource Sharing

Access tokens are used to authenticate and authorize requests to the API. They are usually bound to a resource, which can reside on any node within the Cloudillo network.

Requesting an Access Token

When a user wants to access a resource, they follow this process:

1. The user’s node requests an access token.
2. If the resource is local, the node issues the token directly.
3. If the resource is remote, the node authenticates with the remote node and requests a token on behalf of the user.
4. The access token is returned to the user, allowing them to interact with the resource directly on its home node.

Security & Trust Model

• Access tokens are cryptographically signed to prevent tampering.
• Tokens have expiration times and scopes to limit misuse.
• Nodes validate access tokens before granting access to a resource.

Example 1: Request access to own resource

sequenceDiagram
    box Alice frontend
        participant Alice shell
        participant Alice app
    end
    participant Alice node
    Alice shell ->>+Alice node: Initiate access token request
    Note right of Alice node: Create access token
    Alice node ->>+Alice shell: Access token granted
    deactivate Alice node
    Alice shell ->>+Alice app: Open resource with this token
    deactivate Alice shell
    Alice app ->+Alice node: Use access token
    loop Edit resource
        Alice app --> Alice node: Edit resource
    end
    deactivate Alice app

• Alice opens a resource using her Cloudillo Shell
• Her shell initiates an access token request at her node
• Her node creates an access token and sends it to her shell
• Her shell gives the access token to the App Alice uses to open the resource
• The App uses the access token to edit the resource

Example 2: Request access to resource of an other identity

sequenceDiagram
    box Alice frontend
        participant Alice shell
        participant Alice app
    end
    participant Alice node
    participant Bob node
    Alice shell ->>+Alice node: Initiate access token request
    Note right of Alice node: Create signed request
    Alice node ->>+Bob node: Request access token
    Note right of Bob node: Verify signed request
    Note right of Bob node: Create access token
    deactivate Alice node
    Bob node ->>+Alice node: Grant access token
    deactivate Bob node
    Alice node ->>+Alice shell: Access token granted
    deactivate Alice node
    Alice shell ->>+Alice app: Open resource with this token
    deactivate Alice shell
    Alice app ->+Bob node: Use access token
    loop Edit resource
        Alice app --> Bob node: Edit resource
    end
    deactivate Alice app
    deactivate Bob node

• Alice opens a resource using her Cloudillo Shell
• Her shell initiates an access token request through her node
• Her node creates a signed request and sends it to Bob’s node
• Bob’s node creates an access token and sends it back to Alice’s node
• Alice’s node sends the access token to her shell
• Her shell gives the access token to the App Alice uses to open the resource
• The App uses the access token to edit the resource