> For the complete documentation index, see [llms.txt](https://cleyrop.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cleyrop.gitbook.io/docs/documentation-fr-en/the-factory/gerer-les-instances.md).

# Manage instances

An instance is a deployment of your Agent in a specific environment. Each app can have multiple instances (dev, prod, testing...).

***

## Create an instance from the internal registry

1. From your app's page, go to the tab **Instances**

2. Click **Create an instance**

3. **Step 1 - Deployment** :

   * Enter a **clear** unique identifier for the instance (e.g., "prod-api")
   * Check **Main instance** if you want this instance to be the reference
   * Select **Internal or external registry**
   * Choose the**image** to deploy
   * Configure the **resources** (CPU / RAM)
   * Configure the **deployment timeout** (default: 9 minutes)
   * Add port `22` to allow SSH connections and port `443` for HTTPS connections.
   * Define the **exposed port.** 
   * Enable a **persistent storage** if needed

4. **Step 2 - Configuration** :
   * For Apps: enable/disable the **Basic Auth security**
   * For Apps: Enable a **service account** to access **the project Work Data files** from your app. When enabled, configure:

     * **Role** : Viewer (read-only) or Editor (read + write)
     * **Projects** : restrict access to specific projects, or leave empty to give access to all projects

     A **Client ID** is automatically generated (format `sa-<instance-name>`), visible from the instance page once deployed.
   * Configure the **Health check** (TCP or HTTP)

5. **Step 3 - Environment variables** :
   * Add the **global variables**
   * **For Tools:** you can define **User Variables** : they will be configured by each user from the global assistant or the Agents listing. E.g.: personal API token

6. Click **Create**

The instance is created with the "Created" status. It must then be deployed.

You can view a deployment page to see the details.

{% hint style="warning" %}
The **storage size** persistent cannot **be modified** at present.
{% endhint %}

{% hint style="info" %}
CPU / RAM resources are allocated only at the time of **deploying**, not at creation.
{% endhint %}

{% hint style="info" %}
Add multiple environment variables at once by pasting them directly into the field (format `KEY=value`).
{% endhint %}

## Create an instance from an external registry

You can also deploy an image hosted on an external registry (DockerHub, private registry...).

1. In the "Deployment" step, select **External registry**
2. Enter:
   * **Image URL** (e.g.: `docker.io/my-org/my-image:v1.0` or by digest: `image-name@sha256:<digest>`
   * &#x20;**Access key** (if private registry)
   * **Username** (optional)
3. Continue the process normally

## Deploy an instance

{% hint style="info" %}
Only the **app owner** can launch deployment.
{% endhint %}

Deployment makes the agent instance accessible (via URL for Apps, or from the assistant for Tools).

You can deploy an instance from several places:

| Deployment point             | Deployed instance |
| ---------------------------- | ----------------- |
| Agent page → "Deploy" button | Main instance     |
| Instance card in the list    | Selected instance |
| Instance details page        | Viewed instance   |

**Deployment process**

1. Click **Deploy**
2. The instance changes to "Deployment in progress" status
3. At the end of the process:
   * **Success** : status "Deployed", access URL available
   * **Failure** : status "Failed", error logs available

The **deployment logs** and the **application logs** are available to diagnose issues:

* Deployments tab → "Logs" button: deployment tracking.
* Application logs tab: runtime errors and messages.

It is possible to**cancel an ongoing deployment** directly from the instance page or the card in the listing. The instance then returns to its previous state: "Created" status if it had never been deployed, or "Deployed" status with its last stable configuration if a previous deployment existed.

**Instance statuses**

| Status                 | Description                                       |
| ---------------------- | ------------------------------------------------- |
| Created                | Configured instance, not deployed                 |
| Deployment in progress | Deployment running                                |
| Deployed               | Active and accessible instance                    |
| Stopped                | Paused instance, resources released               |
| Failure                | Deployment failed                                 |
| Warning                | Redeployment failed, fallback to previous version |

#### Redeploy an instance

To redeploy an instance that has already been deployed:

1. Click **Redeploy** from the instance page or the card
2. Confirm the action: "Would you like to redeploy this instance? The current instance will be stopped and then a new deployment will be launched."
3. The old deployment is stopped and a new one is launched with the same configuration

#### Automatic fallback

{% hint style="warning" %}
In **the event of an error during a deployment**, if a previous valid deployment exists, the platform automatically performs **an automatic rollback** to the latest stable version.
{% endhint %}

If redeployment fails, if a previous version was successfully deployed:

* The platform automatically performs a **rollback** to the latest stable version
* The instance changes to "Warning" status with the message: "Redeployment failed. The instance has been restored to its last working version."
* The service is not interrupted
* The error logs from the failed deployment are available

## Define a Main instance

The first instance created automatically becomes the main instance. It is identifiable by a "Main" badge in the list.

To change the main instance:

1. Go to the list of instances
2. On the desired instance, click **Set as main**
3. Confirm the change

The main instance is the one:

* deployed when you click "Deploy" from the app page
* whose**URL will be used** by the application's users (App)
* whose tools will be used in Le Druide (Tools)

## Edit an instance

The owner can modify an instance's configuration from its details page.

**Changes with automatic redeployment**

The following changes trigger a new deployment:

* Docker image
* Resources (CPU / RAM)
* Environment variables
* Exposed port
* Health check
* Basic Auth configuration

**Changes without redeployment**

The following changes are applied immediately without redeployment:

* The instance name
* The deployment timeout

**Behavior in case of failure**

If redeployment following a change fails:

* Automatic fallback to the previous configuration
* Instance in "Warning" status
* Configuration change not applied
* Possibility to retry or cancel the changes

## Start / stop an instance

The app owner can start or stop each instance individually from its details page or from the instances list.

### **Stop an instance**

Stopping an instance releases CPU and RAM resources while keeping the configuration.

1. From the instance page or the card in the listing, click **Stop**
2. Confirm the action in the dialog box
3. The instance changes to "Stopped" status

{% hint style="warning" %}
Stopping an instance makes it inaccessible (URL unavailable for Apps, tool disabled for Tools).
{% endhint %}

### **Start an instance**

Starting reactivates a previously stopped instance with its existing configuration.

1. From the instance page or the card in the listing, click **Start**
2. The instance changes to "Deployment in progress" status
3. Once startup is complete, the instance returns to "Deployed" status

## **Resource management**

The compute resources allocated to agent instance deployments are independent of Spark and Python clusters, but shared among the apps themselves.

* If the platform reaches maximum capacity, it may become impossible to launch new applications.
* Resources (CPU/RAM) are released when stopped and reallocated when deployments start

In case of recurring saturation, contact the Customer Success Manager to adjust the overall capacity.

{% hint style="info" %}
If resources are no longer available, restart will be blocked until capacity is freed.
{% endhint %}

{% hint style="success" %}
**Best practice** : Stop development or test instances when they are not in use to free up cluster resources.
{% endhint %}

## Delete an instance or an app

**Delete an instance**

Deleting an instance removes:

* The active deployment (if any)
* The instance configuration
* The associated resources

The other instances of the app are not affected.

**Delete an app**

Deleting an app permanently removes:

* The entry in The Factory
* All associated instances
* All images from the internal registry
* Access in Le Druide (for Tools)

***

### Best practices for instance management

* **Clearly name** your instances according to their environment (dev, staging, prod)
* **Use the main instance** for your production environment
* **Stop the instances** of development/test when they are not in use
* **Monitor the statuses** : an instance in "Warning" requires intervention