caido · Sytten · Apr 6, 2024 · Apr 6, 2024 · Apr 6, 2024 · Apr 6, 2024
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -23,6 +23,7 @@
 
 # Concepts
 
+- [Instances](./concepts/instances.md)
 - [HTTPQL](./concepts/httpql.md)
 - [Workflows](./concepts/workflows.md)
 - [Tabs](./concepts/tabs.md)
@@ -61,7 +62,6 @@
 
 # Internals
 
-- [(WIP) Instances](./internals/instances.md)
 - [Files](./internals/files.md)
 - [Cloud](./internals/cloud.md)
 - [Authentication](./internals/authentication.md)

diff --git a/src/_images/client_server.png b/src/_images/client_server.png
diff --git a/src/_images/error_url_generation.png b/src/_images/error_url_generation.png
diff --git a/src/_images/instances_dashboard.png b/src/_images/instances_dashboard.png
diff --git a/src/_images/instances_desktop.png b/src/_images/instances_desktop.png
diff --git a/src/_images/instances_local.png b/src/_images/instances_local.png
diff --git a/src/_images/instances_remote.png b/src/_images/instances_remote.png
diff --git a/src/common_errors.md b/src/common_errors.md
@@ -32,6 +32,14 @@ Once you've claimed your instance, make sure to remove the `--reset-credentials`
 
 While not ideal, deleting your Caido data folder will allow you to start with a fresh installation. Check out the [Files](/internals/files.md) page to locate your data folder.
 
+## "Login URL generation failed"
+
+<img alt="Date mismatch" src="/_images/error_url_generation.png" width="400"/>
+
+You may encounter this error when trying to access an instance that you **deleted** in the Caido [dashboard](https://dashboard.caido.io).
+
+The easiest way to fix this issue is to [Reset the instance credentials](#method-2-reset-the-instance-credentials).
+
 ## I have paid for "Pro" but it still shows "Community" in the app
 
 Caido caches the state of your account. Any changes to your account can take some time to update.

diff --git a/src/concepts/instances.md b/src/concepts/instances.md
@@ -0,0 +1,39 @@
+# Instances
+
+We use the concept of `Instance` to refer approximately to an installation of Caido.
+
+To be precise, an instance is the set of files contained in the the [data location](/configuration/data_location.md), thus you can have _multiple_ Caido instances on one machine if you change the data path.
+
+## Why?
+
+First, we have to go back on the fact that Caido is built around a `client/server` architecture. This means you can deploy the `Caido CLI` anywhere (like on [VPS](/user_guide/vps.md) or on [Docker](/user_guide/docker.md)). We thus need some form of _access control_ to authenticate the client (`Browser` or `Desktop Application`) that connects to that server.
+
+You can find all details in our [guide on the topic](/internals/authentication.md), but in essence each instance is tied to your account so only you can access it (sharing will be added eventually). Each instance has a set of OAuth credentials given to it by our cloud service that it uses to identify itself when communicating with us.
+
+<img alt="Client Server Architecture" src="/_images/client_server.png" no-shadow/>
+
+## Desktop
+
+When you use the `Desktop Application`, you will see by default a `Local Instance`. This means that you will spawn a `Caido CLI` process locally on the given port and with the default [data path](/configuration/data_location.md).
+
+<img alt="Desktop Application Instances" src="/_images/instances_desktop.png" no-shadow/>
+
+### Local
+
+You can add instances with the `New instance`, those can be other `Local` instances if you want to use another [data path](/configuration/data_location.md) or port for example.
+
+<img alt="New local instance" src="/_images/instances_local.png" center width="500"/>
+
+### Remote
+
+They can also be `Remote` instances if you just want to connect to an existing `Caido CLI` running somewhere else.
+
+<img alt="New remote instance" src="/_images/instances_remote.png" center width="500"/>
+
+## Dashboard
+
+To manage your instances, you can head over to the [Dashboard](https://dashboard.caido.io/instances).
+
+> **WARN**: If you delete an instance and try to log-in again, you will see the error ["Login URL generation failed"](http://localhost:3000/common_errors.html#login-url-generation-failed). You will need to reset the credentials.
+
+<img alt="Dashboard for instances" src="/_images/instances_dashboard.png"/>
diff --git a/src/internals/instances.md b/src/internals/instances.md