Circles for NC22

Types & Config

Biggest change in Circles 22 is the replacement of ‘Types’.
In older version of the App, you could set a Circle as Personal, Public, Closed or Secret at the creation process.

This have be replaced by a ‘Config’ flag that can be stack on top of each other, and changed at any time.
Some flag are only available to Circles create by users, others can be managed by the Circles App or by an external App.

  • VISIBLE: Circle is visible to everyone. If not set, only members
    will be able to view the Circles in the list.

  • OPEN: Users can join, or request to join the Circle

  • INVITE: Adding a member send an invitation that needs to be accepted by the recipient

  • REQUEST: Users needs to send a request to be member, request needs to be accepted by a Moderator

  • FRIEND: Members can invite users to the Circle (By default, only Moderator are able to do that)

  • ROOT: Circles cannot be a member of another Circle (Nested Circles)

  • FEDERATED: Circles is Federated (ALPHA)

Those config flags are not available to users, but only to apps that
want to create/manage System Circles:

  • NO_OWNER: Circles have no owner.
  • HIDDEN: Hidden from the listing, even to members, but available as a
    share entity
  • BACKEND: Fully Hidden, only used for backend purpose
  • LOCAL: Local, even in GlobalScale setup

Behind the Circles

Better API

If you need information related to Circles from the front-end, you can use the ocs api. This is the API used by the Contacts app to manage circles and members.

The back-end also comes with a new API. It is not yet fully integrated to core, but you can load the Manager using:

     $circlesManager = \OC::$server->get(\OCA\Circles\CirclesManager::class);

The CirclesManager comes with a minimum of functionality, and more will comes in future version. If you have any questions, do not hesitate to ask in here.

Complete documentation is on its way.


Circles are identified by a unique ID. But not just Circles, any entity that interact with the app got its own unique ID, that we will call ‘SingleId’

You can force the generation of SingleId by running occ circles:sync or just wait for the App to generate one when needed.

As an example:

As you can see, Nextcloud Groups have been duplicated as a SYSTEM/NO_OWNER/HIDDEN Circles and, like Nextcloud Users, have their own singleId.

One of the idea behind this identification of Entities is to standardize the
sharing system in the future.

Nested Circles

You can invite another Circles within a Circles and there is no limit to your imagination.
This way, a file shared to the Top Circles will be available to the members of any downstream Circle.

To avoid exponential use of resources when facing huge cascades of Circles within Circles, direct memberships and inherited memberships are cached in a specific table.


While already available, this is an ALPHA feature that will be available in NC23.
The idea behind is that you can set a Circle as FEDERATED. Meaning
that its content will be shared to an other instance of Nextcloud.

Quick overview: you can identify a remote instance of Nextcloud as friendly and assign a level of Trust.

In a GlobalScale setup, the trust is maximum and all Circles are shared between each instance of the GlobalScale.

If the remote instance is not considered as GlobalScale, only Circles set as FEDERATED are shared. The lowest level of Trust will hide the members that does not belongs to the remote instance.

I consider this as the main feature of Circles as the end-game is a fully decentralized network of instance of Nextcloud, not just for files, but for any app that wish to use Circles’ API.
More about this in the incoming documentation.


During the presentation earlier today, I saw some questions about the App, here are the awaited answers.

Disabling the App

As of today, with NC22.0.0, you can still disable Circles.
But this should not be possible in future version of Nextcloud.
The idea is that some apps might needs some features from the App.
However, it will be possible to block your users to create Circles.


No. The Circles app will allow in a future version to add a config flag to generate a default folder available to all members of a Circles. However this folder will not be included in the quota.

However, we will work on a way to add Circles to the group folders app.

Migration from NC21

Yes, your old Circles will still be available in NC22. The type (public, closed, secret) will be removed and translated to the new ‘config’ system.

Please note that Circles cannot be password protected yet.
This will be implemented as soon as possible. Hopefully for NC22.0.1


Although that sounds like rocket science, you probably mean ‘level of trust’ and not ‘level of thrust’. :slight_smile:


Thx for this great outlook. With this, folders and files may be treated more flexible than with folder and groups or group folders? Will group folders be necessary beyond the issue when deleting a user?

I updated to Nextcloud 22. Circle is activated. Unfortunately, it doesn’t show the app icon at the top of the icon bar.

Circles is now back-end only. You will need the Contacts app to manage your Circles.


Hello, which issue are we talking about ?

Can you elaborate a bit more?
The app cannot be accessed directly (…/apps/cricles), this only gives a blank json response ([ ]) and no error message whatsoever.

Tried it with a fresh install of NC 22 to check out the collective app. When creating a new collective, a link to the circles app is provided, but this ends up with the empty resonse.

Where am I supposed to manage cricles now?

As said, you will need the Contacts app to manage your Circles

Ok, I’ll have a look at it.
Is this change documented anywhere? Wasn’t able to find information about it.

OK; I was a bit confused, because on a fresh NC 22 instance, the circles app is enabled, but the contacts app is not enabled. That was the missing link.

I think he means this issue: if you share a folder with user A, and user A creates a file or folder in that shared folder, it will be deleted when you delete user A’s account (and there is no warning). You need to use group folders app.
→ Yes it would be great if this issue gets solved through circles somehow. No, having a default folder for each circle will not do the trick. What I need: Create several folders, share each with certain groups/circles, ideally have ACL access control lists for subfolders.

Quotas are super difficult for shared folders anyway, not sure how to deal with it.

I am surprised to read that circles app will become part of core, and not possible to deactivate. I really hope that it will be super stable and make things easier, not more complicated as they are in NC21. When I look at what is going on with group folders (which is an official app) 🎯 📚 📕 FAQ ➕ KNOWN ISSUES · Issue #1414 · nextcloud/groupfolders · GitHub I get scared that this is not going to happen.

1 Like

Well, the default folder will not be linked to any user but to the Circles itself. Meaning that files generated inside the Folder will not be lost when user is removed.

Now, we are also working on implementing Circles into GroupFolder for 23.


I tried to find the url of ocs api for circles app. I can see here : circles/routes.php at master · nextcloud/circles · GitHub, that some ocs routes exists but I really don’t know what to put between “http://nextcloudinstance/ocs” and “/circles”. Does someone have any idea ?

I just updated to NC22 and played a bit with the new circle functionality. Now I would like to clean up, but I can’t delete the circles anymore. Everytime I click delete, the circle shows up again after a reload.
Any suggestions why and how to fix it?

I have the same issue on the latest nextcloud docker instance, this issue seems related to: Circle not work on fresh installed Nextcloud 22 · Issue #731 · nextcloud/circles · GitHub

May I ask if there will be the possibility to disable creating contacts/contacts app in NC and still be able to create circles in future releases?
We do not use the groupware functionalities of Nextcloud but use another suite instead. Additionally, we sync users and groups via LDAP. But since not all groups are synced it was pretty convenient to use circles to let users create the few missing groups themselves. But if people would be creating contacts in NC too they would wonder why these contacts do not appear in our existing groupware. Because NC does not support reading/syncing with external CalDAV-servers I cannot easily sync concacts to NC. Workarounds for this are rather complex. Therefore I disabled contacts.
Will future releases offer the choice between using circles with/without contacts?


Our circles app only goes up to 50 users per circle created. Where can I find the setting to increase the limit? Currently running NC 22.2.2

What is the result of:

 ./occ config:app:get circles members_limit

The command “…occ config:app:get circles members_limit”
outputs 50.
Can I change this or is it a fixed size?

Looks like this 50 user limit was just reported on Github.