# Butler User Guide

Butler is the Replica assistant for moving data, managing shared workspaces, and supporting automated workflows. You can use Butler from your local Replica session and from inside each Virtual Environment.

* **Context aware**: Features adjust based on where you are working.
* **Workflow agnostic**: Supports browser-based and code-driven workflows.
* **Data transfer**: Moves text and files between your desktop, environments, and enclaves.
* **Automation support**: Works with Enclaves and Jobs for repeatable tasks.
* **Configurable**: Availability depends on your organization's policies.

***

## Butler Home

Butler is available from two places:

### Local host access

On the **Environments** page in your browser, Butler actions appear in the top-right area of each environment card.

### Virtual Environment access

Inside a Virtual Environment, open Butler from the applications menu or from the environment toolbox, depending on the feature you need.

***

## Clipboard

### Clipboard Translate Feature

If translation is enabled, click **Translate** in the Clipboard to translate the current text. By default, Butler auto-detects the source language and translates to English. You can change both languages from the dropdowns next to **Translate**.

### Clipboard Transfer Feature

The Butler Clipboard is a temporary store for text. When you click **Save**, Butler keeps the text for one hour. Saving new text replaces the previous clipboard content. You can **Load** the saved text from either side, whether you started in your browser or in a Virtual Environment.

The example below moves text from a Virtual Environment to your desktop. Reverse the same steps to move text in the other direction.

{% stepper %}
{% step %}
**Open Butler**

Click the GML logo in the bottom-left corner, open the application menu, go to **Replica**, and click **Replica Butler**.
{% endstep %}

{% step %}
**Access Butler**

Butler opens in a browser tab. It does not display the Virtual Environment name.
{% endstep %}

{% step %}
**Save text**

Enter the text and click **Save**. A notification appears when the sync is complete.
{% endstep %}

{% step %}
**Load clipboard content**

Open the Clipboard from the Virtual Environment toolbox or from the Environments page, then click **Load** to retrieve the saved text.
{% endstep %}
{% endstepper %}

***

## Files

Butler lets you move files across the environments and enclaves you can access. This is useful when you need to download a file in one environment, hold it temporarily, and then move it into another environment, including one without direct network access.

### File Manager

The File Manager supports secure, two-way file transfer to and from Virtual Environments and Enclaves.

{% stepper %}
{% step %}
**Open the Butler File Manager**

* From your local Replica view, select the environment or enclave and click **Files**.
* From inside a Virtual Environment, open Butler and click **Files**.
  {% endstep %}

{% step %}
**Upload files**

Drag files into the upload area, or click the area to choose files manually.
{% endstep %}

{% step %}
**Notifications**

A notification appears when the upload finishes.
{% endstep %}

{% step %}
**Download files**

Click the download icon under **Actions** to download the file inside the Virtual Environment. To download it to your local computer, use the same file from the environment card on the **Environments** page.
{% endstep %}
{% endstepper %}

### File Transfer

{% stepper %}
{% step %}
**Start transfer**

Open **File Manager** on the source environment or enclave.
{% endstep %}

{% step %}
**Initiate transfer**

Click **Transfer**.
{% endstep %}

{% step %}
**Select destination**

Select the destination environment or enclave.
{% endstep %}

{% step %}
**Submit**

Click **Submit**.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Transferred files do not appear automatically on the destination Virtual Environment desktop. Download them from Butler File Manager inside the destination environment.
{% endhint %}

### Code Editor

The Code Editor lets you view and edit supported file types in the browser.

Supported file types currently include:

* Text (`.txt`)
* Script (`.sh`)
* Python (`.py`)
* JavaScript (`.js`)
* TypeScript (`.ts`)
* CSV (`.csv`)
* JSON (`.json`)
* YAML (`.yaml`)
* HTML (`.html`)
* SQL (`.sql`)
* PowerShell (`.ps`)
* XML (`.xml`)
* Cypher (`.cypher`)

{% stepper %}
{% step %}
**Select file**

Select a file with a clean AV status. Files that are pending scan or marked infected cannot be edited.
{% endstep %}

{% step %}
**Open editor**

Click the Code Editor icon.
{% endstep %}

{% step %}
**View and edit**

The Code Editor opens the file for review and editing.
{% endstep %}

{% step %}
**Save changes**

Make any needed changes, then click the **Save** icon.
{% endstep %}
{% endstepper %}

***

## Secure Enclaves

Butler Enclaves let you share files with users and groups while keeping control over how data moves. You can only create an enclave outside a Virtual Environment.

{% stepper %}
{% step %}
**Open Enclaves**

In Replica, click **Enclaves** in the left-hand sidebar.
{% endstep %}

{% step %}
**Enclave list**

The Enclaves page opens and lists the enclaves available to you.
{% endstep %}

{% step %}
**Create an Enclave**

Click **Create Enclave**, then enter:

* an enclave name
* an enclave type:
  * **Isolated**: Loads files into an environment once when the environment starts. Strictly isolated - a user must manually choose to update files.
  * **Synchronous**: Loads files when the environment starts and keeps them synced. Persistent, sharable storage — content is accessible in real time by any user or environment with access.
* an assignee for the enclave

Click **Submit** when finished.

{% hint style="info" %}
A valid enclave name is 3 to 20 characters long and can contain letters, numbers, hyphens, and underscores.
{% endhint %}
{% endstep %}

{% step %}
**Enclave File Manager**

Use **File Manager** to view, upload, and delete enclave files.

{% hint style="info" %}
An enclave file named `enclave.sh` runs automatically when the Virtual Environment starts. Use this for automated startup tasks.
{% endhint %}
{% endstep %}
{% endstepper %}

### Quick Create Environment with Enclave

To quickly create an environment from an enclave:

{% stepper %}
{% step %}
Click **Create Environment** on the enclave.
{% endstep %}

{% step %}
Click **Confirm**.

Replica creates a new environment with the same name and assignee as the enclave, using a preset configuration.
{% endstep %}
{% endstepper %}

***

## File Requests

File Requests let you collect files from people who do not have access to your Replica instance. To work with uploaded files, use the enclave's quick-create flow to launch an environment with that enclave attached.

### Invitations

Each File Request invitation is sent by email. The recipient uses the link in that email to upload files after completing two-factor authentication. You are copied on the invitation email, but you cannot use the link yourself because it is tied to the recipient's address and verification flow.

### File Request Permissions

When a File Request is enabled on an enclave, it restricts what different users can do with the files in that enclave.

#### Enclave Permissions

**File Request Creator**

| Description   | Status  |
| ------------- | ------- |
| File Upload   | Denied  |
| File Download | Denied  |
| File Delete   | Allowed |
| File Copy     | Denied  |
| File List     | Allowed |

**File Request Guest**

| Description   | Status  |
| ------------- | ------- |
| File Upload   | Allowed |
| File Download | Denied  |
| File Delete   | Denied  |
| File Copy     | Denied  |
| File List     | Denied  |

#### Environment Permissions

**Environment Files**

| Description   | Status                   |
| ------------- | ------------------------ |
| File Upload   | Host Allowed / VE Denied |
| File Download | Allowed                  |
| File Delete   | Allowed                  |
| File Copy     | Allowed                  |
| File List     | Allowed                  |

**Enclave Files**

| Description   | Status  |
| ------------- | ------- |
| File Upload   | Denied  |
| File Download | Allowed |
| File Delete   | Denied  |
| File Copy     | Denied  |
| File List     | Allowed |

### Create File Request

{% stepper %}
{% step %}
Click **Create File Request** on the enclave, enter a title and description, then click **Next**.
{% endstep %}

{% step %}
Enter the recipient email addresses. Add one address at a time by clicking **Add Email** after each entry.
{% endstep %}

{% step %}
When the list is complete, click **Submit** to send the request emails.
{% endstep %}
{% endstepper %}

### Edit File Request

{% stepper %}
{% step %}
Click **Edit File Request**, update the title or description if needed, and click **Next**.
{% endstep %}

{% step %}
To add email addresses, enter them and click **Add Email** after each one.

{% hint style="info" %}
Adding email addresses does not automatically send invitations. Use **Resend** to deliver them.
{% endhint %}
{% endstep %}

{% step %}
Turn on **Resend Mode** to resend invitations. Click **Resend** for a single address, or click **Send request to all emails** to resend them all.
{% endstep %}

{% step %}
Turn on **Delete Mode** to remove addresses from the request. Click **Delete** on the address you want to remove.
{% endstep %}
{% endstepper %}

***

## API Documentation

If you have API access, you can open the API documentation from Butler. Butler also includes Python and `curl` samples to help you start quickly.

***

## Jobs

Users with API access can manage Jobs from the **Jobs** link in the left-hand sidebar.

### View Jobs

Open **Jobs** in the left-hand sidebar to view scheduled jobs. To change a job, click **Edit** or **Delete** on that item.

### Create Job

To create a new job, go to **Environments**, click **Create Environment**, and select **Virtual Job**.

### Create or Edit Job

{% hint style="info" %}
Consider the resource impact of each new job. Jobs that run too often, such as every minute, can exhaust available capacity and block new Virtual Environment creation.
{% endhint %}

{% stepper %}
{% step %}
**Complete the Jobs Form**

* **Image**: The Virtual Environment image the job uses
* **Name**: The job name. Replica prepends `job-` to the Virtual Environment name.
* **Assignee**: The user or group assigned to the job
* **Egress**: Any egress assigned to you by your administrator
* **Enclave**: The enclave used for file transfer
* **Expires / Time-To-Live**: Job environments run for at least 5 minutes and at most 60 minutes
  {% endstep %}

{% step %}
**Save**

Click **Save** to create or update the job.
{% endstep %}
{% endstepper %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.replicacyber.com/user-guide/butler-user-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.