# Replica Documentation
Deploy secure isolated labs and workspaces in seconds — protected by our patented anonymous attack surface, enterprise observability, and comprehensive data controls.
{% columns %}
{% column valign="middle" %}
### Get started instantly
Deploy secure isolated labs and workspaces in seconds — protected by our patented anonymous attack surface, enterprise observability, and comprehensive data controls.
No guesswork, no complexity — just access to the tools and data you need.
User Guide
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
{% columns %}
{% column width="50%" %}
{% endcolumn %}
{% column width="50%" valign="middle" %}
### Learn about Replica's developer features
Read guides, watch tutorials, and learn more about working with Replica's developer features, APIs, and workflow automation with scheduled Jobs.
Developer GuideAPI Reference
{% endcolumn %}
{% endcolumns %}
Instant. Isolated. Frictionless.
Replica enables high-stakes operations with uncompromising security, seamless collaboration, and full compliance, protecting critical assets while ensuring complete control.
Cover image
Administration Guide
Learn how to configure the Replica platform so users get the most out of their experience.
# Introduction
{% embed url="" fullWidth="false" %}
Replica helps you deploy secure work environments quickly. It lets you stay productive while reducing exposure during online activity.
Replica is a SaaS web application. You can access it from any modern web browser. No special hardware or local software is required.
This guide covers the core features available to general users. Your organization may also provide training for workflows or customizations specific to your environment. Contact Replica if you need documentation for other roles, such as administrators.
{% hint style="info" %}
The features available to you depend on your permissions and your organization's subscription. Some features in this guide may not appear in your environment.
{% endhint %}
## Key Concepts
These concepts make the rest of the guide easier to follow.
**Virtual Environment**
Virtual Environments are the main workspace in Replica. You use them to access the internet and run the tools needed for your work.
**Attribution/Signature**
When you operate online, your browser, operating system, applications, ISP, and device expose details about you. Those details can be combined to track your activity. Replica helps manage those signals for you, providing an anonymous attack surface that protects your organization and identity.
**Profile**
Profiles control how a user appears from a Virtual Environment. When you assign a profile, Replica applies the related attribution settings automatically. You can reuse the same profile across multiple environments.
**Malware**
Some Virtual Environments support malware workflows. These may include reverse engineering, static analysis, dynamic analysis, execution, and long-term monitoring. Replica's file management features can also deliver files into the environment, including files that fail virus scanning.
**Jobs**
Jobs run Virtual Environments on a schedule with scripts or automated tasks. They appear in the Jobs view and are commonly used for repeatable workloads such as web scraping.
# Account
## Login
Open a web browser and go to the Replica URL provided by your administrator. Sign in with the credentials you were given.
On your first login, you may be asked to change your password, accept terms of use, or set up one-time passwords. This depends on your organization's settings.
{% hint style="danger" %}
For security reasons, you cannot bookmark the generic login page. If you want a bookmark, save the exact login URL from your administrator or bookmark the site after you sign in.
{% endhint %}
{% hint style="info" %}
Available features depend on your account permissions and your organization's Replica subscription. If you need additional access, contact your Replica administrator.
{% endhint %}
## Logout
To sign out, click your username in the top-right corner and select **Log out**. This ends your session and returns you to the login page.
## Manage Account
Use **Manage Account** to update basic account settings such as your name, email, and password. You can also reset your password or one-time password (OTP) authenticator. Every action requires re-authentication.
{% stepper %}
{% step %}
### Access Manage Account
In the top-right corner, click your username, then select **Manage Account**.
{% endstep %}
{% step %}
### Account Management page
The Account Management page opens. From here, you can perform basic account actions.
{% endstep %}
{% step %}
### Re-authenticate for actions
Every action on this page requires re-authentication because it changes account-level settings. When you select an action, a prompt appears and walks you through that step.
{% endstep %}
{% endstepper %}
## Change Password
Use **Change Password** to update your password. On your next login, use the new password.
{% stepper %}
{% step %}
### Open Change Password
After you select **Change Password** and re-authenticate, the password form opens.
{% endstep %}
{% step %}
### Submit and use new password
Submit the form to save your new password. Use that password the next time you sign in.
{% endstep %}
{% endstepper %}
## Reset OTP
Use **Reset OTP** to reset the one-time password method for the current user. After the reset, you must register a new authenticator device.
{% stepper %}
{% step %}
### Initiate Reset OTP
After you select **Reset OTP** and re-authenticate, you return to the Manage Account page and see the following prompt.
{% endstep %}
{% step %}
### Confirm Reset OTP
Click **Reset OTP** to continue. On your next login, enter your username and password as usual. Replica then takes you to the OTP setup page and shows the steps to register a new authenticator.
{% endstep %}
{% step %}
### Complete OTP setup
Complete the setup steps to finish sign-in and return to the application.
{% endstep %}
{% endstepper %}
# Virtual Environments
Virtual Environments (VEs) are secure, isolated, monitored workspaces for browsing, research, analysis, and other online tasks. This guide covers how to create, launch, manage, and extend them.
## Viewing Virtual Environments
After you sign in, the landing page shows the Virtual Environments you can access. If nothing appears on your first login, no environments have been assigned to you yet.
### Grid and List Views
The Virtual Environments page supports two display modes:
* **Grid View** *(default)*: Shows each environment as a card with status, egress, and actions.
* **List View**: Shows environments in a table with more detail.
### Virtual Environment Card Details
In **Grid View**, each card shows:
* **Status**: The current state, such as Running or Unavailable
* **Egress**: The egress router name, health percentage, and location
* **Zone**: The deployment zone the environment is hosted in, if applicable.
* **Last Accessed By**: The user who most recently launched or used the environment. If unused, this shows **Never Accessed**.
* **Last Accessed Date/Time**: The most recent access time. If unused, this shows **Never Used**.
### Exporting to CSV
In **List View**, click **Download CSV** in the toolbar to export the current environment data for auditing or bulk review.
## Creating a Virtual Environment
From the Virtual Environments page, click **Create Environment**. The creation form opens in a panel from the right side of the screen.
### Types of Virtual Environments
Choose the environment type that matches your task, then click **Next**.
* **Research**: Best for most users. Supports common workflows such as browsing, research, development, testing, and training.
* **Virtual Jobs**: Runs recurring automated workloads that do not need user interaction after creation. Common use cases include web scraping and scheduled data processing.
* **Malware**: Designed for malware analysis, reverse engineering, and execution of potentially harmful software in an environment built for that workflow.
### Environment Details
Complete the required fields, then click **Next**.
* **Name**: Choose a name that describes the work you plan to do. This name stays internal to your organization and is not exposed publicly.
* **Assignment**: Assign the environment to a user, group, or [profile](/user-guide/profiles). By default, the creator is the assignee. Any users in an assigned group can access the environment. Administrators always have access. If you assign a [profile](/user-guide/profiles), Replica inherits the profile's assignee and egress, and the **Egress Location** option disappears.
* **Base Image**: See [Base Images](#base-images). The base image determines the operating system, tools, and built-in features available in the environment.
### Environment Connectivity
Choose how the environment connects to the network, then click **Next**.
* **Egress**: Select a VPN hosted by Replica or a third-party provider. Each egress maps to a location on the **Egress Map** and determines where traffic exits to the internet. You can choose from the list or click a point directly on the map.
* **Private Route** *(optional)*: Connection to an additional network location for access to specialized services. See [#private-routes](#private-routes "mention")
* **Enclave** *(optional)*: Attach an enclave created through the [Butler User Guide](/user-guide/butler-user-guide#secure-enclaves).
* **Proxy** *(optional)*: Select a SOCKS proxy hosted by a third-party provider. This field only appears if your administrator has configured proxy servers.
* **Open Port** *(optional)*: Allows inbound or outbound network ports between Virtual Environments. To connect two environments, enable this option on both. This is only available for supported environment types and only when enabled by an administrator.
{% hint style="info" %}
**Malware environments** use a **Deployment Zone** step instead of standard egress selection. The deployment zone controls where the environment is hosted and where its traffic exits. Enclave attachment still appears in the Connectivity step.
{% endhint %}
### Open Port
Open Port is an advanced feature that enables you to make network connections between virtual environments.
To enable **Open Port**, complete one extra step:
* **Port Name**: A descriptive name such as `HTTP`
* **Port Number**: The port to open, such as `8080`
* **Protocol**: The traffic protocol. If you are unsure, start with `TCP`.
{% hint style="info" %}
For more information on using this feature, see [#connections-between-environments](#connections-between-environments "mention"). Open Port is an advanced feature that must be enabled by Replica support before use.
{% endhint %}
### Advanced Options
Select any optional features, then click **Next**. None of these are required.
* **Packet Capture** *(optional)*: Captures network traffic to and from the environment and stores it as PCAP for later analysis.
* **File Export** *(configurable)*: If [File Export](#file-export) is enabled by your administrator, this option exports files from the environment to external block storage such as MinIO or S3.
Click **Submit** to start provisioning. The new environment appears on the **Virtual Environments** page. Creation may take a few minutes, depending on the options selected.
## Quick Creating a Virtual Environment (Beta)
If [My View](/user-guide/my-view) is enabled, you can create a new Virtual Environment in two clicks. Click **Quick Create** in My View (accessible from the header toolbar).
Replica opens a shortened creation flow with preconfigured defaults based on your organization's settings. You can usually change the default egress and select an enclave if needed. Click **Submit** to create the environment.
## Cloning a Virtual Environment
To clone an existing environment, drag its card into the clone area on the Virtual Environments page. You can also click **Create Environment** in the clone area to open the standard wizard.
{% hint style="info" %}
Cloning creates a new Virtual Environment with the same configuration as the source environment.
{% endhint %}
## Using a Virtual Environment
To open an environment, click **Launch** on its card. The Virtual Environment interface opens in your browser.
{% hint style="warning" %}
Your browser may ask for permission to access copied text and images. Click **Allow** if you want copy and paste to work smoothly between your computer and the Virtual Environment.
{% endhint %}
{% hint style="info" %}
Some environments support multiple simultaneous users. When more than one user is connected, an indicator appears in the top-right corner. The first user to connect sets the environment resolution for everyone.
{% endhint %}
### Additional Launch Options
You can change how the environment opens by holding keyboard modifiers while clicking **Launch**.
* On **Mac**:
* Hold `shift` to open in a new window
* Hold `command` to open in a new tab
* Hold `shift` + `command` to open in the DCV Desktop Viewer
* On **PC**:
* Hold `shift` to open in a new window
* Hold `ctrl` to open in a new tab
* Hold `shift` + `ctrl` to open in the DCV Desktop Viewer
### Launching the Web Browser
The browser may open automatically. If it does not, click **Applications** in the bottom-left corner, open **Internet**, and select **Chromium Web Browser** or the browser supported by that image.
### Launching Other Applications
Virtual Environments provide a full desktop experience. Many images include tools beyond a web browser. The installed applications depend on the selected base image, and advanced users can install additional software when permitted.
To view installed applications, open the **Applications** menu in the lower-left corner of the environment.
## Overlay Toolbox
Every Virtual Environment includes a toolbox overlay. It provides quick access to common tools while you work.
To open the toolbox, click the toolbox icon on the right side of the Virtual Environment.
{% stepper %}
{% step %}
**Toolbox - Close**
Use the close icon to hide the toolbox.
{% endstep %}
{% step %}
**Toolbox - Files**
The Files icon shows files shared with the environment and lets you move files in or out. Drag a file from your computer into the dotted upload area to copy it into the Virtual Environment. See [File Transfer](#file-transfer) for details.
{% endstep %}
{% step %}
**Toolbox - Clipboard**
The Clipboard icon opens the shared clipboard between your computer and the environment. See [Clipboard](/user-guide/butler-user-guide#clipboard) for more details.
{% endstep %}
{% step %}
**Toolbox - Egress**
The Egress icon lets you switch the environment to a different egress location.
{% endstep %}
{% step %}
**Toolbox - SMS**
The SMS icon opens text messaging for phone numbers assigned to the user or environment. See [SMS Messaging](#sms-messaging) and [Phones](/user-guide/phones) for more detail.
{% endstep %}
{% step %}
**Toolbox - Credentials**
The Credentials icon displays the environment credentials used for privileged actions such as software installation or command-line administration.
{% endstep %}
{% endstepper %}
### File Transfer
Use **Files** to send files into a Virtual Environment or download files from it to your computer.
These files are stored through [Butler User Guide](/user-guide/butler-user-guide). From there, they can also be downloaded, transferred to other environments, or shared when permitted.
{% hint style="info" %}
Replica also supports file sharing between users, Secure Enclaves, and cross-environment file transfer. See [Butler User Guide](/user-guide/butler-user-guide) for the full workflow.
{% endhint %}
#### Upload
{% stepper %}
{% step %}
**Start Upload**
Open the toolbox and click **Files**.
{% endstep %}
{% step %}
**Select Files**
Click **Upload Files from Library** to choose a file from your computer, or drag a file into the dotted upload area.
{% endstep %}
{% step %}
**Post-Upload**
After upload, the file appears in the list. It may take a minute or two to complete antivirus scanning before download or editing is allowed. Refresh the file list to check status. If automated file transfer is enabled, the file may also appear on the environment desktop.
{% endstep %}
{% endstepper %}
#### Download
To download a file to your computer, click the download icon next to the file and choose a destination on your local system.
### Full Screen Mode & Keyboard Lock
Use the full screen button to switch the browser to full screen and lock special keys so they are passed directly to the Virtual Environment.
### Change Egress
Use **Egress** to change the network location used by the environment while it is running.
### Phones
If telephony is enabled and your administrator has assigned phone numbers to you, your group, or a profile, phone features are available from the main navigation and from the Virtual Environment overlay.
See [Phones](/user-guide/phones) for details on assignments, configuration, and call forwarding.
#### SMS Messaging
SMS supports both sending and receiving text messages. Click the SMS icon on the right side of the overlay to open the chat window. The dropdown at the top shows the numbers assigned to you. Use the **To** field to start a new conversation or reopen a previous one.
Messages remain available for review, including those received while you were not active in the system. If a new message arrives while you are using the environment, Replica shows a notification. Click the notification or the SMS icon to open the conversation.
You can view SMS and MMS messages, reply as needed, and open received images or video attachments at full size for download. You can also click individual messages to copy them to the clipboard.
#### Click to Call
From the [Phones](/user-guide/phones) page, you can configure a call forwarding number for supported numbers. Inbound calls to the Replica number are then forwarded automatically. Support varies by provider.
To place an outbound call through a Replica number, use **click to call** where available.
{% stepper %}
{% step %}
Select the number you want to call in the `To` field.
{% endstep %}
{% step %}
Click the phone icon.
{% endstep %}
{% step %}
Enter your callback number in the popup.
{% endstep %}
{% step %}
Enter the target phone number and click `Call`.
{% endstep %}
{% step %}
Replica calls your phone first.
{% endstep %}
{% step %}
Answer the call and Replica connects you to the target number.
{% endstep %}
{% step %}
The recipient sees the Replica phone number as the caller.
{% endstep %}
{% endstepper %}
### Credentials
Use the environment credentials for actions that require elevated privileges.
## Language Support
### Chinese
Replica supports Chinese input with pinyin. Two input methods are available:
* **iBus**: For Chinese input across the desktop, except inside the browser
* **Google Input Tools** *(Chromium extension)*: For Chinese input inside Chromium only
#### iBus Configuration
To adjust iBus settings, right-click the language icon in the bottom-right corner.
{% hint style="info" %}
The iBus icon changes based on the currently selected input language.
{% endhint %}
To enable Chinese input, click the icon and select **Chinese - Intelligent Pinyin**. To switch back, select **English - English (US)**.
#### Google Input Tools Configuration
The Chromium extension is not preconfigured and must be set up before use.
{% hint style="info" %}
The Google Input Tools extension icon appears in the top-right area of Chromium.
{% endhint %}
To configure it, click the extensions icon and select **Extension Options**.
On the language list page, find **Chinese (Simplified, China)** in the left column. Select it, then click the black arrow in the center to move it to the enabled list on the right.
Close the tab, then click the extension icon again and select Chinese as the active input language.
You can now use pinyin input in Chromium text fields.
## Snapshots
### Linux Virtual Environments
If your administrator has enabled Snapshots for Linux Virtual Environments, you can save browser state and later reuse it in another environment. Depending on configuration, the browser may begin storing cookies, bookmarks, extensions, browsing history, and related state after first use. That state contributes to the environment fingerprint. A snapshot preserves it for later reuse.
{% hint style="info" %}
These steps assume you are comfortable using the Linux command line.
{% endhint %}
{% hint style="info" %}
This feature only appears on supported Virtual Environments.
{% endhint %}
#### Capture
{% stepper %}
{% step %}
Open **Terminal** from **Applications** → **System Tools**.
{% endstep %}
{% step %}
Copy the command for the browser you are using from the table below.
{% endstep %}
{% step %}
Run the command and wait for the snapshot process to finish.
{% endstep %}
{% step %}
When the process completes, an archive named for the browser type and environment ID is created on the desktop.
{% endstep %}
{% step %}
Upload that archive to external storage such as [Files](/user-guide/butler-user-guide#files).
{% endstep %}
{% endstepper %}
| Browser | Command |
| -------- | --------------------------------------------------------------------- |
| Chromium | `. /opt/greymarketlabs/configs/chromium/chromium.sh && snapshot_save` |
| Firefox | `. /opt/greymarketlabs/configs/firefox/firefox.sh && snapshot_save` |
| Brave | `. /opt/greymarketlabs/configs/brave/brave.sh && snapshot_save` |
| Tor | `. /opt/greymarketlabs/configs/tor/tor.sh && snapshot_save` |
#### Restore
{% stepper %}
{% step %}
Download the snapshot archive from external storage.
{% endstep %}
{% step %}
Move the archive to the desktop.
{% endstep %}
{% step %}
Open **Terminal** from **Applications** → **System Tools**.
{% endstep %}
{% step %}
Copy the correct restore command from the table below.
{% endstep %}
{% step %}
Run the command and wait for the restore process to finish.
{% endstep %}
{% endstepper %}
| Browser | Command |
| -------- | ----------------------------------------------------------------------------------------------------------- |
| Chromium | `. /opt/greymarketlabs/configs/chromium/chromium.sh && snapshot_load /home/$USER/Desktop/chromium-*.tar.gz` |
| Firefox | `. /opt/greymarketlabs/configs/firefox/firefox.sh && snapshot_load /home/$USER/Desktop/firefox-*.tar.gz` |
| Brave | `. /opt/greymarketlabs/configs/brave/brave.sh && snapshot_load /home/$USER/Desktop/brave-*.tar.gz` |
| Tor | `. /opt/greymarketlabs/configs/tor/tor.sh && snapshot_load /home/$USER/Desktop/tor-*.tar.gz` |
### Windows Virtual Environments
If Snapshots are enabled for Windows Virtual Environments, some environments, such as malware testing images, may support them. A snapshot captures the current environment state so you can restore it later.
Open the **Actions** menu on the Virtual Environment and click **Manage Snapshots**. From that dialog, you can create, restore, edit, and delete snapshots.
Creating a snapshot starts a background job. The time required depends on how much data is stored in the environment.
Restoring a snapshot also starts a background job. The current state is replaced by the snapshot, and the environment restarts while the restore is applied.
## Credentials
Each Virtual Environment has its own credentials. Use them for advanced actions that require a password.
### Viewing Environment Credentials
From the Virtual Environments page, open the environment's **Actions** menu and click **View Credentials**. You can also open the same credentials from the toolbox through **Admin Credentials** while inside the environment.
{% hint style="success" %}
Click the **User Name** or **Password** field to copy it to the clipboard.
{% endhint %}
## Deleting a Virtual Environment
Deleting an environment permanently removes it.
To delete an environment, open its **Actions** menu and click **Delete**, then confirm the action.
## Stop/Start a Virtual Environment
Malware environments can be stopped and started.
To stop or start one, open its **Actions** menu and click **Stop Environment** or **Start Environment**, then confirm the action.
## Restarting a Virtual Environment
To restart an environment, open its **Actions** menu, click **Restart**, and confirm.
## Renaming a Virtual Environment
To rename an environment, open its **Actions** menu, click **Rename**, and enter the new name.
## Additional Details
To view more information about an environment, open its **Actions** menu and click **View Details**.
## Assigning a Virtual Environment
A Virtual Environment can be assigned to a user, group, or profile. Administrators can assign any environment. Standard users can assign only to themselves, to groups they belong to, or to users in those groups. By default, the creator is the assignee.
### Assignment on creation
During creation, you can assign the environment to a user, group, or profile. Assigning to a group grants access to all users in that group. If the environment is assigned to a profile, the user or group that owns the profile can access it.
### Reassignment
To change the assignee after creation, open the environment's **Actions** menu and click **Assign**.
The reassignment dialog lets you choose a new user, group, or profile.
{% hint style="danger" %}
If you assign the environment to a user other than yourself, to a group you do not belong to, or to a profile you are not assigned to, you may lose access.
{% endhint %}
## Base Images
Base images define the operating system, applications, and built-in features for a Virtual Environment.
### Viewing Image Details
Click any image card in the image catalog to open its details. The panel shows the image version, operating system, image type, and installed applications. Click close to dismiss it.
Your image catalog may include:
* Linux Firefox
* Linux Brave
* Linux Tor
* Linux Jupyter Notebooks
* Linux Selenium
* Windows Edge
{% hint style="info" %}
Available images depend on your organization's subscription and configuration. You may see fewer images than the examples listed here, and custom images may also be available.
{% endhint %}
### Linux Neo4j
To access Neo4j in a Linux Neo4j environment:
{% stepper %}
{% step %}
Open the applications menu and select **Open Neo4j** from the **Programming** category.
{% endstep %}
{% step %}
Connect to the Neo4j database.
{% endstep %}
{% endstepper %}
### Linux Jupyter Notebooks
To access Jupyter Notebooks in a Linux Jupyter Notebooks environment:
{% stepper %}
{% step %}
Open Jupyter Notebooks.
{% endstep %}
{% step %}
Jupyter launches in Firefox at .
{% endstep %}
{% step %}
The environment displays the shared notebooks.
{% endstep %}
{% endstepper %}
## File Export
{% hint style="info" %}
If you are not using File Export for out-of-band transfer, use [Files](/user-guide/butler-user-guide#files) in Butler to move data into or out of Virtual Environments.
{% endhint %}
If your administrator has configured **File Export**, you will see an additional option under **Advanced** during environment creation. You must enable it at creation time. After that, files saved in the **Sync** folder on the environment desktop can be exported to external storage such as MinIO or S3.
All exported data is encrypted in transit with SSL/TLS 1.2 or higher and encrypted at rest with AES-256. If S3 is used, AWS Server-Side Encryption S3 (`SSE-S3`) provides AES-256 encryption at rest.
### Exporting Data Walkthrough
{% stepper %}
{% step %}
Create a new Virtual Environment from the **Environments** page and enable **File Export** under **Advanced Options**. If this option does not appear, the image does not support File Export or it has not been configured.
{% endstep %}
{% step %}
Return to the **Environments** page. In the environment's **Actions** menu, look for **Export to S3**. The label says "S3" even if a different storage backend is configured.
{% endstep %}
{% step %}
Launch the Virtual Environment and download a file with the in-environment browser.
{% endstep %}
{% step %}
When saving the file, change the destination from **Downloads** to the **Sync** folder on the desktop.
{% endstep %}
{% step %}
Return to the **Environments** page, open the **Actions** menu for that environment, and click **Export to S3**.
{% endstep %}
{% step %}
Confirm the export. A success notification appears in the top-right corner.
{% endstep %}
{% endstepper %}
### Viewing Exported Data
{% hint style="warning" %}
This section is intended for advanced users or administrators with access to the AWS S3 console.
{% endhint %}
{% stepper %}
{% step %}
If your deployment uses AWS S3 and you have direct bucket access, locate the export bucket using the prefix configured by your administrator followed by `-exports-` and your user ID. If you do not have direct access, contact your administrator.
{% endstep %}
{% step %}
Open the bucket and locate the folder named for the Virtual Environment ID and export timestamp. Timestamps use the format `mm-dd-yyyy-hh:mm:ss`.
{% endstep %}
{% step %}
Open the most recent export folder and confirm that the file from the environment is present.
{% endstep %}
{% endstepper %}
## Advanced Virtual Environment Networking
### Private Routes
Private Routes are a Replica feature that enables your environment to connect to network locations which are not on the public Internet. If you have private routes available to you, you can select them when you create your environment.
For private routes to be available, it must be configured and enabled by your administrator.
{% hint style="info" %}
Private Routes are available on container-type Virtual Environments
{% endhint %}
### Connections Between Environments
Replica provides several features to enable network connections to be made between Virtual Environments. For instance, you can run a web server on one of your virtual environments, and enable it to be accessed locally from other virtual environments. These features vary depending on the type of environment you are using.
#### Container-Type Virtual Environments
Use the [Open Port](#open-port) feature when you create each environment. This feature affects enables both inbound and outbound traffic on the selected port. Use this option for each environment you wish to allow traffic for. You can connect to any other Virtual Environments of this type using the local IP address.
Standard Virtual Environments with any Open Ports are isolated from all other environments.
The Open Port feature is not available by default. To enable this feature, reach out to Replica support.
{% hint style="info" %}
To connect between Virtual Environments with an open port, you can use the IP address of the environment you want to connect to. To get the IP address, run `ifconfig eth0 | awk '/inet / {print $2}'` on the target environment.
{% endhint %}
#### Malware Environments
Malware environments within a zone share a local network by default. You can connect to any other Malware environment in the same zone using the local IP address.
{% hint style="info" %}
You may also need to permit traffic through the operating system's default firewall within your environment, if applicable.
{% endhint %}
#### Other Environments (Cloud Zone)
Connections directly between environments which are hosted in third-party cloud zones are not currently available.
## Hardware Virtual Environments
Hardware Virtual Environments connect physical devices to the Replica platform. They launch and operate like other Virtual Environments, but available features may differ because of hardware-specific limitations.
These environments require special configuration and can only be created or deleted by an administrator. Some standard features, such as Butler file transfer, may not be available.
To check whether an environment is hardware-backed, open **View Details** and review the Environment ID. Hardware Virtual Environments use IDs that begin with `hw`.
Administrators can find additional details in the administrator documentation.
# My View
The *My View* dashboard gives you a simplified view of the resources assigned to you. It also provides a fast path for creating new environments.
To open My View, click **My View** in the top header on any Replica page.
## Environments
The **Environments** section lists all environments assigned to you. Use **Quick Create** to select from available templates or create a fully customized environment.
## Storage Enclaves
The **Storage Enclaves** section lists all storage enclaves assigned to you, either directly or through a group. Use the **Create Storage** button to create a new storage enclave.
## Notifications
Use the bell icon in the top toolbar to open the **Notifications** panel. The dropdown shows recent notifications and a badge with the number of unread items.
# 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 storage enclaves.
* **Automation support**: Works with Storage 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 storage 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 Storage Enclaves.
{% stepper %}
{% step %}
**Open the Butler File Manager**
* From your local Replica view, select the environment or storage enclave and click **Files**.
* From inside a Virtual Environment, open Butler and click **Files**.
{% endstep %}
{% step %}
**Upload files**
Drag files anywhere into the browser window, 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 storage enclave.
{% endstep %}
{% step %}
**Initiate transfer**
Click **Transfer**.
{% endstep %}
{% step %}
**Select destination**
Select the destination environment or storage 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 Storage Enclaves
Butler Storage Enclaves let you share files with users and groups while keeping control over how data moves. You can only create an storage enclave outside a Virtual Environment.
{% stepper %}
{% step %}
**Open Storage Enclaves**
In Replica, click Storage **Enclaves** in the left-hand sidebar.
{% endstep %}
{% step %}
**Storage Enclave list**
The Storage Enclaves page opens and lists the storage enclaves available to you.
{% endstep %}
{% step %}
**Create an Storage Enclave**
Click **Create Storage**, then enter:
* an storage enclave name
* an storage 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 storage enclave
Click **Submit** when finished.
{% hint style="info" %}
A valid storage enclave name is 3 to 20 characters long and can contain letters, numbers, hyphens, and underscores.
{% endhint %}
{% endstep %}
{% step %}
**Storage Enclave File Manager**
Use **File Manager** to view, upload, and delete storage enclave files.
{% hint style="info" %}
An storage 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 Storage Enclave
To quickly create an environment from an storage enclave:
{% stepper %}
{% step %}
Click **Create Environment** on the storage enclave.
{% endstep %}
{% step %}
Click **Confirm**.
Replica creates a new environment with the same name and assignee as the storage 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 storage enclave's quick-create flow to launch an environment with that storage 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 storage enclave, it restricts what different users can do with the files in that storage enclave.
#### Storage 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 |
**Storage 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 storage 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
* **Storage Enclave**: The storage 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 %}
# Profiles
## Profiles Introduction
Profiles control how a Virtual Environment appears to external services. Like a standard environment, a profile can define an egress and language settings that shape attribution. If you select a profile during environment creation, Replica uses the profile's egress automatically.
Profiles also record activity in a shared history. This can include profile creation, environment connections, recordings, notes, and screenshots. The history helps you maintain a consistent profile over time, even across multiple operators.
Profiles are assigned to a user or group. By default, the profile is assigned to the person who creates it. You can change that later from the profile details page. Any Virtual Environment created with that profile inherits the profile assignment and egress.
Profiles also provide an in-environment overlay with helpful context such as name, time, weather, and news, along with tools like notes, broadcast chat, and SMS messaging.
## Create a Profile
{% stepper %}
{% step %}
#### Open the New Profile page
On the **Profiles** page, click **Create** in the upper-right corner.
{% endstep %}
{% step %}
#### Enter profile details and create
Enter the profile details, then click **Create New Profile**.
* **Name**: The identity name you want to emulate.
* **Egress Name**: The VPN used by the profile. You can choose from the egresses assigned to you by your administrator. **Egress Location** shows where traffic exits to the internet.
* **Profile Picture** *(optional)*: An image representing the identity. One option for anonymous generated images is [thispersondoesnotexist.com](https://www.thispersondoesnotexist.com/).
* **Description**: A short summary of the persona. Describe who they are and what they do.
{% endstep %}
{% endstepper %}
## Managing Profiles
### Viewing Profiles
Open **Profiles** from the left-hand menu to see all available profiles. Click **Details** on a profile card to open the profile details panel.
### Viewing Profile Details
The profile details page shows the egress, profile description, and activity history. If the profile is not yet associated with a Virtual Environment, the history only shows the profile creation event.
### Viewing Profile Activity History
Once you associate a profile with a Virtual Environment and begin using it, more events appear in the history. If playback is enabled, session recordings are included and can support auditing or knowledge transfer.
### Assigning Profiles
To assign the profile to a different user or group, click the edit button in the **Assignee** section.
### Deleting Profiles
To delete a profile, click **Delete Profile** on the profile card, then confirm the action.
## Associating a Virtual Environment with a Profile
{% stepper %}
{% step %}
#### Create a Virtual Environment with the profile
Create a new Virtual Environment and select the profile you just created. When you choose a profile, the egress location option disappears because the profile controls those settings.
{% endstep %}
{% step %}
#### Verify association
After the environment starts, confirm the profile association from the profile column and location details.
{% endstep %}
{% endstepper %}
# Phones
## Phones Introduction
Replica supports two phone offerings:
* **Physical Phones**: An optional add-on that provides one or more real Android phones you can control from Replica.
* **Virtual Phones**: Software-based calling and messaging features tied to assigned phone numbers.
Use the sections below to understand which workflow applies to your setup.
{% hint style="info" %}
Phone features depend on your organization's subscription and configuration.
{% endhint %}
## Physical Phones
Physical Phones are an optional add-on. They add one or more real Android phones to the platform so you can control them from Replica.
Physical Phones are made available through a special enclave provided for that purpose.
### Launch a Physical Phone
To launch a Physical Phone, create a Virtual Environment and complete both of these connectivity steps:
* Attach the phone enclave.
* Add the `phone network` private route.
After the environment is ready, launch it to access the attached physical device.
## Virtual Phones
Virtual Phones extend Virtual Environments and Profiles with calling and messaging features. They are commonly used for workflows such as two-factor authentication.
To get phone numbers assigned, contact your administrator. Manage assigned numbers from the **Phones** section. Use them inside a Virtual Environment from the `SMS` icon in the overlay. For usage details, see [SMS Messaging](/user-guide/virtual-environments#sms-messaging).
### View Virtual Phone Numbers
Open **Phones** from the left-hand menu to see the phone numbers available to you.
You will see cards for numbers assigned to you directly or indirectly through a profile or group.
* **Provider**: The Software Defined Telephony (SDT) provider, such as Twilio or Bandwidth, or an SMS Device. **SMS Device** means the number is tied to a physical device.
* **Number**: The phone number in international `E.164` format.
* **Name**: A label that identifies the number's purpose.
* **Number Is**: Shows whether the number is active.
* **Call Forwarding No.**: *(Optional, Twilio only)* Inbound calls to **Number** are forwarded to this number. The caller does not see the forwarding destination. If this field is empty, inbound calls to **Number** return a busy tone. If you call the Replica number from the configured forwarding number, a service answers and prompts you for the number to dial. The outbound call then appears to come from **Number**, not the forwarding number.
* **Assignee**: The assigned user, group, or profile. In environments assigned to a profile, you can access numbers assigned to that profile while using that environment. In all other environments, you can access numbers assigned directly to you or through a group.
* **Is Use As Relay**: *(Administrator feature)* Shows whether an SDT provider number is acting as a relay for an SMS Device and which numbers it supports.
# Troubleshooter Portal
The Replica Troubleshooter Portal is a standalone diagnostic tool. It checks whether your system and network are set up for a reliable Replica experience. The portal runs a series of browser-based pre-flight checks and reports the results. If anything looks unexpected, take a screenshot of the results page and contact Replica Support.
## Accessing the Troubleshooter
Click **Diagnose** at the bottom of the left-hand navigation sidebar to open the Troubleshooter Portal.
## Diagnostic Checks
The Troubleshooter runs the following checks:
* **Ping** — Measures round-trip latency to the Replica platform. High latency can reduce session responsiveness.
* **Jitter** — Measures variation in ping time. High jitter can make Virtual Environment sessions unstable.
* **Clipboard Access** — Verifies that your browser allows clipboard access. If access is denied, copy and paste between your computer and a Virtual Environment will not work.
* **WebSockets** — Confirms that WebSocket connections are available. Replica requires this for Virtual Environment sessions.
* **Download Speed** — Measures network throughput. Higher speeds improve the experience, especially at higher resolutions.
* **IP Info** — Shows your public IP address and geolocation. Use this to confirm you are connecting from the expected network.
* **IP Database Traits** — Checks classifications associated with your IP address that may affect connectivity to a Virtual Environment.
* **Browser Capabilities** — Verifies support for cookies, WebGL, WebAssembly, local storage, and other features Replica may require.
# Tutorials
This section covers common tasks in Replica.
## Installing software
You can install additional software in Replica environments as needed. Use any compatible application that fits your workflow. If you need help choosing a tool, contact Replica Support. Make sure you have the correct license for any software you install.
{% hint style="info" %}
Replica environments support many applications, but Replica does not test every third-party tool. Support for third-party software usually comes from the software vendor.
{% endhint %}
### Installing software in Windows environments
Windows environments include **Chocolatey GUI** in the Start menu for easy application installs. You can also install Windows applications downloaded from the internet in the usual way.
If you are prompted for a password, use the environment credentials. See [Credentials](/user-guide/virtual-environments#credentials).
### Installing software in Linux environments
Linux environments support additional software installation through the `APT` package manager.
When installing applications, you usually need superuser privileges. Use `sudo`, for example:
{% code title="Example" %}
```bash
sudo apt install
```
{% endcode %}
When prompted for a password, use the password shown under **Actions** → **View Credentials** on the Virtual Environments page. See [Credentials](/user-guide/virtual-environments#credentials).
Replica does not necessarily test or approve third-party packages available through `APT`.
See also: [Ubuntu APT documentation](https://help.ubuntu.com/community/AptGet/Howto)
## Gaining access to sites
Website access depends on more than just IP address. Many sites filter traffic based on the perceived attribution of the system connecting to them. Different sites look at different signals, and they rarely disclose exactly what they use.
Common attribution signals include IP address, ISP, user agent, browser fingerprint, operating system, screen resolution, browser configuration, software versions, installed fonts, and languages.
In the past, some users tried to spoof these values. That approach is now easier to detect because modern filtering systems can spot unrealistic combinations.
The most effective approach is to use the most realistic connection possible. That is the model Replica is designed to support.
### CAPTCHAs
CAPTCHAs are tests sites use to separate human traffic from automated or suspicious traffic. Some sites show them to everyone. Others only show them when attribution signals match patterns they distrust. CAPTCHAs often appear when a connection looks unrealistic.
If you keep seeing CAPTCHAs, try the following:
{% stepper %}
{% step %}
### Avoid spoofing or anonymizing tools
Do not use extensions or tools that spoof or mask attribution signals. Fake signals are easy to detect.
{% endstep %}
{% step %}
### Try a different egress location
Try another egress location. Some sites distrust traffic from specific networks. Switching networks can improve access. For example, Tor exits often trigger CAPTCHAs.
{% endstep %}
{% step %}
### Ensure realistic browsing behavior for automation
If you use automation for browsing or scraping, keep request rates realistic for normal human behavior.
{% endstep %}
{% endstepper %}
If CAPTCHAs continue, contact Replica Support for additional options.
# Introduction
{% embed url="" fullWidth="false" %}
Replica helps you deploy secure work environments quickly. It lets you stay productive while reducing exposure during online activity.
Replica is a SaaS web application. You can access it from any modern web browser. No special hardware or local software is required.
This guide covers the core features available to general users. Your organization may also provide training for workflows or customizations specific to your environment. Contact Replica if you need documentation for other roles, such as administrators.
{% hint style="info" %}
The features available to you depend on your permissions and your organization's subscription. Some features in this guide may not appear in your environment.
{% endhint %}
## Key Concepts
These concepts make the rest of the guide easier to follow.
**Virtual Environment**
Virtual Environments are the main workspace in Replica. You use them to access the internet and run the tools needed for your work.
**Attribution/Signature**
When you operate online, your browser, operating system, applications, ISP, and device expose details about you. Those details can be combined to track your activity. Replica helps manage those signals for you, providing an anonymous attack surface that protects your organization and identity.
**Profile**
Profiles control how a user appears from a Virtual Environment. When you assign a profile, Replica applies the related attribution settings automatically. You can reuse the same profile across multiple environments.
**Malware**
Some Virtual Environments support malware workflows. These may include reverse engineering, static analysis, dynamic analysis, execution, and long-term monitoring. Replica's file management features can also deliver files into the environment, including files that fail virus scanning.
**Jobs**
Jobs run Virtual Environments on a schedule with scripts or automated tasks. They appear in the Jobs view and are commonly used for repeatable workloads such as web scraping.
# Account
## Login
Open a web browser and go to the Replica URL provided by your administrator. Sign in with the credentials you were given.
On your first login, you may be asked to change your password, accept terms of use, or set up one-time passwords. This depends on your organization's settings.
{% hint style="danger" %}
For security reasons, you cannot bookmark the generic login page. If you want a bookmark, save the exact login URL from your administrator or bookmark the site after you sign in.
{% endhint %}
{% hint style="info" %}
Available features depend on your account permissions and your organization's Replica subscription. If you need additional access, contact your Replica administrator.
{% endhint %}
## Logout
To sign out, click your username in the top-right corner and select **Log out**. This ends your session and returns you to the login page.
## Manage Account
Use **Manage Account** to update basic account settings such as your name, email, and password. You can also reset your password or one-time password (OTP) authenticator. Every action requires re-authentication.
{% stepper %}
{% step %}
### Access Manage Account
In the top-right corner, click your username, then select **Manage Account**.
{% endstep %}
{% step %}
### Account Management page
The Account Management page opens. From here, you can perform basic account actions.
{% endstep %}
{% step %}
### Re-authenticate for actions
Every action on this page requires re-authentication because it changes account-level settings. When you select an action, a prompt appears and walks you through that step.
{% endstep %}
{% endstepper %}
## Change Password
Use **Change Password** to update your password. On your next login, use the new password.
{% stepper %}
{% step %}
### Open Change Password
After you select **Change Password** and re-authenticate, the password form opens.
{% endstep %}
{% step %}
### Submit and use new password
Submit the form to save your new password. Use that password the next time you sign in.
{% endstep %}
{% endstepper %}
## Reset OTP
Use **Reset OTP** to reset the one-time password method for the current user. After the reset, you must register a new authenticator device.
{% stepper %}
{% step %}
### Initiate Reset OTP
After you select **Reset OTP** and re-authenticate, you return to the Manage Account page and see the following prompt.
{% endstep %}
{% step %}
### Confirm Reset OTP
Click **Reset OTP** to continue. On your next login, enter your username and password as usual. Replica then takes you to the OTP setup page and shows the steps to register a new authenticator.
{% endstep %}
{% step %}
### Complete OTP setup
Complete the setup steps to finish sign-in and return to the application.
{% endstep %}
{% endstepper %}
# Virtual Environments
Virtual Environments (VEs) are secure, isolated, monitored workspaces for browsing, research, analysis, and other online tasks. This guide covers how to create, launch, manage, and extend them.
## Viewing Virtual Environments
After you sign in, the landing page shows the Virtual Environments you can access. If nothing appears on your first login, no environments have been assigned to you yet.
### Grid and List Views
The Virtual Environments page supports two display modes:
* **Grid View** *(default)*: Shows each environment as a card with status, egress, and actions.
* **List View**: Shows environments in a table with more detail.
### Virtual Environment Card Details
In **Grid View**, each card shows:
* **Status**: The current state, such as Running or Unavailable
* **Egress**: The egress router name, health percentage, and location
* **Zone**: The deployment zone the environment is hosted in, if applicable.
* **Last Accessed By**: The user who most recently launched or used the environment. If unused, this shows **Never Accessed**.
* **Last Accessed Date/Time**: The most recent access time. If unused, this shows **Never Used**.
### Exporting to CSV
In **List View**, click **Download CSV** in the toolbar to export the current environment data for auditing or bulk review.
## Creating a Virtual Environment
From the Virtual Environments page, click **Create Environment**. The creation form opens in a panel from the right side of the screen.
### Types of Virtual Environments
Choose the environment type that matches your task, then click **Next**.
* **Research**: Best for most users. Supports common workflows such as browsing, research, development, testing, and training.
* **Virtual Jobs**: Runs recurring automated workloads that do not need user interaction after creation. Common use cases include web scraping and scheduled data processing.
* **Malware**: Designed for malware analysis, reverse engineering, and execution of potentially harmful software in an environment built for that workflow.
### Environment Details
Complete the required fields, then click **Next**.
* **Name**: Choose a name that describes the work you plan to do. This name stays internal to your organization and is not exposed publicly.
* **Assignment**: Assign the environment to a user, group, or [profile](/user-guide/4.4-user-guide/profiles). By default, the creator is the assignee. Any users in an assigned group can access the environment. Administrators always have access. If you assign a [profile](/user-guide/4.4-user-guide/profiles), Replica inherits the profile's assignee and egress, and the **Egress Location** option disappears.
* **Base Image**: See [Base Images](#base-images). The base image determines the operating system, tools, and built-in features available in the environment.
### Environment Connectivity
Choose how the environment connects to the network, then click **Next**.
* **Egress**: Select a VPN hosted by Replica or a third-party provider. Each egress maps to a location on the **Egress Map** and determines where traffic exits to the internet. You can choose from the list or click a point directly on the map.
* **Enclave** *(optional)*: Attach an enclave created through the [Butler User Guide](/user-guide/4.4-user-guide/butler-user-guide#secure-enclaves).
* **Proxy** *(optional)*: Select a SOCKS proxy hosted by a third-party provider. This field only appears if your administrator has configured proxy servers.
* **Open Port** *(optional)*: Allows inbound or outbound network ports between Virtual Environments. To connect two environments, enable this option on both. This is only available for supported environment types and only when enabled by an administrator.
{% hint style="info" %}
**Malware environments** use a **Deployment Zone** step instead of standard egress selection. The deployment zone controls where the environment is hosted and where its traffic exits. Enclave attachment still appears in the Connectivity step.
{% endhint %}
### Open Port
If you enable **Open Port**, complete one extra step:
* **Port Name**: A descriptive name such as `HTTP`
* **Port Number**: The port to open, such as `8080`
* **Protocol**: The traffic protocol. If you are unsure, start with `TCP`.
### Advanced Options
Select any optional features, then click **Next**. None of these are required.
* **Packet Capture** *(optional)*: Captures network traffic to and from the environment and stores it as PCAP for later analysis.
* **File Export** *(configurable)*: If [File Export](#file-export) is enabled by your administrator, this option exports files from the environment to external block storage such as MinIO or S3.
Click **Submit** to start provisioning. The new environment appears on the **Virtual Environments** page. Creation may take a few minutes, depending on the options selected.
## Quick Creating a Virtual Environment (Beta)
If [My View](/user-guide/4.4-user-guide/my-view) is enabled, you can create a new Virtual Environment in two clicks. Click **Quick Create** in My View (accessible from the header toolbar).
Replica opens a shortened creation flow with preconfigured defaults based on your organization's settings. You can usually change the default egress and select an enclave if needed. Click **Submit** to create the environment.
## Cloning a Virtual Environment
To clone an existing environment, drag its card into the clone area on the Virtual Environments page. You can also click **Create Environment** in the clone area to open the standard wizard.
{% hint style="info" %}
Cloning creates a new Virtual Environment with the same configuration as the source environment.
{% endhint %}
## Using a Virtual Environment
To open an environment, click **Launch** on its card. The Virtual Environment interface opens in your browser.
{% hint style="warning" %}
Your browser may ask for permission to access copied text and images. Click **Allow** if you want copy and paste to work smoothly between your computer and the Virtual Environment.
{% endhint %}
{% hint style="info" %}
Some environments support multiple simultaneous users. When more than one user is connected, an indicator appears in the top-right corner. The first user to connect sets the environment resolution for everyone.
{% endhint %}
### Additional Launch Options
You can change how the environment opens by holding keyboard modifiers while clicking **Launch**.
* On **Mac**:
* Hold `shift` to open in a new window
* Hold `command` to open in a new tab
* Hold `shift` + `command` to open in the DCV Desktop Viewer
* On **PC**:
* Hold `shift` to open in a new window
* Hold `ctrl` to open in a new tab
* Hold `shift` + `ctrl` to open in the DCV Desktop Viewer
### Launching the Web Browser
The browser may open automatically. If it does not, click **Applications** in the bottom-left corner, open **Internet**, and select **Chromium Web Browser** or the browser supported by that image.
### Launching Other Applications
Virtual Environments provide a full desktop experience. Many images include tools beyond a web browser. The installed applications depend on the selected base image, and advanced users can install additional software when permitted.
To view installed applications, open the **Applications** menu in the lower-left corner of the environment.
## Overlay Toolbox
Every Virtual Environment includes a toolbox overlay. It provides quick access to common tools while you work.
To open the toolbox, click the toolbox icon on the right side of the Virtual Environment.
{% stepper %}
{% step %}
**Toolbox - Close**
Use the close icon to hide the toolbox.
{% endstep %}
{% step %}
**Toolbox - Files**
The Files icon shows files shared with the environment and lets you move files in or out. Drag a file from your computer into the dotted upload area to copy it into the Virtual Environment. See [File Transfer](#file-transfer) for details.
{% endstep %}
{% step %}
**Toolbox - Clipboard**
The Clipboard icon opens the shared clipboard between your computer and the environment. See [Clipboard](/user-guide/4.4-user-guide/butler-user-guide#clipboard) for more details.
{% endstep %}
{% step %}
**Toolbox - Egress**
The Egress icon lets you switch the environment to a different egress location.
{% endstep %}
{% step %}
**Toolbox - SMS**
The SMS icon opens text messaging for phone numbers assigned to the user or environment. See [SMS Messaging](#sms-messaging) and [Phones](/user-guide/4.4-user-guide/phones) for more detail.
{% endstep %}
{% step %}
**Toolbox - Credentials**
The Credentials icon displays the environment credentials used for privileged actions such as software installation or command-line administration.
{% endstep %}
{% endstepper %}
### File Transfer
Use **Files** to send files into a Virtual Environment or download files from it to your computer.
These files are stored through [Butler User Guide](/user-guide/4.4-user-guide/butler-user-guide). From there, they can also be downloaded, transferred to other environments, or shared when permitted.
{% hint style="info" %}
Replica also supports file sharing between users, Secure Enclaves, and cross-environment file transfer. See [Butler User Guide](/user-guide/4.4-user-guide/butler-user-guide) for the full workflow.
{% endhint %}
#### Upload
{% stepper %}
{% step %}
**Start Upload**
Open the toolbox and click **Files**.
{% endstep %}
{% step %}
**Select Files**
Click **Upload Files from Library** to choose a file from your computer, or drag a file into the dotted upload area.
{% endstep %}
{% step %}
**Post-Upload**
After upload, the file appears in the list. It may take a minute or two to complete antivirus scanning before download or editing is allowed. Refresh the file list to check status. If automated file transfer is enabled, the file may also appear on the environment desktop.
{% endstep %}
{% endstepper %}
#### Download
To download a file to your computer, click the download icon next to the file and choose a destination on your local system.
### Full Screen Mode & Keyboard Lock
Use the full screen button to switch the browser to full screen and lock special keys so they are passed directly to the Virtual Environment.
### Change Egress
Use **Egress** to change the network location used by the environment while it is running.
### Phones
If telephony is enabled and your administrator has assigned phone numbers to you, your group, or a profile, phone features are available from the main navigation and from the Virtual Environment overlay.
See [Phones](/user-guide/4.4-user-guide/phones) for details on assignments, configuration, and call forwarding.
#### SMS Messaging
SMS supports both sending and receiving text messages. Click the SMS icon on the right side of the overlay to open the chat window. The dropdown at the top shows the numbers assigned to you. Use the **To** field to start a new conversation or reopen a previous one.
Messages remain available for review, including those received while you were not active in the system. If a new message arrives while you are using the environment, Replica shows a notification. Click the notification or the SMS icon to open the conversation.
You can view SMS and MMS messages, reply as needed, and open received images or video attachments at full size for download. You can also click individual messages to copy them to the clipboard.
#### Click to Call
From the [Phones](/user-guide/4.4-user-guide/phones) page, you can configure a call forwarding number for supported numbers. Inbound calls to the Replica number are then forwarded automatically. Support varies by provider.
To place an outbound call through a Replica number, use **click to call** where available.
{% stepper %}
{% step %}
Select the number you want to call in the `To` field.
{% endstep %}
{% step %}
Click the phone icon.
{% endstep %}
{% step %}
Enter your callback number in the popup.
{% endstep %}
{% step %}
Enter the target phone number and click `Call`.
{% endstep %}
{% step %}
Replica calls your phone first.
{% endstep %}
{% step %}
Answer the call and Replica connects you to the target number.
{% endstep %}
{% step %}
The recipient sees the Replica phone number as the caller.
{% endstep %}
{% endstepper %}
### Credentials
Use the environment credentials for actions that require elevated privileges.
## Language Support
### Chinese
Replica supports Chinese input with pinyin. Two input methods are available:
* **iBus**: For Chinese input across the desktop, except inside the browser
* **Google Input Tools** *(Chromium extension)*: For Chinese input inside Chromium only
#### iBus Configuration
To adjust iBus settings, right-click the language icon in the bottom-right corner.
{% hint style="info" %}
The iBus icon changes based on the currently selected input language.
{% endhint %}
To enable Chinese input, click the icon and select **Chinese - Intelligent Pinyin**. To switch back, select **English - English (US)**.
#### Google Input Tools Configuration
The Chromium extension is not preconfigured and must be set up before use.
{% hint style="info" %}
The Google Input Tools extension icon appears in the top-right area of Chromium.
{% endhint %}
To configure it, click the extensions icon and select **Extension Options**.
On the language list page, find **Chinese (Simplified, China)** in the left column. Select it, then click the black arrow in the center to move it to the enabled list on the right.
Close the tab, then click the extension icon again and select Chinese as the active input language.
You can now use pinyin input in Chromium text fields.
## Snapshots
### Linux Virtual Environments
If your administrator has enabled Snapshots for Linux Virtual Environments, you can save browser state and later reuse it in another environment. Depending on configuration, the browser may begin storing cookies, bookmarks, extensions, browsing history, and related state after first use. That state contributes to the environment fingerprint. A snapshot preserves it for later reuse.
{% hint style="info" %}
These steps assume you are comfortable using the Linux command line.
{% endhint %}
{% hint style="info" %}
This feature only appears on supported Virtual Environments.
{% endhint %}
#### Capture
{% stepper %}
{% step %}
Open **Terminal** from **Applications** → **System Tools**.
{% endstep %}
{% step %}
Copy the command for the browser you are using from the table below.
{% endstep %}
{% step %}
Run the command and wait for the snapshot process to finish.
{% endstep %}
{% step %}
When the process completes, an archive named for the browser type and environment ID is created on the desktop.
{% endstep %}
{% step %}
Upload that archive to external storage such as [Files](/user-guide/4.4-user-guide/butler-user-guide#files).
{% endstep %}
{% endstepper %}
| Browser | Command |
| -------- | --------------------------------------------------------------------- |
| Chromium | `. /opt/greymarketlabs/configs/chromium/chromium.sh && snapshot_save` |
| Firefox | `. /opt/greymarketlabs/configs/firefox/firefox.sh && snapshot_save` |
| Brave | `. /opt/greymarketlabs/configs/brave/brave.sh && snapshot_save` |
| Tor | `. /opt/greymarketlabs/configs/tor/tor.sh && snapshot_save` |
#### Restore
{% stepper %}
{% step %}
Download the snapshot archive from external storage.
{% endstep %}
{% step %}
Move the archive to the desktop.
{% endstep %}
{% step %}
Open **Terminal** from **Applications** → **System Tools**.
{% endstep %}
{% step %}
Copy the correct restore command from the table below.
{% endstep %}
{% step %}
Run the command and wait for the restore process to finish.
{% endstep %}
{% endstepper %}
| Browser | Command |
| -------- | ----------------------------------------------------------------------------------------------------------- |
| Chromium | `. /opt/greymarketlabs/configs/chromium/chromium.sh && snapshot_load /home/$USER/Desktop/chromium-*.tar.gz` |
| Firefox | `. /opt/greymarketlabs/configs/firefox/firefox.sh && snapshot_load /home/$USER/Desktop/firefox-*.tar.gz` |
| Brave | `. /opt/greymarketlabs/configs/brave/brave.sh && snapshot_load /home/$USER/Desktop/brave-*.tar.gz` |
| Tor | `. /opt/greymarketlabs/configs/tor/tor.sh && snapshot_load /home/$USER/Desktop/tor-*.tar.gz` |
### Windows Virtual Environments
If Snapshots are enabled for Windows Virtual Environments, some environments, such as malware testing images, may support them. A snapshot captures the current environment state so you can restore it later.
Open the **Actions** menu on the Virtual Environment and click **Manage Snapshots**. From that dialog, you can create, restore, edit, and delete snapshots.
Creating a snapshot starts a background job. The time required depends on how much data is stored in the environment.
Restoring a snapshot also starts a background job. The current state is replaced by the snapshot, and the environment restarts while the restore is applied.
## Credentials
Each Virtual Environment has its own credentials. Use them for advanced actions that require a password.
### Viewing Environment Credentials
From the Virtual Environments page, open the environment's **Actions** menu and click **View Credentials**. You can also open the same credentials from the toolbox through **Admin Credentials** while inside the environment.
{% hint style="success" %}
Click the **User Name** or **Password** field to copy it to the clipboard.
{% endhint %}
## Deleting a Virtual Environment
Deleting an environment permanently removes it.
To delete an environment, open its **Actions** menu and click **Delete**, then confirm the action.
## Stop/Start a Virtual Environment
Malware environments can be stopped and started.
To stop or start one, open its **Actions** menu and click **Stop Environment** or **Start Environment**, then confirm the action.
## Restarting a Virtual Environment
To restart an environment, open its **Actions** menu, click **Restart**, and confirm.
## Renaming a Virtual Environment
To rename an environment, open its **Actions** menu, click **Rename**, and enter the new name.
## Additional Details
To view more information about an environment, open its **Actions** menu and click **View Details**.
## Assigning a Virtual Environment
A Virtual Environment can be assigned to a user, group, or profile. Administrators can assign any environment. Standard users can assign only to themselves, to groups they belong to, or to users in those groups. By default, the creator is the assignee.
### Assignment on creation
During creation, you can assign the environment to a user, group, or profile. Assigning to a group grants access to all users in that group. If the environment is assigned to a profile, the user or group that owns the profile can access it.
### Reassignment
To change the assignee after creation, open the environment's **Actions** menu and click **Assign**.
The reassignment dialog lets you choose a new user, group, or profile.
{% hint style="danger" %}
If you assign the environment to a user other than yourself, to a group you do not belong to, or to a profile you are not assigned to, you may lose access.
{% endhint %}
## Base Images
Base images define the operating system, applications, and built-in features for a Virtual Environment.
### Viewing Image Details
Click any image card in the image catalog to open its details. The panel shows the image version, operating system, image type, and installed applications. Click close to dismiss it.
Your image catalog may include:
* Linux Firefox
* Linux Brave
* Linux Tor
* Linux Jupyter Notebooks
* Linux Selenium
* Windows Edge
{% hint style="info" %}
Available images depend on your organization's subscription and configuration. You may see fewer images than the examples listed here, and custom images may also be available.
{% endhint %}
### Linux Neo4j
To access Neo4j in a Linux Neo4j environment:
{% stepper %}
{% step %}
Open the applications menu and select **Open Neo4j** from the **Programming** category.
{% endstep %}
{% step %}
Connect to the Neo4j database.
{% endstep %}
{% endstepper %}
### Linux Jupyter Notebooks
To access Jupyter Notebooks in a Linux Jupyter Notebooks environment:
{% stepper %}
{% step %}
Open Jupyter Notebooks.
{% endstep %}
{% step %}
Jupyter launches in Firefox at .
{% endstep %}
{% step %}
The environment displays the shared notebooks.
{% endstep %}
{% endstepper %}
## File Export
{% hint style="info" %}
If you are not using File Export for out-of-band transfer, use [Files](/user-guide/4.4-user-guide/butler-user-guide#files) in Butler to move data into or out of Virtual Environments.
{% endhint %}
If your administrator has configured **File Export**, you will see an additional option under **Advanced** during environment creation. You must enable it at creation time. After that, files saved in the **Sync** folder on the environment desktop can be exported to external storage such as MinIO or S3.
All exported data is encrypted in transit with SSL/TLS 1.2 or higher and encrypted at rest with AES-256. If S3 is used, AWS Server-Side Encryption S3 (`SSE-S3`) provides AES-256 encryption at rest.
### Exporting Data Walkthrough
{% stepper %}
{% step %}
Create a new Virtual Environment from the **Environments** page and enable **File Export** under **Advanced Options**. If this option does not appear, the image does not support File Export or it has not been configured.
{% endstep %}
{% step %}
Return to the **Environments** page. In the environment's **Actions** menu, look for **Export to S3**. The label says "S3" even if a different storage backend is configured.
{% endstep %}
{% step %}
Launch the Virtual Environment and download a file with the in-environment browser.
{% endstep %}
{% step %}
When saving the file, change the destination from **Downloads** to the **Sync** folder on the desktop.
{% endstep %}
{% step %}
Return to the **Environments** page, open the **Actions** menu for that environment, and click **Export to S3**.
{% endstep %}
{% step %}
Confirm the export. A success notification appears in the top-right corner.
{% endstep %}
{% endstepper %}
### Viewing Exported Data
{% hint style="warning" %}
This section is intended for advanced users or administrators with access to the AWS S3 console.
{% endhint %}
{% stepper %}
{% step %}
If your deployment uses AWS S3 and you have direct bucket access, locate the export bucket using the prefix configured by your administrator followed by `-exports-` and your user ID. If you do not have direct access, contact your administrator.
{% endstep %}
{% step %}
Open the bucket and locate the folder named for the Virtual Environment ID and export timestamp. Timestamps use the format `mm-dd-yyyy-hh:mm:ss`.
{% endstep %}
{% step %}
Open the most recent export folder and confirm that the file from the environment is present.
{% endstep %}
{% endstepper %}
## Hardware Virtual Environments
Hardware Virtual Environments connect physical devices to the Replica platform. They launch and operate like other Virtual Environments, but available features may differ because of hardware-specific limitations.
These environments require special configuration and can only be created or deleted by an administrator. Some standard features, such as Butler file transfer, may not be available.
To check whether an environment is hardware-backed, open **View Details** and review the Environment ID. Hardware Virtual Environments use IDs that begin with `hw`.
Administrators can find additional details in the administrator documentation.
# My View
The *My View* dashboard gives you a simplified view of the resources assigned to you. It also provides a fast path for creating new environments.
To open My View, click **My View** in the top header on any Replica page.
## Environments
The *environments* section lists the environments assigned to you. It also includes buttons to [quick create a Virtual Environment](/user-guide/virtual-environments#quick-creating-a-virtual-environment-beta) or [create a Virtual Environment](/user-guide/virtual-environments#creating-a-virtual-environment).
## Enclaves
The *enclaves* section lists the enclaves assigned to you or to a group you belong to. It also includes a button for creating a new enclave.
## Resource Summary
The *resource summary* section shows a count of the resources you can access. This currently includes environments, enclaves, and routers.
## User Management
The *user management* section lets you update account details such as your password, email, first name, and last name. Username changes are not supported.
## Network Map
The *network map* section shows the egress locations currently available to you. This helps you understand which locations can be used to reach resources that depend on geography.
## Notifications
Use the bell icon in the top toolbar to open the **Notifications** panel. The dropdown shows recent notifications and a badge with the number of unread items.
# 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 %}
# Profiles
## Profiles Introduction
Profiles control how a Virtual Environment appears to external services. Like a standard environment, a profile can define an egress and language settings that shape attribution. If you select a profile during environment creation, Replica uses the profile's egress automatically.
Profiles also record activity in a shared history. This can include profile creation, environment connections, recordings, notes, and screenshots. The history helps you maintain a consistent profile over time, even across multiple operators.
Profiles are assigned to a user or group. By default, the profile is assigned to the person who creates it. You can change that later from the profile details page. Any Virtual Environment created with that profile inherits the profile assignment and egress.
Profiles also provide an in-environment overlay with helpful context such as name, time, weather, and news, along with tools like notes, broadcast chat, and SMS messaging.
## Create a Profile
{% stepper %}
{% step %}
#### Open the New Profile page
On the **Profiles** page, click **Create** in the upper-right corner.
{% endstep %}
{% step %}
#### Enter profile details and create
Enter the profile details, then click **Create New Profile**.
* **Name**: The identity name you want to emulate.
* **Egress Name**: The VPN used by the profile. You can choose from the egresses assigned to you by your administrator. **Egress Location** shows where traffic exits to the internet.
* **Profile Picture** *(optional)*: An image representing the identity. One option for anonymous generated images is [thispersondoesnotexist.com](https://www.thispersondoesnotexist.com/).
* **Description**: A short summary of the persona. Describe who they are and what they do.
{% endstep %}
{% endstepper %}
## Managing Profiles
### Viewing Profiles
Open **Profiles** from the left-hand menu to see all available profiles. Click **Details** on a profile card to open the profile details panel.
### Viewing Profile Details
The profile details page shows the egress, profile description, and activity history. If the profile is not yet associated with a Virtual Environment, the history only shows the profile creation event.
### Viewing Profile Activity History
Once you associate a profile with a Virtual Environment and begin using it, more events appear in the history. If playback is enabled, session recordings are included and can support auditing or knowledge transfer.
### Assigning Profiles
To assign the profile to a different user or group, click the edit button in the **Assignee** section.
### Deleting Profiles
To delete a profile, click **Delete Profile** on the profile card, then confirm the action.
## Associating a Virtual Environment with a Profile
{% stepper %}
{% step %}
#### Create a Virtual Environment with the profile
Create a new Virtual Environment and select the profile you just created. When you choose a profile, the egress location option disappears because the profile controls those settings.
{% endstep %}
{% step %}
#### Verify association
After the environment starts, confirm the profile association from the profile column and location details.
{% endstep %}
{% endstepper %}
# Phones
## Phones Introduction
Replica supports two phone offerings:
* **Physical Phones**: An optional add-on that provides one or more real Android phones you can control from Replica.
* **Virtual Phones**: Software-based calling and messaging features tied to assigned phone numbers.
Use the sections below to understand which workflow applies to your setup.
{% hint style="info" %}
Phone features depend on your organization's subscription and configuration.
{% endhint %}
## Physical Phones
Physical Phones are an optional add-on. They add one or more real Android phones to the platform so you can control them from Replica.
Physical Phones are made available through a special enclave provided for that purpose.
### Launch a Physical Phone
To launch a Physical Phone, create a Virtual Environment and complete both of these connectivity steps:
* Attach the phone enclave.
* Add the `phone network` private route.
After the environment is ready, launch it to access the attached physical device.
## Virtual Phones
Virtual Phones extend Virtual Environments and Profiles with calling and messaging features. They are commonly used for workflows such as two-factor authentication.
To get phone numbers assigned, contact your administrator. Manage assigned numbers from the **Phones** section. Use them inside a Virtual Environment from the `SMS` icon in the overlay. For usage details, see [SMS Messaging](/user-guide/virtual-environments#sms-messaging).
### View Virtual Phone Numbers
Open **Phones** from the left-hand menu to see the phone numbers available to you.
You will see cards for numbers assigned to you directly or indirectly through a profile or group.
* **Provider**: The Software Defined Telephony (SDT) provider, such as Twilio or Bandwidth, or an SMS Device. **SMS Device** means the number is tied to a physical device.
* **Number**: The phone number in international `E.164` format.
* **Name**: A label that identifies the number's purpose.
* **Number Is**: Shows whether the number is active.
* **Call Forwarding No.**: *(Optional, Twilio only)* Inbound calls to **Number** are forwarded to this number. The caller does not see the forwarding destination. If this field is empty, inbound calls to **Number** return a busy tone. If you call the Replica number from the configured forwarding number, a service answers and prompts you for the number to dial. The outbound call then appears to come from **Number**, not the forwarding number.
* **Assignee**: The assigned user, group, or profile. In environments assigned to a profile, you can access numbers assigned to that profile while using that environment. In all other environments, you can access numbers assigned directly to you or through a group.
* **Is Use As Relay**: *(Administrator feature)* Shows whether an SDT provider number is acting as a relay for an SMS Device and which numbers it supports.
# Troubleshooter Portal
The Replica Troubleshooter Portal is a standalone diagnostic tool. It checks whether your system and network are set up for a reliable Replica experience. The portal runs a series of browser-based pre-flight checks and reports the results. If anything looks unexpected, take a screenshot of the results page and contact Replica Support.
## Accessing the Troubleshooter
Click **Diagnose** at the bottom of the left-hand navigation sidebar to open the Troubleshooter Portal.
## Diagnostic Checks
The Troubleshooter runs the following checks:
* **Ping** — Measures round-trip latency to the Replica platform. High latency can reduce session responsiveness.
* **Jitter** — Measures variation in ping time. High jitter can make Virtual Environment sessions unstable.
* **Clipboard Access** — Verifies that your browser allows clipboard access. If access is denied, copy and paste between your computer and a Virtual Environment will not work.
* **WebSockets** — Confirms that WebSocket connections are available. Replica requires this for Virtual Environment sessions.
* **Download Speed** — Measures network throughput. Higher speeds improve the experience, especially at higher resolutions.
* **IP Info** — Shows your public IP address and geolocation. Use this to confirm you are connecting from the expected network.
* **IP Database Traits** — Checks classifications associated with your IP address that may affect connectivity to a Virtual Environment.
* **Browser Capabilities** — Verifies support for cookies, WebGL, WebAssembly, local storage, and other features Replica may require.
# Tutorials
This section covers common tasks in Replica.
## Installing software
You can install additional software in Replica environments as needed. Use any compatible application that fits your workflow. If you need help choosing a tool, contact Replica Support. Make sure you have the correct license for any software you install.
{% hint style="info" %}
Replica environments support many applications, but Replica does not test every third-party tool. Support for third-party software usually comes from the software vendor.
{% endhint %}
### Installing software in Windows environments
Windows environments include **Chocolatey GUI** in the Start menu for easy application installs. You can also install Windows applications downloaded from the internet in the usual way.
If you are prompted for a password, use the environment credentials. See [Credentials](/user-guide/virtual-environments#credentials).
### Installing software in Linux environments
Linux environments support additional software installation through the `APT` package manager.
When installing applications, you usually need superuser privileges. Use `sudo`, for example:
{% code title="Example" %}
```bash
sudo apt install
```
{% endcode %}
When prompted for a password, use the password shown under **Actions** → **View Credentials** on the Virtual Environments page. See [Credentials](/user-guide/virtual-environments#credentials).
Replica does not necessarily test or approve third-party packages available through `APT`.
See also: [Ubuntu APT documentation](https://help.ubuntu.com/community/AptGet/Howto)
## Gaining access to sites
Website access depends on more than just IP address. Many sites filter traffic based on the perceived attribution of the system connecting to them. Different sites look at different signals, and they rarely disclose exactly what they use.
Common attribution signals include IP address, ISP, user agent, browser fingerprint, operating system, screen resolution, browser configuration, software versions, installed fonts, and languages.
In the past, some users tried to spoof these values. That approach is now easier to detect because modern filtering systems can spot unrealistic combinations.
The most effective approach is to use the most realistic connection possible. That is the model Replica is designed to support.
### CAPTCHAs
CAPTCHAs are tests sites use to separate human traffic from automated or suspicious traffic. Some sites show them to everyone. Others only show them when attribution signals match patterns they distrust. CAPTCHAs often appear when a connection looks unrealistic.
If you keep seeing CAPTCHAs, try the following:
{% stepper %}
{% step %}
### Avoid spoofing or anonymizing tools
Do not use extensions or tools that spoof or mask attribution signals. Fake signals are easy to detect.
{% endstep %}
{% step %}
### Try a different egress location
Try another egress location. Some sites distrust traffic from specific networks. Switching networks can improve access. For example, Tor exits often trigger CAPTCHAs.
{% endstep %}
{% step %}
### Ensure realistic browsing behavior for automation
If you use automation for browsing or scraping, keep request rates realistic for normal human behavior.
{% endstep %}
{% endstepper %}
If CAPTCHAs continue, contact Replica Support for additional options.
# Admin Guide Introduction
Replica supports self-service administration. Use this guide to manage access, configure platform services, and review operational data.
Admin pages cover user and group management, service configuration, and monitoring tools.
## Admin Navigation
Users with admin-level roles see extra items in the left-hand navigation.
Users with the **Admin** role see a dedicated administration section with links to:
* **Egress** — Create and manage egress routers and connectivity options.
* **External Storage** — Configure external storage providers such as Amazon S3 and MinIO.
* **Hardware Devices** — Manage hardware device pools.
* **Text API** — Configure the Text API integration.
* **Telephony** — Configure telephony providers.
* **Zones** — View and manage deployment zones.
* **Users** — Create and manage user accounts, roles, and credentials.
* **Groups** — Create and manage groups used to organize resources.
* **Proxy Management** — Configure proxy settings.
* **Notifications** — Send platform-wide or targeted notifications.
* **Logging** — Open the log search and analysis interface.
* **Monitoring** — Open the platform monitoring dashboard.
# User Management
Use User Management to create, update, enable, and disable users.
## Roles
Replica uses roles to control what each user can do. Users without a role cannot use Replica or view data.
See [Roles and Permissions](/admin-guide/user-management/roles-and-permissions).
## Groups
Groups help organize users and control resource access.
See [Group Management](/admin-guide/user-management/group-management) and [Resource Visibility and Assignment](/admin-guide/user-management/resource-visibility-and-assignment).
## Finding Users
The Users list includes a **Search** field to quickly locate a user by name, username, or email address.
## Enabled and Disabled Users
Users must be enabled to sign in. New users are enabled by default.
Disabled users cannot sign in or use the platform. Replica keeps disabled users for history and audit purposes instead of deleting them.
To change a user's status, open the Users list and select `Disable` or `Enable` in that user's actions.
{% hint style="warning" %}
Replica does not support permanent user deletion.
{% endhint %}
## Password Resets
To reset a password, select `Reset Password` in that user's actions.
You can use the generated password or set one manually. The user must change it on the next login.
# Roles and Permissions
Replica uses role-based access control. Assign one or more roles to each user to define their access.
Users inherit the combined permissions of all assigned roles.
## Roles Overview
| Role | Description |
| --------- | --------------------------------------------------------------------------------------- |
| Core | The standard set of permissions for a typical Replica User |
| API | A set of permissions that grant API access and access to Replica Jobs |
| Isolation | A limited set of permissions to trigger a VE creation and launch it |
| Guest | Limited access to interact with existing VEs only |
| Admin | An administrative set of permissions granting full access and visibility within Replica |
| Audit | A set of permissions for access to audit, log, and monitoring data |
## Replica Core Functionality
| | Core | API | Isolation | Guest | Admin | Audit |
| ------------------------ | :--: | :-: | :-------: | :---: | :---: | :---: |
| Use Environments | X | | | X | | |
| Manage Environments | X | | | | | |
| Quick-Launch Environment | X | | X | X | | |
| Manage Enclaves | X | | | | | |
| Manage File Requests | X | | | | | |
| Manage Jobs | | X | | | X | |
| Manage Profiles | X | | | | | |
| Manage Self | X | X | X | X | X | X |
| Receive Notifications | X | | X | X | X | X |
| Use External Links | X | | | X | X | |
| Use Phone Numbers | X | | | | | |
| Use Profiles | X | | | | | |
| Use Zones | X | | | | X | |
| View Images | X | | | | X | |
## Platform Administration
| | Core | API | Isolation | Guest | Admin | Audit |
| ----------------------------- | :--: | :-: | :-------: | :---: | :---: | :---: |
| Access Logging | | | | | X | X |
| Access Monitoring | | | | | X | X |
| Manage Advanced Configuration | | | | | X | |
| Manage External Links | | | | | X | |
| Manage Groups | | | | | X | |
| Manage Hardware Devices | | | | | X | |
| Manage Images | | | | | X | |
| Manage Notifications | | | | | X | |
| Manage Phone Numbers | | | | | X | |
| Manage Proxies | | | | | X | |
| Manage Routers | | | | | X | |
| Manage SMS Devices | | | | | X | |
| Manage Storage | | | | | X | |
| Manage Telephony Providers | | | | | X | |
| Manage Translation | | | | | X | |
| Manage Users | | | | | X | |
| Manage Zones | | | | | X | |
| Read Swagger Docs | | | | | X | |
| Modify Global Assignments | | | | | X | |
| Modify All Data | | | | | X | |
Modify Global Assignments
Resources assigned to `Global` are visible to all users. Only admins can assign resources to or from `Global`.
# Group Management
Use Group Management to create and update groups.
## Parents
A group can belong under another group. This parent-child structure supports up to three levels.
## Types
You can assign a type to a group to describe its purpose. The available types are:
* **Team** — A group representing a team of users.
* **Project** — A group representing a project or initiative.
## Users
Users can belong to multiple groups, one group, or no groups. Groups can also exist without members.
See [User Management](/admin-guide/user-management).
# Resource Visibility and Assignment
## Resource Visibility
Users can view resources assigned to:
* Themselves
* Groups they are members of
* Profiles they can see
* Global
If a user is assigned to a group, they can also view resources assigned to that group, its members, and its subgroups.
Users with the **Admin** role can view all resources in the system.
## Resource Assignment
Users can assign resources to:
* Themselves
* Groups they are members of
* Users in those Groups
* Subgroups (and the Users in them) of those Groups
* Profiles they can see
If a user is assigned to a group, they can also assign resources to that group, its members, and its subgroups.
Users with the **Admin** role can assign resources to any user, group, or profile, including `Global`.
### Resource Type Specific Rules
* Routers cannot be assigned to profiles.
* Profiles cannot be assigned to profiles.
* Groups can only be assigned to users.
# User Policies
{% hint style="info" %}
Replica manages authentication with Keycloak. Default password, session, and login settings follow common security baselines. Replica SSO administrators handle custom changes. Contact your account manager for exceptions or review the [Keycloak documentation](https://www.keycloak.org/documentation).
{% endhint %}
## User Policies
### Passwords
* Minimum password length: 15 characters
### Login Lockouts (Brute Force Detection)
Default settings:
* Max login failures: 30 — after this point a lockout is triggered.
* Permanent lockout: disabled
* Wait increment: 1 minute before a lockout ends
* Max failure count reset: after 12 hours
* Quick login check: 1 second. Faster attempts trigger a lockout.
* Minimum wait after a quick login: 1 minute before the lockout ends
### Login Timeout Settings
Default settings:
* Login Timeout: 30 minutes
* Login action timeout: 5 minutes
### SSO Session Settings
Default settings:
* SSO Session Idle: 30 minutes
* SSO Session Max: 10 minutes
# Butler Admin Guide
This page lists default Butler settings and Butler audit data.
## Clipboard Configuration
| Description | Default |
| ------------------------------------ | ---------------- |
| Enable or disable Clipboard Transfer | Enabled |
| User host clipboard operations | Upload, Download |
| Environment clipboard operations | Upload, Download |
| Clipboard data expiration | 1 hour |
## Translation Configuration
| Description | Default |
| ---------------------------------- | ------- |
| Enable or disable text Translation | Enabled |
## File Configuration
These are the default Butler file transfer settings.
{% hint style="info" %}
Butler data transfers are performed over encrypted channels and Butler Storage encrypts data at rest.
{% endhint %}
| Description | Default |
| ---------------------------------------------- | ---------------------------------------- |
| Enable or disable File Transfer | Enabled |
| User host file operations | List, Upload, Download, Delete, Copy |
| Environment file operations | List, Upload, Download, Delete, Copy |
| The maximum file size allowed for upload | 400MB |
| The maximum number of files allowed per upload | 10 |
| Anti-Virus (AV) scanning | Enabled |
| Anti-Virus (AV) ignore | None |
| Infected file download | Blocked (Except in malware environments) |
| File Encryption at Rest | Enabled |
| File Encryption Algorithm | AES-256 |
| File Integrity Verification | Disabled |
| File Integrity Algorithm | None (options available) |
## Environment Events
Butler can send actions into Replica environments. If environment events are enabled, the environment receives and processes event messages. Use the Butler API sample for programmatic access.
| Description | Default |
| ------------------------------------------- | ----------------------- |
| Enable or disable Environment Events | Disabled |
| Enable or disable Environment File Autosync | Disabled |
| Environment File Autosync directory | Desktop Files directory |
### File Events
When file events are enabled, Butler can automatically transfer uploaded files into the environment.
### Browser Events
When browser events are enabled, Butler can open a URL inside a Replica environment.
## File History
Butler records file activity in its history and logging systems. Each event includes a UTC timestamp.
#### Fields
Butler resource history entries include the following fields:
| Name | Description |
| -------------- | ---------------------------------------------------- |
| resource\_id | A unique identifier assigned to the Resource |
| resource\_path | The Resource path in Butler Storage |
| entity\_type | The Entity Type that performed the action |
| entity\_id | The Entity Id that performed the action |
| accessed | The timestamp of when the action was performed (UTC) |
| operation | The action that was performed |
#### Entity Types
| Name | Description |
| ------- | --------------------------------------- |
| User | A Replica user plus their User Id |
| Group | A Replica group plus their Group Id |
| Profile | A Replica profile plus their Profile Id |
#### Operation Types
| Name | Description |
| -------- | --------------------------------------------------------------- |
| Delete | The resource was deleted from Butler Storage |
| Download | The resource was downloaded from Butler Storage |
| Transfer | The resource was transferred between Enclaves in Butler Storage |
| Upload | The resource was created or updated in Butler Storage |
Resource History Sample
```json
[
{
"resource_id": "resource_id",
"resource_path": "resource_path",
"entity_type": "entity_type",
"entity_id": "entity_id",
"accessed": "2023-10-30T17:14:08.000Z",
"operation": "upload"
},
{
"resource_id": "resource_id",
"resource_path": "resource_path",
"entity_type": "entity_type",
"entity_id": "entity_id",
"accessed": "2023-10-30T17:14:22.415Z",
"operation": "download"
},
{
"resource_id": "resource_id",
"resource_path": "resource_path",
"entity_type": "entity_type",
"entity_id": "entity_id",
"accessed": "2023-10-30T17:16:43.501Z",
"operation": "delete"
}
]
```
***
### File Event Logging
| Name | Description |
| ------ | ------------------------------------- |
| Get | Get a Resource from Butler Storage |
| Put | Save a Resource in Butler Storage |
| Delete | Delete a Resource from Butler Storage |
Transfer Sample
```json
{
"@timestamp": "2023-10-30T17:54:57.925Z",
"log.level": "info",
"message": "Auth credentials accepted",
"ecs": { "version": "8.10.0" },
"event": {
"kind": "event",
"type": ["allowed"],
"category": ["authentication"],
"outcome": "success"
},
"http": {
"version": "1.1",
"request": {
"method": "PUT",
"headers": {
"host": "replicacyber.com",
"x-request-id": "8709f71e96fd500b5e3433bf0051ef44",
"x-real-ip": "1.2.3.4",
"x-forwarded-for": "1.2.3.4",
"x-forwarded-host": "replicacyber.com",
"x-forwarded-port": "443",
"x-forwarded-proto": "https",
"x-forwarded-scheme": "https",
"x-requested-with": "XMLHttpRequest",
"x-scheme": "https",
"content-type": "multipart/form-data; boundary=---------------------------1804628349855675348442767821",
"user-agent": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/119.0",
"accept": "application/json",
"accept-language": "en-US,en;q=0.5",
"accept-encoding": "gzip, deflate, br",
"cookie": "redacted"
},
"body": { "bytes": 6165 }
},
"response": {
"status_code": 200,
"headers": {
...
}
}
},
"url": {
"path": "/butler/api/v1/transfer/resources/mY9bUtVCxc7F-9R6MHOgA-SQZJMD5Bt0V-pUAG2cVnA/test.txt",
"domain": "replicacyber.com"
},
"client": {
"address": "1.2.3.4",
"ip": "1.2.3.4",
"port": 36600
},
"user_agent": {
"original": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/119.0"
},
"user": {
"authenticated": true,
"id": "a123456-1234-1234-1234-123456789123",
"email": "username@replicacyber.com",
"full_name": "User Name"
}
}
```
Auth Sample
```json
{
"@timestamp": "2023-10-30T17:52:41.164Z",
"log.level": "info",
"message": "Auth credentials accepted",
"ecs": {
"version": "8.10.0"
},
"event": {
"kind": "event",
"type": ["allowed"],
"category": ["authentication"],
"outcome": "success"
},
"http": {
"version": "1.1",
"request": {
"method": "GET",
"headers": {
"host": "replicacyber.com",
"x-request-id": "39a4d4d54dd906fdc942a239df23a26a",
"x-real-ip": "1.2.3.4",
"x-forwarded-for": "1.2.3.4",
"x-forwarded-host": "replicacyber.com",
"x-forwarded-port": "443",
"x-forwarded-proto": "https",
"x-forwarded-scheme": "https",
"x-scheme": "https",
"accept": "application/json",
"user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36",
...
}
},
"response": {
"status_code": 200,
...
}
},
"url": {
"path": "/butler/api/v1/enclaves",
"domain": "replicacyber.com"
},
"client": {
"address": "1.2.3.4",
"ip": "1.2.3.4",
"port": 48354
},
"user_agent": {
"original": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36"
},
"user": {
"authenticated": true,
"id": "a123456-1234-1234-1234-123456789123",
"email": "username@replicacyber.com",
"full_name": "User Name"
}
}
```
Login Sample
```json
{
"@timestamp": "2023-10-30T17:02:07.450Z",
"log.level": "info",
"message": "User John Smith logged into butler",
"ecs": {
"version": "8.10.0"
},
"event": {
"kind": "event",
"type": ["user"],
"category": ["authentication"],
"outcome": "success"
}
}
```
# Data Management
This page summarizes where data is stored and how key platform data is retained.
## Replica Environment
### Virtual Environment Storage
Each virtual environment includes a home directory that persists for the life of that environment.
Data stored outside the home directory may be removed when the environment is not running. When an environment is deleted, all data inside it is permanently removed.
## Replica Platform
Replica performs nightly backups of critical platform data to isolated external storage.
### Butler
See [Butler Admin Guide](/admin-guide/butler-admin-guide) for Butler storage, transfer, and audit details.
### Egress
See [Egress data policy](/admin-guide/egress#egress-data-policy).
### Logging
See [Logging data management](/admin-guide/logging#logging-data-management).
### Telephony
Telephony data for software-defined resources is retained for at least one year.
# Limits
Replica enforces limits to preserve shared resources and maintain platform availability. Some limits vary by environment type and backing infrastructure.
{% hint style="info" %}
Some limits can be adjusted. Contact Replica Support for details. Your organization may also have limits that differ from the defaults below.
{% endhint %}
## Storage Limits
| Object | Description | Limit |
| ------------------------------------- | ----------------------------------------------------- | --------------------------------- |
| Virtual Environment (container-based) | Maximum amount of data stored in `/home/user` | 500 GB shared across all VEs |
| Virtual Environment (container-based) | Maximum amount of data stored outside of `/home/user` | 50 GB shared across node |
| Virtual Environment (VM-based) | Total storage limit | 30 GB |
| Virtual Environment (Malware-type) | Total storage limit | 30 GB - 50 GB, depending on image |
| Physical Mobile Device | Total storage limit | 128 GB |
{% hint style="info" %}
Available storage may be lower than the stated limit because of preinstalled system or application data.
{% endhint %}
## Memory Limits
| Object | Description | Limit |
| ------------------------------------- | -------------------------------- | ----- |
| Virtual Environment (container-based) | Total memory limit | 5 GB |
| Virtual Environment (VM-based) | Memory limit, not including swap | 4 GB |
| Virtual Environment (Malware-type) | Memory limit, not including swap | 8 GB |
## Transfer Limits
| Object | Description | Limit |
| ---------------------- | ------------------------ | ----------------------------- |
| Virtual Environment | Egress data transfer | unlimited |
| Virtual Environment | Proxy data transfer | subject to subscription terms |
| Enclave | Maximum file upload size | 400 MB |
| Butler Files | Maximum file upload size | 400 MB |
| Physical Mobile Device | SMS/MMS limit | unlimited |
| Physical Mobile Device | Data transfer limit | unlimited (via WiFi) |
# Egress
## Egress Introduction
Egress controls where outbound internet traffic leaves the Replica platform. The egress location strongly affects the apparent origin and signature of your activity.
This matters because many websites classify, filter, or block visitors based on source network details.
### Egress Types
Replica may be configured with several types of Egress options, including but not limited to:
* Commercial VPN provider Egress
* Cloud VPN Egress
* Bring-your-own VPN Egress
* White-line Egress
{% hint style="info" %}
Each option has tradeoffs. Contact your Replica representative if you need help choosing the right one.
{% endhint %}
### Egress Data Policy
Replica egress protocols create encrypted channels between your platform and the egress servers. Replica provisions egress resources on isolated infrastructure.
Replica does not log or retain egress traffic data in transit.
### What impact does Egress have on my attribution/signature?
Observers can identify traffic sources in several ways. The most common method is an IP address lookup against commercial or public IP databases.
These databases often include location, provider, organization, and whether an IP belongs to a VPN or cloud platform.
Websites rarely disclose their exact filtering logic. If a site blocks traffic based on IP reputation or geography, using a different egress may help.
Egress also affects other parts of your activity signature. By default, Replica aligns environment locale settings with the languages used in the selected egress location.
### Bring-your-own VPN Egress
You can bring your own VPN provider and use it as an egress location in Replica. Replica supports WireGuard and OpenVPN.
{% hint style="danger" %}
Your VPN provider may limit how many users can share one connection. Make sure your Replica configuration stays within that provider's terms of service.
{% endhint %}
## Create Egress
To create a new egress point, gather valid WireGuard or OpenVPN configuration details from your provider. If both are available, WireGuard is usually the better choice for performance.
### WireGuard
{% stepper %}
{% step %}
#### Access Egress
Open **Egress** from the **Administration** menu. The page shows existing egress locations as cards.
Click the **Create Wireguard** button to open the New Egress Details form.
{% endstep %}
{% step %}
#### Router settings
Fill out the following fields:
* **Router Name**: Choose a name that will be displayed to users to select this Egress.
* **Router Type**: Select `Egress`.
* **Router Status**: Select `Active` to enable this egress.
* **Disable Egress Verification**: Enable this option to bypass Egress verification checks.
* **Hot Swap**: Enable this option to allow a running environment to change routers.
{% endstep %}
{% step %}
#### Provider settings
Click **Next** to open the provider page, then fill out:
* **Provider Name**: Enter the name of your Egress provider.
* **Provider Type**: Select the provider type. `VPN` is the most common choice.
{% endstep %}
{% step %}
#### Configuration
Click **Next** to open the configuration page.
* Paste the contents of your Wireguard configuration file into the **Configuration** field.
{% endstep %}
{% step %}
#### Create
Click **Next** to create the egress. The new egress appears in the card list.
Assign the egress to a user or group before they can use it.
{% endstep %}
{% endstepper %}
### OpenVPN
{% stepper %}
{% step %}
#### Access Egress
Open **Egress** from the **Administration** menu. The page shows existing egress locations as cards.
Click the **Create OpenVPN** button to open the New Egress Details form.
{% endstep %}
{% step %}
#### Router settings
Fill out the following fields:
* **Router Name**: Choose a name that will be displayed to users to select this Egress.
* **Router Type**: Select `Egress`.
* **Router Status**: Select `Active` to enable this egress.
* **Disable Egress Verification**: Enable this option to bypass Egress verification checks.
* **Hot Swap**: Enable this option to allow a running environment to change routers.
{% endstep %}
{% step %}
#### Provider settings
Click **Next** to open the provider page, then fill out:
* **Provider Name**: Enter the name of your Egress provider.
* **Provider Type**: Select the provider type. `VPN` is the most common choice.
{% endstep %}
{% step %}
#### Certificates & Configuration
Click **Next** to open the configuration page, then fill out:
* **CA Certificate**: Paste the contents of your CA certificate here, if provided by your VPN provider.
* **Key Certificate**: Paste the contents of your private Key Certificate here, if provided by your VPN provider.
* **Key**: Paste the contents of your private key here, if provided by your VPN provider.
* **Configuration**: Paste the contents of your OpenVPN configuration file here. This is a mandatory field.
{% endstep %}
{% step %}
#### Locale Configuration
Click **Next** to open the locale configuration page. All fields on this page are optional.
{% endstep %}
{% step %}
#### Create
Click **Submit** to create the egress. The new egress appears in the card list.
Assign the egress to a user or group before they can use it.
{% endstep %}
{% endstepper %}
## Edit Egress
Each egress card includes action icons in the top-right corner. Hover over an icon to see its action.
# Zones
Zones are an optional feature that define external deployment regions and infrastructure configurations available on the Replica platform. Each zone maps to a compute provider region and enables new types of Virtual Environments to be launched.
> **Note:** Zones are typically configured and managed by Replica. Under normal circumstances, zone settings should not be created or modified without guidance from your Replica representative.
## Viewing Zones
Open **Zones** from the admin navigation to see a list of all configured deployment zones.
The zones list shows a table with the following columns:
| Column | Description |
| ---------------- | ---------------------------------------------------- |
| id | The unique identifier for the zone. |
| name | The display name of the zone. |
| iaas | The infrastructure provider |
| region | The provider region where the zone is deployed. |
| status | The current operational status of the zone. |
| supports Malware | Whether the zone supports Malware environment types. |
| created Time | When the zone was created. |
| Actions | Available management actions for the zone. |
## Creating a Zone
Click **Create Zone** to configure a new deployment zone. Zone creation requires coordination with your Replica representative and is typically done during onboarding or capacity expansion.
## Zones and Malware Environments
Zones that support Malware are configured with the necessary isolation and security controls required for malware analysis workflows. When creating a Virtual Environment with the **Malware** use-case type, only zones that support malware are available for selection.
# Logging
Use Logging to search, analyze, and export Replica logs.
## Log Types
### Replica Environment
Virtual environment activity is logged by event type. For DNS, URL, and packet logging details, see [Network Monitoring](/admin-guide/network-monitoring).
| Name | Index | Description | Default Retention |
| ----------------- | ----------- | ---------------------------------------------------------------------------------------------- | ----------------- |
| System | env.system | Environment Operating System start up events | 30 days |
| DNS & URL Logging | env.traffic | Capture and extract URLs from network packets and Environment Domain Name System (DNS) queries | 1 day |
### Replica Platform
| Name | Elasticsearch Indices |
| ---------------- | ----------------------------------------- |
| Auth (SSO) | app.sso |
| Egress | app.wharf, app.rest-api |
| Entity | app.user-service, app.rest-api |
| Environment | app.ic2, app.hive, app.keel, app.rest-api |
| Image | app.hull |
| Permissions | app.user-service |
| Profiles | app.profile-memory, app.rest-api |
| Telephony | app.telephony |
| VE Clipboard | app.butler |
| VE Files | app.butler |
| VE Jobs | app.butler, app.keel |
| General VE Usage | env.usage |
| VE Translations | app.butler |
## Logging Data Management
Replica snapshots Elasticsearch indices to secondary backup volumes. Snapshots are typically retained for 30 to 90 days.
All Replica logs include timestamps synchronized through Amazon Time Sync.
### Retention Policies
| Index Name | Retention |
| ------------------ | --------- |
| app.butler | 180 days |
| app.hull | 30 days |
| app.ic2 | 90 days |
| app.keel | 90 days |
| app.profile-memory | 90 days |
| app.rest-api | 180 days |
| app.sso | 180 days |
| app.telephony | 30 days |
| app.user-service | 180 days |
| app.wharf | 180 days |
| env.system | 30 days |
| env.traffic | 1 day |
| env.usage | 90 days |
## Accessing Logging
Open **Logging** from the **Administration** menu to access the logging home screen.
### Dashboards
#### Accessing Dashboards
To open the preloaded dashboard, click the menu button in the top-left corner and select **Dashboard** under **Analytics**.
The default *Replica Dashboard* includes built-in visualizations that update as new data arrives. You can clone it or create your own dashboard.
{% hint style="warning" %}
Changes to the default *Replica Dashboard* may be overwritten during system upgrades or maintenance.
{% endhint %}
#### Customizing Dashboards
To clone the Replica Dashboard:
1. Open **Replica Dashboard**.
2. Click **Save as** in the top-right corner.
3. Enter a **Title** and optional **Description** or **Tags**.
4. Confirm **Save as new dashboard** is selected, then click **Save**.
#### Creating Your Own Dashboards
To create your own dashboard:
1. Click **Create dashboard**.
2. Click **Save** in the top-right corner.
3. Enter a **Title** and optional **Description** or **Tags**.
4. Click **Save**.
#### Requesting Updates
We use customer feedback to periodically improve the Replica Dashboard. To request changes and additions to the Replica Dashboard, contact support.
### Discover
The **Discover** tab provides access to logs generated by Replica services. It also supports filtering with [Kibana Query Language](https://www.elastic.co/guide/en/kibana/current/kuery-query.html) (KQL).
For more detail on Discover, see the [Kibana Discover documentation](https://www.elastic.co/guide/en/kibana/current/discover.html).
## Export to Splunk Integration
### Add the Replica Indices to Splunk (Optional but Recommended)
1. In Splunk, go to **Settings > Indexes**.
2. Select **New Index** and add the following:
```
replica_app_sso
replica_ve_packet_capture
replica_ve_traffic
```
### Create an HTTPS Event Collector (HEC) for Replica in Splunk
1. In Splunk, go to **Settings > HTTP Event Collector > New Token**.
2. Choose a name and select **Next**.
3. Add the indices from the previous step and select **Finish**. This is only required if you want Replica to use those index names.
4. Send the following HEC details to your Replica point of contact so they can add them to your Replica cluster:
```
HEC Server Address
HEC Server Port Number
HEC Token
If you do/don't want Replica logs tagged with the above indices
```
## Export to S3 Integration
The Export to S3 integration sends logging data to external systems that can ingest data from an S3 bucket.
Before setup, create an S3 bucket and an IAM identity with the required permissions.
All logs will be written to the provided bucket under a `logs/` directory in JSON format.
### Example IAM policy
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListBucket"
],
"Resource": "arn:aws:s3:::my-s3bucket"
},
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject"
],
"Resource": "arn:aws:s3:::my-s3bucket/*"
}
]
}
```
### Required Information
To configure this integration, prepare the following information and provide it to Replica support:
* Key ID
* Secret Key
* Bucket Name
* AWS region
# Network Monitoring
Use Replica's Network Monitoring features to inspect traffic from a virtual environment.
Replica supports two monitoring modes:
* DNS and URL logging
* Packet capture
DNS and URL logging is enabled by default. If you enable packet capture, Replica writes traffic to a `.pcap` file inside the environment instead.
You can also reassign environments after monitoring is enabled.
## DNS and URL Logging
DNS and URL logging captures requested destinations by analyzing network packets.
For HTTP traffic, Replica reads the `Host` header. For HTTPS traffic, it extracts the domain during the TLS handshake.
To review these logs, open the running environment's actions menu and select **View Network Traffic**.
| Name | Description |
| -------------------------- | ------------------------------------------------------------- |
| @timestamp | Timestamp of the network event |
| host.id | Replica-generated unique virtual environment ID |
| host.name | User-provided virtual environment name |
| host.hostname | The hostname of the Virtual Environment |
| host.namespace | The Kubernetes namespace of the Virtual Environment |
| host.ip | The internal IP address of the Virtual Environment |
| host.type | The Virtual Environment OS type (e.g., linux) |
| source.ip | The source IP address of the network traffic |
| source.port | The source port number of the network traffic |
| destination.ip | The IP address of external system |
| destination.port | The port number of external system |
| destination.address | The domain name of external system specified in HTTP traffic |
| network.transport | The transport protocol (e.g., tcp, udp) |
| frame.protocols | The protocol stack of the captured packet |
| frame.time\_epoch | The epoch time of the captured frame |
| frame.length | The length of the captured frame in bytes |
| dns.type | The type of DNS query (query or response) |
| dns.question.name | The domain name queried |
| dns.question.type | The type of DNS question (e.g., A, AAAA, CNAME) |
| dns.response.name | The domain name in the DNS response |
| dns.resolved\_ip | The resolved IP address from DNS response |
| dns.cname | The canonical name from DNS response |
| dns.nameserver | The nameserver that handled the DNS query |
| http.request.method | The HTTP request method (e.g., GET, POST) |
| http.request.uri | The HTTP request URI path |
| http.host | The HTTP host header value |
| http.response.status\_code | The HTTP response status code |
| http.user\_agent | The HTTP User-Agent header value |
| tls.client.server\_name | The domain name of external system specified in HTTPS traffic |
| tls.handshake.type | The type of TLS handshake message |
| event.kind | The kind of event (e.g., event, alert) |
| event.provider | The provider of the event (e.g., tshark) |
| event.dataset | The dataset identifier for the event |
| tags.creatorId | The user ID who created the environment |
## Packet Capture
Use packet capture for deeper traffic analysis in Wireshark.
### Enable Packet Capture
Enable **Packet Capture** in **Advanced Options** when you create the virtual environment.
### Access Packet Captures
If packet capture is enabled, Wireshark is installed automatically.
Open the `.pcap` file in the `pcap` folder on the virtual environment desktop.
### Packet Capture Content
Packet captures include IP addresses, ports, protocols, and bytes transferred.
Use [Discover](/admin-guide/logging#discover) to view, search, and export packet logs.
# SMS Devices (Physical Phone Relay)
## SMS Devices Introduction
SMS Devices extend telephony by connecting real mobile phones to the platform. Use them when software-defined numbers are not enough for your workflow.
Talk to your administrator to procure and configure physical phones.
{% hint style="info" %}
SMS Devices are an optional feature subscription and require advanced configuration.
{% endhint %}
## SMS Device / Telephony Management
SMS Devices use a physical phone together with Replica telephony features. The phone runs a Replica Android app and uses a software-defined relay number from providers such as Twilio or Bandwidth.
This setup can help when websites reject software-defined numbers, especially during account creation or two-factor authentication flows.
### Configuration
{% stepper %}
{% step %}
### Open SMS Devices
Open `Telephony` from the `Administration` menu, then select the `SMS Devices` tab.
This page shows the configured SMS devices.
{% endstep %}
{% step %}
### Create SMS Device
Click `Create SMS Device`.
{% endstep %}
{% step %}
### Provide Device Details
Enter the physical phone's `Device Number`, a `Name`, and an optional `Description`. Then select a `Relay Number`.
Use a relay number that is not already assigned for normal software-defined messaging. One relay number can serve multiple SMS devices.
{% endstep %}
{% endstepper %}
## Android App
The Android app is available in the Google Play Store and runs on supported Android devices.
After you create the SMS device in Replica, install the app on the target phone and configure it with the selected `Relay Number`.
The app does not support RCS. Disable RCS on the phone to force SMS delivery.
# Hardware Virtual Environments
## Hardware Virtual Environments Introduction
Hardware Virtual Environments let you connect physical devices to the Replica platform. This combines Replica management controls with the realism and performance of external hardware.
You can access a hardware-backed environment over VNC or RDP. Contact your Replica account manager for procurement and setup details.
{% hint style="info" %}
Available features depend on the hardware you use. Contact Replica for details about your specific device and workflow.
{% endhint %}
## Lifecycle
Hardware devices do not provision on demand like virtual environments. Instead, you add devices to a pool first, then assign them as environments when needed.
A device in the pool may have the following statuses:
| Status | Description |
| ------------ | -------------------------------------------------------------------------------- |
| available | The device is ready, but is not yet being used as an Environment |
| checked\_out | The device is assigned as an Environment |
| stale | The device was previously used and needs to be reset before it can be used again |
## Configuration
To use hardware environments, first create a device pool and add devices to it. After that, you can assign those devices to users.
{% stepper %}
{% step %}
### Adding a Pool
Hardware pools are implemented as a special type of zone. Create one pool for each device type and location you want to support.
Follow the UI to create a pool:
* Open the Hardware Devices area and select `Create Pool`.
* Enter a `Pool Description` and a `Pool Region` code for the physical location.
* Click `Create New Zone`. The new hardware pool appears in the Zones list.
{% endstep %}
{% step %}
### Adding Devices to a Pool
After you create a pool, add devices to it:
* Open the pool details (View Pool).
* Click `Create Device` to add a new device.
* On the New Device page, enter the VNC or RDP connection details on the VDI tab. Leave non-applicable fields blank.
* Provide credentials on the next page and click `Submit` to create the device.
{% endstep %}
{% step %}
### Assigning a Device
To create an environment from a device and assign it to a user or group:
* In the device list, locate the device you want to assign.
* Click the `Use as Environment` button for that device.
{% endstep %}
{% endstepper %}
# Notifications
Use Notifications to send in-platform messages to selected users or to the entire platform.
Users can read notifications later if they were offline when the message was sent. The editor supports rich formatting, including headings, lists, images, and tables.
## Notification Types
When creating a notification, choose one of the following styles. These types affect presentation only.
* Primary
* Secondary
* Warning
* Alert
* Danger
* Success
## Creating a Notification
{% stepper %}
{% step %}
### Open Notifications
Open **Notifications** from the **Administration** menu.
This page lists sent notifications and shows their content and recipients.
{% endstep %}
{% step %}
### Create a new notification
Click **Create Notification**.
{% endstep %}
{% step %}
### Fill out the form and send
Complete the form, then click **Send**.
{% hint style="info" %}
To send a notification to all users, leave the **Search users** field blank.
{% endhint %}
{% endstep %}
{% endstepper %}
## Rich Text Editor
Use the built-in rich text editor for the message body. Open it by clicking the rich text icon.
The editor supports headings, bold, italics, images, lists, and tables.
Type `/` to open the formatting toolbar for the current cursor location or selected text.
When you are done, click **Save Changes**, then press **Escape** or click outside the editor to close it.
The formatted content appears in the **Message Rich Text** field.
# Admin Guide Introduction
Replica supports self-service administration. Use this guide to manage access, configure platform services, and review operational data.
Admin pages cover user and group management, service configuration, and monitoring tools.
## Admin Navigation
Users with admin-level roles see extra items in the left-hand navigation.
Users with the **Admin** role see a dedicated administration section with links to:
* **Egress** — Create and manage egress routers and connectivity options.
* **External Storage** — Configure external storage providers such as Amazon S3 and MinIO.
* **Hardware Devices** — Manage hardware device pools.
* **Text API** — Configure the Text API integration.
* **Telephony** — Configure telephony providers.
* **Zones** — View and manage deployment zones.
* **Users** — Create and manage user accounts, roles, and credentials.
* **Groups** — Create and manage groups used to organize resources.
* **Proxy Management** — Configure proxy settings.
* **Notifications** — Send platform-wide or targeted notifications.
* **Logging** — Open the log search and analysis interface.
* **Monitoring** — Open the platform monitoring dashboard.
# User Management
Use User Management to create, update, enable, and disable users.
## Roles
Replica uses roles to control what each user can do. Users without a role cannot use Replica or view data.
See [Roles and Permissions](/admin-guide/4.4-admin-guide/user-management/roles-and-permissions).
## Groups
Groups help organize users and control resource access.
See [Group Management](/admin-guide/4.4-admin-guide/user-management/group-management) and [Resource Visibility and Assignment](/admin-guide/4.4-admin-guide/user-management/resource-visibility-and-assignment).
## Finding Users
The Users list includes a **Search** field to quickly locate a user by name, username, or email address.
## Enabled and Disabled Users
Users must be enabled to sign in. New users are enabled by default.
Disabled users cannot sign in or use the platform. Replica keeps disabled users for history and audit purposes instead of deleting them.
To change a user's status, open the Users list and select `Disable` or `Enable` in that user's actions.
{% hint style="warning" %}
Replica does not support permanent user deletion.
{% endhint %}
## Password Resets
To reset a password, select `Reset Password` in that user's actions.
You can use the generated password or set one manually. The user must change it on the next login.
# Roles and Permissions
Replica uses role-based access control. Assign one or more roles to each user to define their access.
Users inherit the combined permissions of all assigned roles.
## Roles Overview
| Role | Description |
| --------- | --------------------------------------------------------------------------------------- |
| Core | The standard set of permissions for a typical Replica User |
| API | A set of permissions that grant API access and access to Replica Jobs |
| Isolation | A limited set of permissions to trigger a VE creation and launch it |
| Guest | Limited access to interact with existing VEs only |
| Admin | An administrative set of permissions granting full access and visibility within Replica |
| Audit | A set of permissions for access to audit, log, and monitoring data |
## Replica Core Functionality
| | Core | API | Isolation | Guest | Admin | Audit |
| ------------------------ | :--: | :-: | :-------: | :---: | :---: | :---: |
| Use Environments | X | | | X | | |
| Manage Environments | X | | | | | |
| Quick-Launch Environment | X | | X | X | | |
| Manage Enclaves | X | | | | | |
| Manage File Requests | X | | | | | |
| Manage Jobs | | X | | | X | |
| Manage Profiles | X | | | | | |
| Manage Self | X | X | X | X | X | X |
| Receive Notifications | X | | X | X | X | X |
| Use External Links | X | | | X | X | |
| Use Phone Numbers | X | | | | | |
| Use Profiles | X | | | | | |
| Use Zones | X | | | | X | |
| View Images | X | | | | X | |
## Platform Administration
| | Core | API | Isolation | Guest | Admin | Audit |
| ----------------------------- | :--: | :-: | :-------: | :---: | :---: | :---: |
| Access Logging | | | | | X | X |
| Access Monitoring | | | | | X | X |
| Manage Advanced Configuration | | | | | X | |
| Manage External Links | | | | | X | |
| Manage Groups | | | | | X | |
| Manage Hardware Devices | | | | | X | |
| Manage Images | | | | | X | |
| Manage Notifications | | | | | X | |
| Manage Phone Numbers | | | | | X | |
| Manage Proxies | | | | | X | |
| Manage Routers | | | | | X | |
| Manage SMS Devices | | | | | X | |
| Manage Storage | | | | | X | |
| Manage Telephony Providers | | | | | X | |
| Manage Translation | | | | | X | |
| Manage Users | | | | | X | |
| Manage Zones | | | | | X | |
| Read Swagger Docs | | | | | X | |
| Modify Global Assignments | | | | | X | |
| Modify All Data | | | | | X | |
Modify Global Assignments
Resources assigned to `Global` are visible to all users. Only admins can assign resources to or from `Global`.
# Group Management
Use Group Management to create and update groups.
## Parents
A group can belong under another group. This parent-child structure supports up to three levels.
## Types
You can assign a type to a group to describe its purpose. The available types are:
* **Team** — A group representing a team of users.
* **Project** — A group representing a project or initiative.
## Users
Users can belong to multiple groups, one group, or no groups. Groups can also exist without members.
See [User Management](/admin-guide/4.4-admin-guide/user-management).
# Resource Visibility and Assignment
## Resource Visibility
Users can view resources assigned to:
* Themselves
* Groups they are members of
* Profiles they can see
* Global
If a user is assigned to a group, they can also view resources assigned to that group, its members, and its subgroups.
Users with the **Admin** role can view all resources in the system.
## Resource Assignment
Users can assign resources to:
* Themselves
* Groups they are members of
* Users in those Groups
* Subgroups (and the Users in them) of those Groups
* Profiles they can see
If a user is assigned to a group, they can also assign resources to that group, its members, and its subgroups.
Users with the **Admin** role can assign resources to any user, group, or profile, including `Global`.
### Resource Type Specific Rules
* Routers cannot be assigned to profiles.
* Profiles cannot be assigned to profiles.
* Groups can only be assigned to users.
# User Policies
{% hint style="info" %}
Replica manages authentication with Keycloak. Default password, session, and login settings follow common security baselines. Replica SSO administrators handle custom changes. Contact your account manager for exceptions or review the [Keycloak documentation](https://www.keycloak.org/documentation).
{% endhint %}
## User Policies
### Passwords
* Minimum password length: 15 characters
### Login Lockouts (Brute Force Detection)
Default settings:
* Max login failures: 30 — after this point a lockout is triggered.
* Permanent lockout: disabled
* Wait increment: 1 minute before a lockout ends
* Max failure count reset: after 12 hours
* Quick login check: 1 second. Faster attempts trigger a lockout.
* Minimum wait after a quick login: 1 minute before the lockout ends
### Login Timeout Settings
Default settings:
* Login Timeout: 30 minutes
* Login action timeout: 5 minutes
### SSO Session Settings
Default settings:
* SSO Session Idle: 30 minutes
* SSO Session Max: 10 minutes
# Butler Admin Guide
This page lists default Butler settings and Butler audit data.
## Clipboard Configuration
| Description | Default |
| ------------------------------------ | ---------------- |
| Enable or disable Clipboard Transfer | Enabled |
| User host clipboard operations | Upload, Download |
| Environment clipboard operations | Upload, Download |
| Clipboard data expiration | 1 hour |
## Translation Configuration
| Description | Default |
| ---------------------------------- | ------- |
| Enable or disable text Translation | Enabled |
## File Configuration
These are the default Butler file transfer settings.
{% hint style="info" %}
Butler data transfers are performed over encrypted channels and Butler Storage encrypts data at rest.
{% endhint %}
| Description | Default |
| ---------------------------------------------- | ---------------------------------------- |
| Enable or disable File Transfer | Enabled |
| User host file operations | List, Upload, Download, Delete, Copy |
| Environment file operations | List, Upload, Download, Delete, Copy |
| The maximum file size allowed for upload | 400MB |
| The maximum number of files allowed per upload | 10 |
| Anti-Virus (AV) scanning | Enabled |
| Anti-Virus (AV) ignore | None |
| Infected file download | Blocked (Except in malware environments) |
| File Encryption at Rest | Enabled |
| File Encryption Algorithm | AES-256 |
| File Integrity Verification | Disabled |
| File Integrity Algorithm | None (options available) |
## Environment Events
Butler can send actions into Replica environments. If environment events are enabled, the environment receives and processes event messages. Use the Butler API sample for programmatic access.
| Description | Default |
| ------------------------------------------- | ----------------------- |
| Enable or disable Environment Events | Disabled |
| Enable or disable Environment File Autosync | Disabled |
| Environment File Autosync directory | Desktop Files directory |
### File Events
When file events are enabled, Butler can automatically transfer uploaded files into the environment.
### Browser Events
When browser events are enabled, Butler can open a URL inside a Replica environment.
## File History
Butler records file activity in its history and logging systems. Each event includes a UTC timestamp.
#### Fields
Butler resource history entries include the following fields:
| Name | Description |
| -------------- | ---------------------------------------------------- |
| resource\_id | A unique identifier assigned to the Resource |
| resource\_path | The Resource path in Butler Storage |
| entity\_type | The Entity Type that performed the action |
| entity\_id | The Entity Id that performed the action |
| accessed | The timestamp of when the action was performed (UTC) |
| operation | The action that was performed |
#### Entity Types
| Name | Description |
| ------- | --------------------------------------- |
| User | A Replica user plus their User Id |
| Group | A Replica group plus their Group Id |
| Profile | A Replica profile plus their Profile Id |
#### Operation Types
| Name | Description |
| -------- | --------------------------------------------------------------- |
| Delete | The resource was deleted from Butler Storage |
| Download | The resource was downloaded from Butler Storage |
| Transfer | The resource was transferred between Enclaves in Butler Storage |
| Upload | The resource was created or updated in Butler Storage |
Resource History Sample
```json
[
{
"resource_id": "resource_id",
"resource_path": "resource_path",
"entity_type": "entity_type",
"entity_id": "entity_id",
"accessed": "2023-10-30T17:14:08.000Z",
"operation": "upload"
},
{
"resource_id": "resource_id",
"resource_path": "resource_path",
"entity_type": "entity_type",
"entity_id": "entity_id",
"accessed": "2023-10-30T17:14:22.415Z",
"operation": "download"
},
{
"resource_id": "resource_id",
"resource_path": "resource_path",
"entity_type": "entity_type",
"entity_id": "entity_id",
"accessed": "2023-10-30T17:16:43.501Z",
"operation": "delete"
}
]
```
***
### File Event Logging
| Name | Description |
| ------ | ------------------------------------- |
| Get | Get a Resource from Butler Storage |
| Put | Save a Resource in Butler Storage |
| Delete | Delete a Resource from Butler Storage |
Transfer Sample
```json
{
"@timestamp": "2023-10-30T17:54:57.925Z",
"log.level": "info",
"message": "Auth credentials accepted",
"ecs": { "version": "8.10.0" },
"event": {
"kind": "event",
"type": ["allowed"],
"category": ["authentication"],
"outcome": "success"
},
"http": {
"version": "1.1",
"request": {
"method": "PUT",
"headers": {
"host": "replicacyber.com",
"x-request-id": "8709f71e96fd500b5e3433bf0051ef44",
"x-real-ip": "1.2.3.4",
"x-forwarded-for": "1.2.3.4",
"x-forwarded-host": "replicacyber.com",
"x-forwarded-port": "443",
"x-forwarded-proto": "https",
"x-forwarded-scheme": "https",
"x-requested-with": "XMLHttpRequest",
"x-scheme": "https",
"content-type": "multipart/form-data; boundary=---------------------------1804628349855675348442767821",
"user-agent": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/119.0",
"accept": "application/json",
"accept-language": "en-US,en;q=0.5",
"accept-encoding": "gzip, deflate, br",
"cookie": "redacted"
},
"body": { "bytes": 6165 }
},
"response": {
"status_code": 200,
"headers": {
...
}
}
},
"url": {
"path": "/butler/api/v1/transfer/resources/mY9bUtVCxc7F-9R6MHOgA-SQZJMD5Bt0V-pUAG2cVnA/test.txt",
"domain": "replicacyber.com"
},
"client": {
"address": "1.2.3.4",
"ip": "1.2.3.4",
"port": 36600
},
"user_agent": {
"original": "Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/119.0"
},
"user": {
"authenticated": true,
"id": "a123456-1234-1234-1234-123456789123",
"email": "username@replicacyber.com",
"full_name": "User Name"
}
}
```
Auth Sample
```json
{
"@timestamp": "2023-10-30T17:52:41.164Z",
"log.level": "info",
"message": "Auth credentials accepted",
"ecs": {
"version": "8.10.0"
},
"event": {
"kind": "event",
"type": ["allowed"],
"category": ["authentication"],
"outcome": "success"
},
"http": {
"version": "1.1",
"request": {
"method": "GET",
"headers": {
"host": "replicacyber.com",
"x-request-id": "39a4d4d54dd906fdc942a239df23a26a",
"x-real-ip": "1.2.3.4",
"x-forwarded-for": "1.2.3.4",
"x-forwarded-host": "replicacyber.com",
"x-forwarded-port": "443",
"x-forwarded-proto": "https",
"x-forwarded-scheme": "https",
"x-scheme": "https",
"accept": "application/json",
"user-agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36",
...
}
},
"response": {
"status_code": 200,
...
}
},
"url": {
"path": "/butler/api/v1/enclaves",
"domain": "replicacyber.com"
},
"client": {
"address": "1.2.3.4",
"ip": "1.2.3.4",
"port": 48354
},
"user_agent": {
"original": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36"
},
"user": {
"authenticated": true,
"id": "a123456-1234-1234-1234-123456789123",
"email": "username@replicacyber.com",
"full_name": "User Name"
}
}
```
Login Sample
```json
{
"@timestamp": "2023-10-30T17:02:07.450Z",
"log.level": "info",
"message": "User John Smith logged into butler",
"ecs": {
"version": "8.10.0"
},
"event": {
"kind": "event",
"type": ["user"],
"category": ["authentication"],
"outcome": "success"
}
}
```
# Data Management
This page summarizes where data is stored and how key platform data is retained.
## Replica Environment
### Virtual Environment Storage
Each virtual environment includes a home directory that persists for the life of that environment.
Data stored outside the home directory may be removed when the environment is not running. When an environment is deleted, all data inside it is permanently removed.
## Replica Platform
Replica performs nightly backups of critical platform data to isolated external storage.
### Butler
See [Butler Admin Guide](/admin-guide/butler-admin-guide) for Butler storage, transfer, and audit details.
### Egress
See [Egress data policy](/admin-guide/egress#egress-data-policy).
### Logging
See [Logging data management](/admin-guide/logging#logging-data-management).
### Telephony
Telephony data for software-defined resources is retained for at least one year.
# Limits
Replica enforces limits to preserve shared resources and maintain platform availability. Some limits vary by environment type and backing infrastructure.
{% hint style="info" %}
Some limits can be adjusted. Contact Replica Support for details. Your organization may also have limits that differ from the defaults below.
{% endhint %}
## Storage Limits
| Object | Description | Limit |
| ------------------------------------- | ----------------------------------------------------- | --------------------------------- |
| Virtual Environment (container-based) | Maximum amount of data stored in `/home/user` | 500 GB shared across all VEs |
| Virtual Environment (container-based) | Maximum amount of data stored outside of `/home/user` | 50 GB shared across node |
| Virtual Environment (VM-based) | Total storage limit | 30 GB |
| Virtual Environment (Malware-type) | Total storage limit | 30 GB - 50 GB, depending on image |
| Physical Mobile Device | Total storage limit | 128 GB |
{% hint style="info" %}
Available storage may be lower than the stated limit because of preinstalled system or application data.
{% endhint %}
## Memory Limits
| Object | Description | Limit |
| ------------------------------------- | -------------------------------- | ----- |
| Virtual Environment (container-based) | Total memory limit | 5 GB |
| Virtual Environment (VM-based) | Memory limit, not including swap | 4 GB |
| Virtual Environment (Malware-type) | Memory limit, not including swap | 8 GB |
## Transfer Limits
| Object | Description | Limit |
| ---------------------- | ------------------------ | ----------------------------- |
| Virtual Environment | Egress data transfer | unlimited |
| Virtual Environment | Proxy data transfer | subject to subscription terms |
| Enclave | Maximum file upload size | 400 MB |
| Butler Files | Maximum file upload size | 400 MB |
| Physical Mobile Device | SMS/MMS limit | unlimited |
| Physical Mobile Device | Data transfer limit | unlimited (via WiFi) |
# Egress
## Egress Introduction
Egress controls where outbound internet traffic leaves the Replica platform. The egress location strongly affects the apparent origin and signature of your activity.
This matters because many websites classify, filter, or block visitors based on source network details.
### Egress Types
Replica may be configured with several types of Egress options, including but not limited to:
* Commercial VPN provider Egress
* Cloud VPN Egress
* Bring-your-own VPN Egress
* White-line Egress
{% hint style="info" %}
Each option has tradeoffs. Contact your Replica representative if you need help choosing the right one.
{% endhint %}
### Egress Data Policy
Replica egress protocols create encrypted channels between your platform and the egress servers. Replica provisions egress resources on isolated infrastructure.
Replica does not log or retain egress traffic data in transit.
### What impact does Egress have on my attribution/signature?
Observers can identify traffic sources in several ways. The most common method is an IP address lookup against commercial or public IP databases.
These databases often include location, provider, organization, and whether an IP belongs to a VPN or cloud platform.
Websites rarely disclose their exact filtering logic. If a site blocks traffic based on IP reputation or geography, using a different egress may help.
Egress also affects other parts of your activity signature. By default, Replica aligns environment locale settings with the languages used in the selected egress location.
### Bring-your-own VPN Egress
You can bring your own VPN provider and use it as an egress location in Replica. Replica supports WireGuard and OpenVPN.
{% hint style="danger" %}
Your VPN provider may limit how many users can share one connection. Make sure your Replica configuration stays within that provider's terms of service.
{% endhint %}
## Create Egress
To create a new egress point, gather valid WireGuard or OpenVPN configuration details from your provider. If both are available, WireGuard is usually the better choice for performance.
### WireGuard
{% stepper %}
{% step %}
#### Access Egress
Open **Egress** from the **Administration** menu. The page shows existing egress locations as cards.
Click the **Create Wireguard** button to open the New Egress Details form.
{% endstep %}
{% step %}
#### Router settings
Fill out the following fields:
* **Router Name**: Choose a name that will be displayed to users to select this Egress.
* **Router Type**: Select `Egress`.
* **Router Status**: Select `Active` to enable this egress.
* **Disable Egress Verification**: Enable this option to bypass Egress verification checks.
* **Hot Swap**: Enable this option to allow a running environment to change routers.
{% endstep %}
{% step %}
#### Provider settings
Click **Next** to open the provider page, then fill out:
* **Provider Name**: Enter the name of your Egress provider.
* **Provider Type**: Select the provider type. `VPN` is the most common choice.
{% endstep %}
{% step %}
#### Configuration
Click **Next** to open the configuration page.
* Paste the contents of your Wireguard configuration file into the **Configuration** field.
{% endstep %}
{% step %}
#### Create
Click **Next** to create the egress. The new egress appears in the card list.
Assign the egress to a user or group before they can use it.
{% endstep %}
{% endstepper %}
### OpenVPN
{% stepper %}
{% step %}
#### Access Egress
Open **Egress** from the **Administration** menu. The page shows existing egress locations as cards.
Click the **Create OpenVPN** button to open the New Egress Details form.
{% endstep %}
{% step %}
#### Router settings
Fill out the following fields:
* **Router Name**: Choose a name that will be displayed to users to select this Egress.
* **Router Type**: Select `Egress`.
* **Router Status**: Select `Active` to enable this egress.
* **Disable Egress Verification**: Enable this option to bypass Egress verification checks.
* **Hot Swap**: Enable this option to allow a running environment to change routers.
{% endstep %}
{% step %}
#### Provider settings
Click **Next** to open the provider page, then fill out:
* **Provider Name**: Enter the name of your Egress provider.
* **Provider Type**: Select the provider type. `VPN` is the most common choice.
{% endstep %}
{% step %}
#### Certificates & Configuration
Click **Next** to open the configuration page, then fill out:
* **CA Certificate**: Paste the contents of your CA certificate here, if provided by your VPN provider.
* **Key Certificate**: Paste the contents of your private Key Certificate here, if provided by your VPN provider.
* **Key**: Paste the contents of your private key here, if provided by your VPN provider.
* **Configuration**: Paste the contents of your OpenVPN configuration file here. This is a mandatory field.
{% endstep %}
{% step %}
#### Locale Configuration
Click **Next** to open the locale configuration page. All fields on this page are optional.
{% endstep %}
{% step %}
#### Create
Click **Submit** to create the egress. The new egress appears in the card list.
Assign the egress to a user or group before they can use it.
{% endstep %}
{% endstepper %}
## Edit Egress
Each egress card includes action icons in the top-right corner. Hover over an icon to see its action.
# Zones
Zones are an optional feature that define external deployment regions and infrastructure configurations available on the Replica platform. Each zone maps to a compute provider region and enables new types of Virtual Environments to be launched.
> **Note:** Zones are typically configured and managed by Replica. Under normal circumstances, zone settings should not be created or modified without guidance from your Replica representative.
## Viewing Zones
Open **Zones** from the admin navigation to see a list of all configured deployment zones.
The zones list shows a table with the following columns:
| Column | Description |
| ---------------- | ---------------------------------------------------- |
| id | The unique identifier for the zone. |
| name | The display name of the zone. |
| iaas | The infrastructure provider |
| region | The provider region where the zone is deployed. |
| status | The current operational status of the zone. |
| supports Malware | Whether the zone supports Malware environment types. |
| created Time | When the zone was created. |
| Actions | Available management actions for the zone. |
## Creating a Zone
Click **Create Zone** to configure a new deployment zone. Zone creation requires coordination with your Replica representative and is typically done during onboarding or capacity expansion.
## Zones and Malware Environments
Zones that support Malware are configured with the necessary isolation and security controls required for malware analysis workflows. When creating a Virtual Environment with the **Malware** use-case type, only zones that support malware are available for selection.
# Logging
Use Logging to search, analyze, and export Replica logs.
## Log Types
### Replica Environment
Virtual environment activity is logged by event type. For DNS, URL, and packet logging details, see [Network Monitoring](/admin-guide/4.4-admin-guide/network-monitoring).
| Name | Index | Description | Default Retention |
| ----------------- | ----------- | ---------------------------------------------------------------------------------------------- | ----------------- |
| System | env.system | Environment Operating System start up events | 30 days |
| DNS & URL Logging | env.traffic | Capture and extract URLs from network packets and Environment Domain Name System (DNS) queries | 1 day |
### Replica Platform
| Name | Elasticsearch Indices |
| ---------------- | ----------------------------------------- |
| Auth (SSO) | app.sso |
| Egress | app.wharf, app.rest-api |
| Entity | app.user-service, app.rest-api |
| Environment | app.ic2, app.hive, app.keel, app.rest-api |
| Image | app.hull |
| Permissions | app.user-service |
| Profiles | app.profile-memory, app.rest-api |
| Telephony | app.telephony |
| VE Clipboard | app.butler |
| VE Files | app.butler |
| VE Jobs | app.butler, app.keel |
| General VE Usage | env.usage |
| VE Translations | app.butler |
## Logging Data Management
Replica snapshots Elasticsearch indices to secondary backup volumes. Snapshots are typically retained for 30 to 90 days.
All Replica logs include timestamps synchronized through Amazon Time Sync.
### Retention Policies
| Index Name | Retention |
| ------------------ | --------- |
| app.butler | 180 days |
| app.hull | 30 days |
| app.ic2 | 90 days |
| app.keel | 90 days |
| app.profile-memory | 90 days |
| app.rest-api | 180 days |
| app.sso | 180 days |
| app.telephony | 30 days |
| app.user-service | 180 days |
| app.wharf | 180 days |
| env.system | 30 days |
| env.traffic | 1 day |
| env.usage | 90 days |
## Accessing Logging
Open **Logging** from the **Administration** menu to access the logging home screen.
### Dashboards
#### Accessing Dashboards
To open the preloaded dashboard, click the menu button in the top-left corner and select **Dashboard** under **Analytics**.
The default *Replica Dashboard* includes built-in visualizations that update as new data arrives. You can clone it or create your own dashboard.
{% hint style="warning" %}
Changes to the default *Replica Dashboard* may be overwritten during system upgrades or maintenance.
{% endhint %}
#### Customizing Dashboards
To clone the Replica Dashboard:
1. Open **Replica Dashboard**.
2. Click **Save as** in the top-right corner.
3. Enter a **Title** and optional **Description** or **Tags**.
4. Confirm **Save as new dashboard** is selected, then click **Save**.
#### Creating Your Own Dashboards
To create your own dashboard:
1. Click **Create dashboard**.
2. Click **Save** in the top-right corner.
3. Enter a **Title** and optional **Description** or **Tags**.
4. Click **Save**.
#### Requesting Updates
We use customer feedback to periodically improve the Replica Dashboard. To request changes and additions to the Replica Dashboard, contact support.
### Discover
The **Discover** tab provides access to logs generated by Replica services. It also supports filtering with [Kibana Query Language](https://www.elastic.co/guide/en/kibana/current/kuery-query.html) (KQL).
For more detail on Discover, see the [Kibana Discover documentation](https://www.elastic.co/guide/en/kibana/current/discover.html).
## Export to Splunk Integration
### Add the Replica Indices to Splunk (Optional but Recommended)
1. In Splunk, go to **Settings > Indexes**.
2. Select **New Index** and add the following:
```
replica_app_sso
replica_ve_packet_logging
replica_ve_packet_capture
replica_ve_traffic
```
### Create an HTTPS Event Collector (HEC) for Replica in Splunk
1. In Splunk, go to **Settings > HTTP Event Collector > New Token**.
2. Choose a name and select **Next**.
3. Add the indices from the previous step and select **Finish**. This is only required if you want Replica to use those index names.
4. Send the following HEC details to your Replica point of contact so they can add them to your Replica cluster:
```
HEC Server Address
HEC Server Port Number
HEC Token
If you do/don't want Replica logs tagged with the above indices
```
## Export to S3 Integration
The Export to S3 integration sends logging data to external systems that can ingest data from an S3 bucket.
Before setup, create an S3 bucket and an IAM identity with the required permissions.
All logs will be written to the provided bucket under a `logs/` directory in JSON format.
### Example IAM policy
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListBucket"
],
"Resource": "arn:aws:s3:::my-s3bucket"
},
{
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject"
],
"Resource": "arn:aws:s3:::my-s3bucket/*"
}
]
}
```
### Required Information
To configure this integration, prepare the following information and provide it to Replica support:
* Key ID
* Secret Key
* Bucket Name
* AWS region
# Network Monitoring
Use Replica's Network Monitoring features to inspect traffic from a virtual environment.
Replica supports two monitoring modes:
* DNS and URL logging
* Packet capture
DNS and URL logging is enabled by default. If you enable packet capture, Replica writes traffic to a `.pcap` file inside the environment instead.
You can also reassign environments after monitoring is enabled.
## DNS and URL Logging
DNS and URL logging captures requested destinations by analyzing network packets.
For HTTP traffic, Replica reads the `Host` header. For HTTPS traffic, it extracts the domain during the TLS handshake.
To review these logs, open the running environment's actions menu and select **View Network Traffic**.
| Name | Description |
| -------------------------- | ------------------------------------------------------------- |
| @timestamp | Timestamp of the network event |
| host.id | Replica-generated unique virtual environment ID |
| host.name | User-provided virtual environment name |
| host.hostname | The hostname of the Virtual Environment |
| host.namespace | The Kubernetes namespace of the Virtual Environment |
| host.ip | The internal IP address of the Virtual Environment |
| host.type | The Virtual Environment OS type (e.g., linux) |
| source.ip | The source IP address of the network traffic |
| source.port | The source port number of the network traffic |
| destination.ip | The IP address of external system |
| destination.port | The port number of external system |
| destination.address | The domain name of external system specified in HTTP traffic |
| network.transport | The transport protocol (e.g., tcp, udp) |
| frame.protocols | The protocol stack of the captured packet |
| frame.time\_epoch | The epoch time of the captured frame |
| frame.length | The length of the captured frame in bytes |
| dns.type | The type of DNS query (query or response) |
| dns.question.name | The domain name queried |
| dns.question.type | The type of DNS question (e.g., A, AAAA, CNAME) |
| dns.response.name | The domain name in the DNS response |
| dns.resolved\_ip | The resolved IP address from DNS response |
| dns.cname | The canonical name from DNS response |
| dns.nameserver | The nameserver that handled the DNS query |
| http.request.method | The HTTP request method (e.g., GET, POST) |
| http.request.uri | The HTTP request URI path |
| http.host | The HTTP host header value |
| http.response.status\_code | The HTTP response status code |
| http.user\_agent | The HTTP User-Agent header value |
| tls.client.server\_name | The domain name of external system specified in HTTPS traffic |
| tls.handshake.type | The type of TLS handshake message |
| event.kind | The kind of event (e.g., event, alert) |
| event.provider | The provider of the event (e.g., tshark) |
| event.dataset | The dataset identifier for the event |
| tags.creatorId | The user ID who created the environment |
## Packet Capture
Use packet capture for deeper traffic analysis in Wireshark.
### Enable Packet Capture
Enable **Packet Capture** in **Advanced Options** when you create the virtual environment.
### Access Packet Captures
If packet capture is enabled, Wireshark is installed automatically.
Open the `.pcap` file in the `pcap` folder on the virtual environment desktop.
### Packet Capture Content
Packet captures include IP addresses, ports, protocols, and bytes transferred.
Use [Discover](/admin-guide/logging#discover) to view, search, and export packet logs.
# SMS Devices (Physical Phone Relay)
## SMS Devices Introduction
SMS Devices extend telephony by connecting real mobile phones to the platform. Use them when software-defined numbers are not enough for your workflow.
Talk to your administrator to procure and configure physical phones.
{% hint style="info" %}
SMS Devices are an optional feature subscription and require advanced configuration.
{% endhint %}
## SMS Device / Telephony Management
SMS Devices use a physical phone together with Replica telephony features. The phone runs a Replica Android app and uses a software-defined relay number from providers such as Twilio or Bandwidth.
This setup can help when websites reject software-defined numbers, especially during account creation or two-factor authentication flows.
### Configuration
{% stepper %}
{% step %}
### Open SMS Devices
Open `Telephony` from the `Administration` menu, then select the `SMS Devices` tab.
This page shows the configured SMS devices.
{% endstep %}
{% step %}
### Create SMS Device
Click `Create SMS Device`.
{% endstep %}
{% step %}
### Provide Device Details
Enter the physical phone's `Device Number`, a `Name`, and an optional `Description`. Then select a `Relay Number`.
Use a relay number that is not already assigned for normal software-defined messaging. One relay number can serve multiple SMS devices.
{% endstep %}
{% endstepper %}
## Android App
The Android app is available in the Google Play Store and runs on supported Android devices.
After you create the SMS device in Replica, install the app on the target phone and configure it with the selected `Relay Number`.
The app does not support RCS. Disable RCS on the phone to force SMS delivery.
# Hardware Virtual Environments
## Hardware Virtual Environments Introduction
Hardware Virtual Environments let you connect physical devices to the Replica platform. This combines Replica management controls with the realism and performance of external hardware.
You can access a hardware-backed environment over VNC or RDP. Contact your Replica account manager for procurement and setup details.
{% hint style="info" %}
Available features depend on the hardware you use. Contact Replica for details about your specific device and workflow.
{% endhint %}
## Lifecycle
Hardware devices do not provision on demand like virtual environments. Instead, you add devices to a pool first, then assign them as environments when needed.
A device in the pool may have the following statuses:
| Status | Description |
| ------------ | -------------------------------------------------------------------------------- |
| available | The device is ready, but is not yet being used as an Environment |
| checked\_out | The device is assigned as an Environment |
| stale | The device was previously used and needs to be reset before it can be used again |
## Configuration
To use hardware environments, first create a device pool and add devices to it. After that, you can assign those devices to users.
{% stepper %}
{% step %}
### Adding a Pool
Hardware pools are implemented as a special type of zone. Create one pool for each device type and location you want to support.
Follow the UI to create a pool:
* Open the Hardware Devices area and select `Create Pool`.
* Enter a `Pool Description` and a `Pool Region` code for the physical location.
* Click `Create New Zone`. The new hardware pool appears in the Zones list.
{% endstep %}
{% step %}
### Adding Devices to a Pool
After you create a pool, add devices to it:
* Open the pool details (View Pool).
* Click `Create Device` to add a new device.
* On the New Device page, enter the VNC or RDP connection details on the VDI tab. Leave non-applicable fields blank.
* Provide credentials on the next page and click `Submit` to create the device.
{% endstep %}
{% step %}
### Assigning a Device
To create an environment from a device and assign it to a user or group:
* In the device list, locate the device you want to assign.
* Click the `Use as Environment` button for that device.
{% endstep %}
{% endstepper %}
# Notifications
Use Notifications to send in-platform messages to selected users or to the entire platform.
Users can read notifications later if they were offline when the message was sent. The editor supports rich formatting, including headings, lists, images, and tables.
## Notification Types
When creating a notification, choose one of the following styles. These types affect presentation only.
* Primary
* Secondary
* Warning
* Alert
* Danger
* Success
## Creating a Notification
{% stepper %}
{% step %}
### Open Notifications
Open **Notifications** from the **Administration** menu.
This page lists sent notifications and shows their content and recipients.
{% endstep %}
{% step %}
### Create a new notification
Click **Create Notification**.
{% endstep %}
{% step %}
### Fill out the form and send
Complete the form, then click **Send**.
{% hint style="info" %}
To send a notification to all users, leave the **Search users** field blank.
{% endhint %}
{% endstep %}
{% endstepper %}
## Rich Text Editor
Use the built-in rich text editor for the message body. Open it by clicking the rich text icon.
The editor supports headings, bold, italics, images, lists, and tables.
Type `/` to open the formatting toolbar for the current cursor location or selected text.
When you are done, click **Save Changes**, then press **Escape** or click outside the editor to close it.
The formatted content appears in the **Message Rich Text** field.
# Replica Implementation Guide
This guide is for anyone involved in planning and rolling out Replica: project leads, IT teams, compliance and audit stakeholders, and platform administrators.
### Overview
Replica provides secure, isolated virtual environments delivered in the browser. Users can browse, research, analyze, or run automated tasks without exposing their identity, device, or infrastructure to the public internet. All traffic exits through a configurable egress point.
Replica is a SaaS application. It runs over the public internet. No special hardware or local software is required. Users sign in at their instance URL and get a full desktop experience over VDI in the browser.
```mermaid
flowchart LR
user1[User's Browser]
user2[User's Browser]
user3[User's Browser]
vpn1[Commercial VPN Egress]
vpn2[Cloud VPN Egress]
vpn3[Residential Proxy Egress]
internet([Public Internet])
subgraph Replica
direction LR
subgraph ve1[Virtual Environment]
os1[OS/Applications/Files]
end
subgraph ve2[Virtual Environment]
os2[OS/Applications/Files]
end
subgraph ve3[Virtual Environment]
os3[OS/Applications/Files]
end
end
ve1 --- vpn1 --- internet
ve2 --- vpn2 --- internet
ve3 --- vpn3 --- internet
user1 -- VDI stream --- ve1
user2 -- VDI stream --- ve2
user3 -- VDI stream --- ve3
```
Each user's browser connects to a Virtual Environment over VDI. Internet traffic leaves through a separately configured egress point. The user's real network is never exposed to the public internet.
Common deployment patterns include:
* **Research and OSINT teams** who need attribution-managed workspaces
* **Security teams** running malware analysis or dynamic execution in isolated environments
* **Operations teams** automating recurring data collection via scheduled Jobs
* **Training environments** for analysts working in a contained space
Talk with your Replica representative early. They can help map your workflows to the Operational View that fits your organization.
### Things to Think About Before You Start
Replica is quick to deploy. A few early decisions will make onboarding smoother:
#### Who will use it, and how?
Identify your user types and what they will do in Replica. That will shape the environments you provision and the roles you assign. Also decide who will act as Platform Admin. That person will manage users, groups, and settings over time.
#### Access structure
Replica uses role-based access control. Plan that structure before you provision users.
Questions to answer:
* Which users need standard access (Core role) vs. API/automation access vs. admin access?
* Do you have multiple teams or operational units that should be organized into groups?
Groups make resource visibility and assignment much easier to manage at scale.
See [Roles and Permissions](/admin-guide/user-management/roles-and-permissions) for more.
#### Egress strategy
Egress determines where your environments' internet traffic appears to originate. That directly affects how your team can operate online. Replica supports several egress types, each with tradeoffs in geography, attribution, and performance. You'll review this with your Replica representative during onboarding . See [Egress](/admin-guide/egress).
#### VE lifecycle policy
There is no fixed expiration on Virtual Environments. They can run for minutes or for months. Best practice is to delete a VE when its task is complete. Decide the policy that works best for your goals before users start creating environments. Cleanup habits are easier to establish early. See [Virtual Environment Lifetime and Best Practices](/faqs/virtual-environment-lifetime-and-best-practices).
#### Any integrations?
If you need SSO, external log storage, or telephony features, flag that early. These features have prerequisites that should be in place before onboarding. Your Replica representative can help you plan them.
### Technical Requirements and Considerations for IT Teams
Replica runs entirely in the browser. There is no software to install and no on-premise infrastructure to manage. IT teams still play a key role during rollout.
#### Technical requirements
For the best experience, each user's connection should meet these requirements:
| Requirement | Specification |
| ----------------- | -------------------------------------------------------------------- |
| Connection speed | Broadband (≥ 25/3 Mbps) |
| Latency | < 100ms (required) / < 50ms (recommended) / < 25ms (preferred) |
| Connection method | Direct internet connection (public preferred) |
| Firewall | Allow all HTTPS, WebSocket, and QUIC to the Replica instance address |
| Browser | Latest stable version of Chrome or Edge |
Users should connect directly to Replica. They should not connect through a corporate VPN, remote browser, virtualized desktop, or another VDI solution such as Citrix. Those layers duplicate Replica functionality, add latency, and can cause compatibility issues. If your organization uses traffic inspection or filtering software, such as Zscaler or Akamai, allowlist the Replica instance address.
#### Single Sign-On
Replica supports SSO through SAML 2.0 and OpenID Connect. You can require SSO for some users or all users. You can also map roles automatically from your identity provider to Replica roles, so users receive the right access without manual assignment.
Replica's team handles SSO setup. If your organization requires it, contact support early. It should be in place before users are provisioned. If you are not using SSO, Replica manages authentication natively with configurable password and session policies. See [User Policies](/admin-guide/user-management/user-policies).
#### Log export and SIEM integration
Replica can export log data to Splunk or to an external S3-compatible bucket. An external bucket can feed a SIEM or another log pipeline. If your organization has log retention requirements, set this up before go-live. See [Logging](/admin-guide/logging).
### Compliance & Audit
Replica is designed for auditability. This section summarizes what compliance teams and auditors should know.
#### What Replica logs
Replica captures a broad range of platform activity. That includes authentication events, user and environment actions, file transfers, clipboard usage, DNS queries, and select network traffic. Retention varies by category, from 1 day for packet captures to 180 days for authentication and API activity. See [Logging](/admin-guide/logging) for the full schedule.
#### The Audit role
Users with the Audit role have read-only access to logs and the monitoring dashboard. They cannot modify platform configuration or user data. Assign this role to compliance or audit staff who need visibility without admin privileges. See [Roles and Permissions](/admin-guide/user-management/roles-and-permissions).
#### Data and egress privacy
Replica does not log or retain egress traffic in transit. The platform routes traffic through egress, but it does not inspect or store the content. In production environments, all Replica Cyber system access to your instance is audited. Access occurs only when needed for support, maintenance, or security response. See [Can Replica Cyber see our activity?](https://docs.replicacyber.com/faqs/can-replica-cyber-see-our-activity)
#### Security posture
Replica undergoes regular security audits and penetration testing. Full trust and compliance documentation is available at [trust.replicacyber.com](https://trust.replicacyber.com/).
### Preparing Your Users
Before first login, a little preparation prevents a lot of support friction.
#### Connection requirements
Users should connect to Replica directly. Traffic inspection or filtering software should be configured to allowlist all traffic to your Replica instance address without filtering overhead. See [Technical Requirements](#technical-requirements).
#### Troubleshooter Portal
Have trial users run the [Troubleshooter Portal](/user-guide/troubleshooter). It checks system and network configuration and surfaces issues early. It takes a few minutes and saves a lot of back-and-forth.
#### Set expectations before go-live
Send a short note before first login that covers:
* What Replica is and what they'll be using it for
* The correct instance URL
* What to expect on first login, such as any preconfigured images or environments, and custom configurations
* Where to go if something doesn't work
### Onboarding
#### Admin readiness
Your Platform Admin should be comfortable with the [Admin Guide](https://docs.replicacyber.com/admin-guide/) before supporting end users. They should know how to manage users and groups, and access monitoring and logs.
#### End user training
Operators should be comfortable with four things:
1. Logging in and navigating to their Virtual Environments
2. Launching, using, and deleting a VE
3. Using file and clipboard transfer (if applicable)
4. How to reach out for support
The [User Guide](https://docs.replicacyber.com/user-guide/) covers all of this. Share it directly with operators.
#### Developers and automation users
Users working with Jobs or Enclave Scripts should review the [Developer Guide](https://docs.replicacyber.com/developer-guide/) before building production workflows.
#### Consider a pilot
If you are onboarding a larger team, run a small pilot first. Have that group work through real workflows before full rollout. Pilot feedback often surfaces configuration tweaks and training gaps that are much easier to fix early.
### Go-Live Checklist
Use this as a final check before cutting over to full deployment.
**Access and Users**
* [ ] Platform Admin identified
* [ ] All user accounts created with correct roles assigned
* [ ] Groups created and populated
* [ ] Audit role assigned to compliance/security owner
**IT & Security**
* [ ] Network allowlist confirmed (Replica instance address reachable without traffic inspection interference)
* [ ] SSO configured and tested (if applicable)
* [ ] Log export configured and verified (if applicable)
**Environments**
* [ ] VE images assigned to users/groups
* [ ] VE lifecycle and best practices communicated to users
**User Readiness**
* [ ] Test/trial users have run the Troubleshooter Portal
* [ ] Orientation/onboarding completed
**Support**
* [ ] Support contact shared with all users (`support@replicacyber.com`)
* [ ] Internal escalation path documented
***
### Sustaining the Deployment
A few areas are worth reviewing regularly after go-live:
**User management:** Add users, adjust roles as responsibilities change, and disable departing users promptly. Replica retains disabled users for audit history rather than deleting them.
**VE hygiene:** Reinforce your VE lifecycle policy. Environments that outlive their purpose accumulate unnecessary risk.
**Egress:** Review your egress configuration periodically as operational needs evolve.
**Monitoring and audit:** Make sure your compliance owner has access to logs and is reviewing them on a regular cadence.
**Stay in touch with your Replica representative:** Replica is actively developed. Your account manager is the best source for new features and how they might support your workflows.
# Replica Developer Guide
The Replica platform includes developer features enabling you to automatically run code within your environment, create jobs that run automatically on a schedule, and control the flow of data in and out of Replica environments.
## Automatically Executing Code in an Environment
### Enclave Scripts
To automatically execute code in Replica, create an Enclave Script and mount it to an Environment.
{% stepper %}
{% step %}
### Create an Enclave
Create an Enclave to store the files that you would like to execute within your environment.
{% endstep %}
{% step %}
### Create an Enclave Script
Within your Enclave, simply upload a file named `enclave.sh` . Any bash script with this special name will be automatically executed on startup when mounted to an Environment. You can use this script to initiate other processes or install applications. This file will run as `root` within the context of your environment.
enclave.sh
```sh
#!/bin/bash
echo "Installing NodeJS"
export DEBIAN_FRONTEND=noninteractive
apt-get update
apt-get install -y nodejs
echo "Enclave Script Complete"
```
{% endstep %}
{% step %}
### Mount the Enclave to an Environment
You can now use this enclave to automatically run code in any environment you choose. You can create a new environment normally to run the script on demand. You can also choose the enclave when creating a job if you would like to run the script on a schedule.
{% hint style="info" %}
To debug your Enclave script, you can view the execution log within the environment at `/home/user/Desktop/.enclave.log`
{% endhint %}
{% endstep %}
{% endstepper %}
## Example: Scraping a Webpage
Web scraping is a common developer use case in Replica. Here's a short example of how you can scrape a webpage, using an Enclave Script to initiate a Python script leveraging Selenium.
{% hint style="info" %}
These scripts presume Selenium is preinstalled in your Environment, and the name of your enclave is `my-enclave`
{% endhint %}
enclave.sh
```sh
#!/bin/bash
# create output directory for scrape results
su user -c "mkdir /home/user/Desktop/scrape-results"
# run the web scraper
su user -c "python3 /home/user/Desktop/enclaves/my-enclave/scrape.py"
```
scrape.py
```python
import os
import logging
from selenium import webdriver
from datetime import datetime
logging.basicConfig(encoding='utf-8', level=logging.INFO, format='%(levelname)s: %(message)s')
def scrape_page(url, dir_path='/home/user/Desktop/scrape-results'):
file_name = datetime.now().strftime('%Y%m%d-%H-%M-%S')
driver = webdriver.Chrome()
driver.get(url)
logging.info("Got page title %s from %s", driver.title, url)
new_screenshot = os.path.join(dir_path, file_name + '.png')
driver.save_screenshot(new_screenshot)
logging.info("Page screenshot saved to %s", new_screenshot)
pageSource = driver.page_source
new_source = os.path.join(dir_path, file_name + '.html')
with open(new_source, 'w', encoding="utf-8") as f:
f.write(pageSource)
logging.info("Page source saved to %s", new_screenshot)
scrape_page('URL_TO_SCRAPE_HERE')
# You may want to upload your scrape results to another system,
# or back to a different Enclave. See Butler API examples for more info.
```
## Scheduling a Job
Replica Jobs enable you to schedule code to run on a recurring basis.
All Replica Jobs are based on [Enclave Scripts](#enclave-scripts). Once you have defined an Enclave Script, you can schedule it to run as a Job [through the UI](/user-guide/butler-user-guide#create-job) or through the [Butler API](/developer-guide/butler-api-reference/jobs).
## File/Data Transfer
Data flow within Replica is controlled by the Butler subsystem. See [Butler API Guide](/developer-guide/butler-api-guide). Butler APIs can be used to transfer files and other data in and out of Replica.
# Butler API Guide
The Replica Butler subsystem controls secure bi-directional transmission of all data flow in and out of Replica's Virtual Environments. Replica Butler APIs can be accessed in two contexts:
* External to Replica, to transfer files to and from external systems
* Within a Replica Environment, to move files within Replica, or access files which have been previously uploaded
You can script interactions with Replica Butler using Python. The required package is preinstalled in Linux environments and includes built-in docstrings for inline reference and IDE auto-completion. The Python package README.md additionally lists all available function samples.
## Using the API Within an Environment
The scripts below are available in Linux environments and helpful for automating tasks.
### Python Examples
Use the preinstalled Python package to interact with Butler from within a Replica environment.
Use Butler Python package in Environment
**4.4.0**
```python
import sys
sys.path.append('/opt/greymarketlabs/configs/butler')
from butler import ReplicaButler
replicaButler = ReplicaButler()
initialized = replicaButler.initialize()
if initialized:
response = replicaButler.ping()
print(f'Ping response: {response}')
```
**4.5.0**
```python
from replica.butler import ReplicaButler
replicaButler = ReplicaButler()
initialized = replicaButler.initialize()
if initialized:
response = replicaButler.ping()
print(f'Ping response: {response}')
```
```sh
python3 my-script.py
```
***
## Using the API Externally to Replica
Use the Python package to interact with Butler from systems outside of Replica.
Install Package
This will install the Replica Butler Python Wheel with `--no-deps` flag and into the current working directory via the `--target` flag.
{% hint style="info" %}
The code samples presume the Python Requests library is preinstalled in your system, Python venv or equivalent
{% endhint %}
```sh
pip3 install replica_butler-4.4.0-py3-none-any.whl --no-deps --target .
```
Configure Credentials
Provide your instance domain name and credentials
| Environment Variable | Required | Description |
| -------------------- | -------- | --------------------------------------------------------------- |
| REPLICA\_DOMAIN | Yes | Replica domain name |
| REPLICA\_USERNAME | Yes | Replica user name |
| REPLICA\_PASSWORD | No | Replica user password or you'll be prompted to enter a password |
Use Butler Python Package
Use Pylance or similar extension in your IDE to view docs
```py
from replica.butler import ReplicaButler
replicaButler = ReplicaButler()
initialized = replicaButler.initialize()
if initialized:
response = replicaButler.ping()
print(f'Ping response: {response}')
```
```sh
python3 my-script.py
```
# Clipboard
Clipboard actions
## GET /v1/clipboards/{environmentId}
> Get environment clipboard data
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Clipboard","description":"Clipboard actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/clipboards/{environmentId}":{"get":{"summary":"Get environment clipboard data","tags":["Clipboard"],"parameters":[{"name":"environmentId","in":"path","required":true,"description":"The Environment Id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## PUT /v1/clipboards/{environmentId}
> Save data to environment clipboard
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Clipboard","description":"Clipboard actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ClipboardRequest":{"type":"object","required":["data","emit"],"properties":{"data":{"type":"string"},"emit":{"type":"boolean"}}},"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/clipboards/{environmentId}":{"put":{"summary":"Save data to environment clipboard","tags":["Clipboard"],"parameters":[{"name":"environmentId","in":"path","required":true,"description":"The Environment Id","schema":{"type":"string"}}],"requestBody":{"description":"Environment Clipboard request body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClipboardRequest"}}}},"responses":{"200":{"descrption":"Environment Clipboard save request success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"descrption":"Environment Clipboard save request failure","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## PUT /v1/clipboards/{environmentId}/{targetId}
> Transfer data between environment clipboards
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Clipboard","description":"Clipboard actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/clipboards/{environmentId}/{targetId}":{"put":{"summary":"Transfer data between environment clipboards","tags":["Clipboard"],"parameters":[{"name":"environmentId","in":"path","required":true,"description":"The source Environment Id","schema":{"type":"string"}},{"name":"targetId","in":"path","required":true,"description":"The target Environment Id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
# Storage
Enclave Storage Actions
## Get permitted Enclave Storage
> Gets a list of Butler Enclave Storage user is permitted to access
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Storage","description":"Enclave Storage Actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"EnclaveStorageInfo":{"type":"object","required":["id","name","assignee"],"properties":{"id":{"type":"string","description":"The Id"},"name":{"type":"string","description":"The name"},"assignee":{"allOf":[{"$ref":"#/components/schemas/Assignee"},{"type":"object","properties":{"displayName":{"type":"string"}}}]}}},"Assignee":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","$ref":"#/components/schemas/AssigneeType"}}},"AssigneeType":{"type":"string","enum":["user","group","profile"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/resources":{"get":{"summary":"Get permitted Enclave Storage","description":"Gets a list of Butler Enclave Storage user is permitted to access","tags":["Storage"],"parameters":[{"name":"ids","in":"query","required":false,"description":"Optional comma separated Ids","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{},"items":{"type":"array","$ref":"#/components/schemas/EnclaveStorageInfo"}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## Create new Enclave Storage
> Create and assign new Enclave Storage
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Storage","description":"Enclave Storage Actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"StorageCreateRequest":{"type":"object","required":["displayName","assignee"],"properties":{"displayName":{"type":"string","description":"The Enclave Storage name"},"assignee":{"type":"object","$ref":"#/components/schemas/Assignee"},"storageType":{"type":"string","$ref":"#/components/schemas/StorageType"}}},"Assignee":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","$ref":"#/components/schemas/AssigneeType"}}},"AssigneeType":{"type":"string","enum":["user","group","profile"]},"StorageType":{"type":"string","enum":["Isolated","Synchronous"]},"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/resources":{"post":{"summary":"Create new Enclave Storage","description":"Create and assign new Enclave Storage","tags":["Storage"],"requestBody":{"description":"Enclave Storage create request body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorageCreateRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## DELETE /v1/resources/{id}
> Delete Enclave Storage by Id
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Storage","description":"Enclave Storage Actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/resources/{id}":{"delete":{"summary":"Delete Enclave Storage by Id","tags":["Storage"],"parameters":[{"name":"id","in":"path","required":true,"description":"The Enclave Storage Id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{},"items":{"type":"array"}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## Assign Enclave Storage
> Assign Enclave Storage
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Storage","description":"Enclave Storage Actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"AssignmentRequest":{"type":"object","required":["id","assignee"],"properties":{"id":{"type":"string","description":"The Id"},"assignee":{"type":"object","$ref":"#/components/schemas/Assignee"}}},"Assignee":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","$ref":"#/components/schemas/AssigneeType"}}},"AssigneeType":{"type":"string","enum":["user","group","profile"]},"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/resources/assignments/{id}":{"post":{"summary":"Assign Enclave Storage","description":"Assign Enclave Storage","tags":["Storage"],"requestBody":{"description":"Enclave Storage assignment request body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignmentRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
# Files
File actions
## List files or download as zip file
> List or download files from Environment or Enclave
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Files","description":"File actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]}}},"paths":{"/v1/transfer/resources/{id}":{"get":{"summary":"List files or download as zip file","description":"List or download files from Environment or Enclave","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"description":"The Resource Id"},{"name":"name","in":"query","required":false,"description":"Set to provide custom zip file name"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}},"application/zip":{"description":"Download a zip file containing Resource files","headers":{"Content-Disposition":"attachment; filename=\"butler.zip\""}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## Copy files
> Copy files between Environments and Enclaves
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Files","description":"File actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TransferFilesRequest":{"type":"object","properties":{"action":{"type":"string","description":"Type of transfer","enum":["copy","export"],"required":true},"sourceId":{"type":"string","required":true,"description":"The source Resource Id"},"sourceName":{"type":"string","required":false,"description":"The source Resource Id"},"sourceType":{"$ref":"#/components/schemas/ResourceType","required":true,"description":"The source Resource Type"},"targetId":{"type":"string","required":false,"description":"The target Resource Id"},"targetType":{"$ref":"#/components/schemas/ResourceType","required":false,"description":"The target Resource Type"}}},"ResourceType":{"type":"string","enum":["environment","storage"]},"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/transfer/resources/{id}":{"post":{"summary":"Copy files","description":"Copy files between Environments and Enclaves","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"description":"The Resource Id"}],"requestBody":{"description":"Transfer request body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferFilesRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## Delete all files
> Delete an Environment or Enclave file
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Files","description":"File actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/transfer/resources/{id}":{"delete":{"summary":"Delete all files","description":"Delete an Environment or Enclave file","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"description":"The Resource Id"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## Download file
> Download a file from Environment or Enclave
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Files","description":"File actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]}}},"paths":{"/v1/transfer/resources/{id}/{name}":{"get":{"summary":"Download file","description":"Download a file from Environment or Enclave","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"description":"The Resource Id"},{"name":"name","in":"path","required":true,"description":"The Resource name"}],"responses":{"200":{"description":"Stream file content. Sets response Content-Disposition to attachment and MIME type from file."},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## Upload a file
> Upload a file to an Environment or Enclave
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Files","description":"File actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"UploadFileRequest":{"type":"object","required":["filesize","filetype"],"properties":{"filesize":{"type":"string","description":"File content size"},"filetype":{"type":"string","description":"File MIME type"},"filestore":{"type":"string","description":"File storage Type","enum":["s3","efs"]}}},"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/transfer/resources/{id}/{name}":{"put":{"summary":"Upload a file","description":"Upload a file to an Environment or Enclave","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"description":"The Resource Id"},{"name":"name","in":"path","required":true,"description":"The Resource name"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadFileRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"422":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## Delete a file
> Delete an Environment or Enclave file
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Files","description":"File actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/transfer/resources/{id}/{name}":{"delete":{"summary":"Delete a file","description":"Delete an Environment or Enclave file","tags":["Files"],"parameters":[{"name":"id","in":"path","required":true,"description":"The Resource Id"},{"name":"name","in":"path","required":true,"description":"The Resource name"}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
# Translation
Translation actions
## Translate content
> Translate content from one language to another
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Translation","description":"Translation actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TranslationRequest":{"type":"object","required":["translateFrom","translateTo","data"],"properties":{"translateFrom":{"type":"string","description":"The source language (auto or language code)"},"translateTo":{"type":"string","description":"The target language (af, sq, am, ar, hy, az, bn, bs, bg, ca, zh, zh-TW ...)"},"data":{"type":"array","description":"The text to translate"}}},"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/translation":{"post":{"summary":"Translate content","description":"Translate content from one language to another","tags":["Translation"],"requestBody":{"description":"Translation request body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslationRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{},"items":{"type":"array"}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{},"items":{"type":"array"}}}]}}}}}}}}}
```
# Events
Event actions
## POST /v1/events/publish/{environmentId}
> Publish an event to a Virtual Environment
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Events","description":"Event actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"EnvironmentEventRequest":{"type":"object","required":["name","data"],"properties":{"name":{"type":"string","description":"The event name (clipboard_sync, file_download, open_tab, etc.)","$ref":"#/components/schemas/EnvironmentEvent"},"data":{"type":"string","description":"The data to publish"}}},"EnvironmentEvent":{"type":"string","enum":["clipboard_sync","file_download","files_download_all","open_tab"]},"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/events/publish/{environmentId}":{"post":{"summary":"Publish an event to a Virtual Environment","tags":["Events"],"parameters":[{"name":"environmentId","in":"path","required":true,"description":"The Environment Id","schema":{"type":"string"}}],"requestBody":{"description":"Environment Event request body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentEventRequest"}}}},"responses":{"200":{"description":"Publish success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"description":"Publish failure","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
# Jobs
Translation actions
## Get Jobs status
> This endpoint requires administrator permissions
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Jobs","description":"Translation actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/jobs/status":{"get":{"summary":"Get Jobs status","description":"This endpoint requires administrator permissions","tags":["Jobs"],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## Pause Job scheduling
> This endpoint requires administrator permissions
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Jobs","description":"Translation actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/jobs/pause":{"put":{"summary":"Pause Job scheduling","description":"This endpoint requires administrator permissions","tags":["Jobs"],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## Resume Job scheduling
> This endpoint requires administrator permissions
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Jobs","description":"Translation actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/jobs/resume":{"put":{"summary":"Resume Job scheduling","description":"This endpoint requires administrator permissions","tags":["Jobs"],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## Get active Jobs
> This endpoint requires Jobs permissions
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Jobs","description":"Translation actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/jobs":{"get":{"summary":"Get active Jobs","description":"This endpoint requires Jobs permissions","tags":["Jobs"],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## Create a new Job
> This endpoint requires Jobs permissions
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Jobs","description":"Translation actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"JobRequest":{"type":"object","required":["displayName","imageId","routerId","resolution","expires","retries","pattern","assignee","storageId"],"properties":{"displayName":{"type":"string","description":"A job name"},"imageId":{"type":"string","description":"The Virtual Environment image id"},"routerId":{"type":"string","description":"The egress Router id"},"resolution":{"type":"string","description":"The Virtual Environment resolution"},"expires":{"type":"number","description":"The max run time of the job in minutes","minimum":10,"maximum":60},"retries":{"type":"number","description":"The number of times to retry failed jobs","minimum":0,"maximum":0},"pattern":{"type":"string","description":"A cron schedule pattern"},"assignee":{"type":"object","$ref":"#/components/schemas/Assignee"},"storageId":{"type":"string","description":"The Enclave Storage id"}}},"Assignee":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","$ref":"#/components/schemas/AssigneeType"}}},"AssigneeType":{"type":"string","enum":["user","group","profile"]},"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/jobs":{"post":{"summary":"Create a new Job","description":"This endpoint requires Jobs permissions","tags":["Jobs"],"requestBody":{"description":"Job request body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## Update existing Job
> This endpoint requires Jobs permissions
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Jobs","description":"Translation actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"JobRequest":{"type":"object","required":["displayName","imageId","routerId","resolution","expires","retries","pattern","assignee","storageId"],"properties":{"displayName":{"type":"string","description":"A job name"},"imageId":{"type":"string","description":"The Virtual Environment image id"},"routerId":{"type":"string","description":"The egress Router id"},"resolution":{"type":"string","description":"The Virtual Environment resolution"},"expires":{"type":"number","description":"The max run time of the job in minutes","minimum":10,"maximum":60},"retries":{"type":"number","description":"The number of times to retry failed jobs","minimum":0,"maximum":0},"pattern":{"type":"string","description":"A cron schedule pattern"},"assignee":{"type":"object","$ref":"#/components/schemas/Assignee"},"storageId":{"type":"string","description":"The Enclave Storage id"}}},"Assignee":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","$ref":"#/components/schemas/AssigneeType"}}},"AssigneeType":{"type":"string","enum":["user","group","profile"]},"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/jobs/{jobId}":{"put":{"summary":"Update existing Job","description":"This endpoint requires Jobs permissions","tags":["Jobs"],"parameters":[{"name":"jobId","in":"path","required":true,"description":"The Job Id","schema":{"type":"string"}}],"requestBody":{"description":"Job request body","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
## Delete a Job
> This endpoint requires Jobs permissions
```json
{"openapi":"3.0.0","info":{"title":"Replica Butler","version":"4.5.0"},"tags":[{"name":"Jobs","description":"Translation actions"}],"servers":[{"url":"/butler/api/","description":"Replica Butler"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ReplicaMessageSuccess":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}},"ReplicaEvent":{"type":"string","enum":["GET","POST","PUT","DELETE","ERROR"]},"ReplicaMessageFailure":{"type":"object","properties":{"statusCode":{"type":"integer"},"success":{"type":"boolean"},"message":{"type":"string"},"event":{"type":"string","$ref":"#/components/schemas/ReplicaEvent"},"items":{"type":"array"}}}}},"paths":{"/v1/jobs/{jobId}":{"delete":{"summary":"Delete a Job","description":"This endpoint requires Jobs permissions","tags":["Jobs"],"parameters":[{"name":"jobId","in":"path","required":true,"description":"The Job Id","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageSuccess"},{"type":"object","properties":{"message":{}}}]}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ReplicaMessageFailure"},{"type":"object","properties":{"message":{}}}]}}}}}}}}}
```
# Release Notes
Replica's release notes contain a high-level overview of features and improvements in each version of Replica. These notes are provided to help users stay informed about the latest platform changes. The features in the latest version automatically become available to users as soon as the release is made available.
{% updates format="full" %}
{% update date="2026-06-03" %}
## Replica 4.5.0
#### Highlights
* This release is about empowering the user in Replica. The newest evolution of Enclaves includes three new “sub” classes of Enclave as well as an entirely new feature aimed at delivering a smoother user experience while unlocking the power of the platform.
* We have worked to reduce cognitive load for the user to accelerate “time to operationality” by highlighting workflows that are important and automating those that aren’t. We have also consolidated views where appropriate.
* The “My View” experience will make it easier for users and admins to tailor their Replica workloads to the specific needs of their users
#### What shipped
**Enclaves & storage**
* Reimagined Enclaves:
* ***Storage Enclaves*** – what was previously referred to as “Enclaves” – storage mounts (isolated or synchronous) for your VE
* ***Worker Enclaves*** – designed to run “behind the scenes” to do things like install apps, execute scripts and configure your VE
* ***Enclaves*** – some predefined combination of the above, that result in a templated experience for one click environment creation.
* Users can now mount multiple Enclaves to a VE (max 3)
**Egress**
* Implemented new automation to better manage egress deployment within Replica. This will allow us to respond more efficiently to customers’ needs across all our available egress options.
* Introducing a new egress provider to broaden the locations available within Replica.
**Images**
* Windows 11 is now available for those customers with an Azure or Malware Zone.
**Observability & logging**
* New System Status page – allows admins to quickly glance at entitlements such as number of VEs, Egresses, Enclaves and Users.
* Consolidated Network Logging – simplified the way in which our customers collect mission critical logs
* Improved Packet Capture experience – PCAP logs are now stored local to the VE that they are collected on
* Removed legacy shared directory when launching Jupyter Notebooks.
* Deprecated access to Advanced Configuration page
**UI/UX**
* New “My View” experience – a more accessible Replica experience that shows you exactly the information you need and none of the information you do not.
* New Documentation pages – we have improved the readability and searchability of our docs
**Butler File Management**
* Bulk delete of files
* New “drag and drop” feature for instant upload
**Platform**
* A new release-managment tool within Replica that enables us to push updates more efficiently and quickly. This will result in our ability to deliver more releases in a shorter period of time as we continue to innovate.
* Zones now available in Azure
* “Replica Local” – the first steps have been taken to identify technology partners that will allow us to deliver Replica local to your host. The use-cases here are manifold, stay tuned for more detail as we continue to refine this offering.
{% endupdate %}
{% update date="2026-01-29" %}
## Replica 4.4.0
#### Highlights
* New Enclave Storage Type: choose Isolated or Synchronous storage for each Enclave to support strict separation or shared, reusable workflows.
* Expanded security monitoring coverage
* Faster, steadier provisioning at scale with standardized images, improved image transfer paths, added capacity, safer upgrades, and runtime hardening.
* Improved networking for Windows-based VEs, including the ability to “hot swap” an egress.
#### What shipped
**Enclaves & storage**
* Added Enclave “Storage Type” setting with two options:
* Isolated — self-contained storage for strict separation. Content is only accessible by assignee(s) and must be manually shared with other users or enclaves.
* Synchronous — persistent sharable storage. Content is accessible in real time by any user or environment with access.
* Enclaves are now “assignable”.
* Note: customers asked for more granular access controls (e.g., read-only vs read/write and group-based access). Those controls are not part of this release; v4.4 establishes the storage behavior selection.
**Identity & access controls**
* Enforced re-authentication before sensitive actions (“Force Reauth”).
* Tighter isolate-route permission structure (least privilege).
* 2FA styling/flow consistency improvements.
**Secrets & certificates**
* Security enhancements to internal vault
**Observability & logging**
* Improved security monitoring coverage
* Logging menu item fixed for Monitor user role.
**Provisioning, scale & reliability**
* Standardized Windows and Linux images (4.4.x).
* Improved Malware environment image transfer and backups.
* Added capacity and tuned scaling for key services.
* Safer upgrade behavior.
* Runtime hardening improvements.
* FlareVM available for Malware environments (analysis image).
**Analyst/admin experience + networking**
* Updated Guest Portal experience.
* New Troubleshooter portal for pre-flight checks and faster diagnosis.
* Router messaging improvements; clearer zones/time lifecycle states during setup and management.
* Egress tunneling enforcement moved from per-VM clients to cluster routers; VM environment egress routing aligns with container environments for a more consistent experience.
* VE Toolbox is now “relocate-able”.
{% endupdate %}
{% update date="2025-10-13" %}
## Replica 4.3.0
The 4.3 release of Replica was focused on completing all of the necessary work to enable Replica to enter the SOC2 – Type 2 audit period. We are pleased to announce that this audit began earlier this month as we finished wrapping up the features of this release that were not associated with Security and Compliance efforts. The balance of the development work this cycle pivoted to elements of the User Interface and User Experience, Administrative workflows as well as the usual improvements and bug fixes. Here are the highlights of the Replica 4.3 release:
#### Security and Compliance
* Replica has entered the mandatory 90-day audit period before officially becoming SOC2 – Type 2 certified. This was a wide-ranging effort and touched every part of the product. We will update all customers as soon as the audit period is complete and the certification is official.
#### User Interface/User Experience
* New User centric UI that consolidates all of the critical components of Replica into a single pane of glass – Virtual Environments, Enclaves, Egress and the newly introduced “Quick Create”.
* Enhanced Notifications that are easier to read
* Updated Animations
#### Platform
* Improved Troubleshooter utility – more robust testing to ensure that your host system is best configured to deliver maximum performance of Replica.
* VE Linux images have been upgraded to Ubuntu 25.10
#### Administration
* List views are now exportable to CSV. This includes both the list view of Virtual Environment and the list view of Users
* Last Login information is now included in Users
* Actions tab is pinned to the right side of the list views
#### Improvements
* Enhanced fine grain auditing for API events
* Added log monitor for Elastic Search – will improve health, hygiene and resiliency
#### Bug Fixes
* There was a known bug in the Isolate route (end point) that was remediated with this fix
* Pulse audio issue was resolved in DCV for this release
{% endupdate %}
{% update date="2025-07-21" %}
## Replica 4.2.0
Replica 4.2.1 is the latest release of the Replica platform. The flagship feature of this release is the debut of File Request Enclaves – a seamless way to invite third parties to collaborate with you safely and securely within Replica. As is customary for us, this is the first in a series of new capabilities designed to empower our users to extend the perimeter of what is traditionally understood as the boundary of trusted work. We are excited to bring this release to you and welcome feedback on this release. Please read below for highlights from this release:
#### Butler
* **File Request Enclaves:** This feature allows users to convert an existing Enclave into a File Request Enclave. File requests can be sent to any third party email, and files can be transferred safely and securely into this Enclave (subject to Butler file transfer limits). Once the Enclave is converted, it can no longer be mounted to a traditional VE, but instead a unique, “locked down” VE can be created to view and manipulate the files from within the safety and security of Replica. You can learn more about this feature on our website – [www.replicacyber.com](http://www.replicacyber.com)
* **Permissions:** Fine-grained Butler permissions for both files and Enclaves can now be scoped at the user or group level.
#### Platform
* **Image Catalog:** Improvements to the Image Catalog include installed applications and descriptions. This applies to both images presented when creating a VE and the Administrator view of the catalog.
* **Egress:** Customers now have the ability to configure egresses that cannot be changed. Geared toward supporting the creation and maintenance of online personas, these egresses are fixed at creation time, which prevents accidental slippage in tradecraft.
* **User Management:** Self Service password reset functionality has been improved for both ease of use and delivery of the password reset email to users’ inboxes. Note: Emails will now come from .
* **Group Management:** Group hierarchy is now clearly displayed in the Group Management section of Replica. This is part of a larger focus on making User and Group Management more streamlined and effective for our customers.
#### Malware
* **Management:** We are implementing VE caps on deployed Zones within Replica to avoid overprovisioning Malware resources. We will continue to improve and iterate on Zone management and encourage customers who have Malware Zones deployed to continue to raise feature requests in this space.
#### Software-defined telephony
* **Call Forwarding:** Users can clear the call forwarding field to restore the number to SMS-only.
#### Virtual environments
* **Bulk Create:** Users with the appropriate role can now create multiple VEs and Temporary User accounts with the click of a button. Use cases include: delivering online training, collaborating with teammates or workshops.
* **Greyscale:** Based on user feedback, we have implemented the ability to view sensitive content in a VE in either Greyscale or Black/White.
* **UI Improvements:** Several improvements and optimizations were implemented on the “Environments” page in Replica. These include (but are not limited to): additional information provided on the VE card, rendering of certain UI elements, and overall performance of the page.
#### Mobile telephony
* **Fix:** More resilient and reliable deployment method for the Mobile Phone to a VE.
#### Updates
* Normal security fixes and updates to the platform to keep you and your work safe while leveraging the latest technologies available to further your mission. Updates include (but are not limited to): upgrading Kubernetes, moving some database elements from Postgres to RDS, Updating and Back-up workflow improvements and token management improvements.
{% endupdate %}
{% update date="2025-05-28" %}
## Replica 4.1.0
We are pleased to announce our latest update to Replica – Replica 4.1 Building on the work done in the 4.0 release, Replica 4.1 advances the platform’s redesigned user experience and advanced architecture. Completing the integration of every workflow of Replica into our newly redesigned interface, Replica completes its transformation and begins to move toward delivering superior value and unparalleled capability. Enhancements in our Malware offering, improved Butler workflows, an overhauled User Management schema, and several requested features highlight this release. Here are all of the features included in this quarter’s update:
#### Platform
* **Image Catalog:** Fully integrated into the new UI.
* **User Management:** Fully integrated into the new UI. Simplified roles. Custom roles via fine-grain permissions.
* **Profile Memory:** Fully integrated into the new UI.
* **Telephony:** New telephony UI in the VE toolbox, including click-to-call workflows.
* **Zones:** Fully integrated into the new UI.
* **Export to S3:** Exports now include friendly names plus full VEIDs.
#### Malware
* Support for multiple snapshots of Malware-enabled VEs (storage constraints still apply).
* Start/Stop supported for Malware-enabled VEs.
* DCV available for Malware-enabled VEs.
#### Butler
* **Introducing Butler Events:** When enabled, automatically pass files between the VE and host machine via Butler.
* In-VE Butler interface redesigned to align with host-side UI.
* Enclave names can now include spaces.
#### Virtual environments
* Out-of-date Images are now clearly marked.
* Launch VEs in a new tab using native key binds (e.g., “shift+launch”).
* List view filters to show only relevant data points.
* Multiple users can access a single VE at the same time.
* Isolate browser extension restored.
#### Mobile telephony
* Mobile Telephony is now GA after Beta.
#### Updates
* Routine security fixes and platform updates.
#### New features and improvements
* **Global Assignments:** A global assignee for platform-wide resources.
* **Simplified Groups:** Groups are no longer required. “Global groups” are removed. Resources are assigned to Global.
{% endupdate %}
{% update date="2025-02-26" %}
## Replica 4.0.0
Replica 4.0 introduces significant improvements to user experience, performance, and collaboration capabilities. This release includes a redesigned interface, enhanced virtual environment management, expanded OS support, and new communication tools. Key updates include in-app walkthroughs, drag-and-drop environment cloning, seamless switching between environments, and improved file transfers. Additional enhancements feature high-performance VDI, Linux VM support for Docker, integrated Butler capabilities, SMS threading, scheduled recurring jobs, proxy support, rich text notifications, and virtual environment renaming.
#### New features and improvements
* **In-App Walkthroughs:** Interactive guided tours of platform workflows.
* **Drag-and-Drop VE Cloning:** Quickly duplicate and modify virtual environments.
* **Seamless In-App VDI Experience:** Switch between environments without disruption.
* **New File Transfer Overlay:** Streamlined drag/drop for quick file transfers.
* **High-Performance VDI:** Default setting on all new virtual environments.
* **Updated VEs with Linux Support:** Linux VM-backed environments for Docker compatibility.
* **Butler Integration:** Butler capabilities available directly in the Webkit UI.
* **SMS Interface with Threading:** Improved secure communication workflows.
* **Scheduled Jobs:** GA support for recurring automated tasks.
* **Proxy Support:** Enhanced access to external data sources.
* **Rich Text Notifications:** More informative and customizable alerts.
* **VE Renaming:** Personalize environment names for better organization.
{% endupdate %}
{% update date="2024-07-24" %}
## Replica 3.6.0
The Replica 3.6 release serves to deliver some key functionality from our commercial backlog to satisfy customer feature requests as well as generally finish up some incomplete items that were parts of the 3.4 and 3.5 release. Additionally, we are pushing some updates and upgrades of the underlying infrastructure of Replica in preparation for the debut of Replica 4.0 at the end of 2024.
This is not an exhaustive list, but rather a high-level summary of the key elements of Replica 3.6.
#### Platform
* Image Catalog: Introducing a graphical Image Catalog as well as the ability to assign images to groups.
* User Management: Manually configure password during the password reset workflow. Performance improvements to user management as well for deployments over 150 users
* Improved Notifications: Admins can now set an expiration date for notifications. Furthermore, reporting is now available on who has read the notifications pushed by Replica Administrators.
* Logging: The default logging dashboard will now include Time in VE for DCV enabled VEs. Additionally, friendly names will be visible.
* Licensing Controls: In conjunction with our change in licensing structure, we are implementing controls to more tightly constrain user and environment limits.
#### Butler
* Butler for Malware: To better support our malware users, Butler now supports accessing and downloading known malware into approved environments. This also enables administrators to allow users to download known malware directly to their host environments.
* Enclave Mounts for Windows: Users can now mount Enclaves to Windows VEs at create time in the same way they can with Linux VEs. This works across most of our supported IaaS including AWS, Azure and GCP as well as for our bare metal Malware offering and on-prem.
#### Virtual Environments
* Increased Logging for Windows VEs
#### Updates
* Kubernetes: Updating all clusters to Kubernetes v1.30
* Ubuntu: Security updates
* File System Reliability Improvements
{% endupdate %}
{% update date="2024-05-08" %}
## Replica 3.5.0
The Replica v3.5 release is a smaller, light-weight release that delivers a few key enhancements that were in flight but did not make it into the 3.4 release. As always, we have introduced additional security features and controls.
#### Platform
* Replica Chrome Extension: Modernized the Chrome extension for opening native weblinks in the context of a Replica VE. Note: This extension will be expanded in further releases.
* Egress: Enhanced UI elements to indicate deprecated egress points in Replica.
* User Management: Improved performance of the User management page to mitigate slowness and improve responsiveness.
#### Butler
* Clipboard one way data control: Butler can now be aware of which direction data is moving so that it can be configured to allow data to flow in only one direction, e.g. from the Virtual Environment to the host machine and not the other way.
* API Documentation: Updated documentation and scripts for leveraging Butler activity via the REST api.
#### Virtual Environments
* Copy/Paste: Implemented controls to enable “uni-directional” copying and pasting into or out of a Virtual Environment. This capability applies to both DCV and non-DCV equipped Virtual Environments.
* Replica Base Images: Creation of two new Images – a custom Ubuntu build (v16.04) and a popular Malware toolset - REMnux
{% endupdate %}
{% update date="2024-04-12" %}
## Replica 3.4.0
#### Platform
* Replica Organizations: Enhanced group management capability that allows customers to create groups below groups, set up group level administrators, and limit visibility across groups for more robust organizational management.
* Splunk Forwarder: Implemented a log forwarder for Splunk. note: Requires configuration from both Replica Support and customer – please contact Customer Success or Support for more information.
* Advanced Configuration: Administrators are now able to configure Advanced Settings for all Virtual Environments – including the ability to require certain features - e.g. URL Logging, Packet Logging, Screen Recording.
* Egress Management: Improved monitoring and remediation of all Egress endpoints within Replica.
* User Management: Expanded our SSO capabilities as well as introduced forced logouts and timeouts under various scenarios.
#### Butler
* Security Improvements: Improved Security for all transfers within Butler through implementing a tokenization scheme in Butler.
* File Transfer API: Improved workflows for handling Butler transfers using the Replica API. New documentation can be found in the User Guide
#### Virtual Environments
* DCV: General Availability of the DCV functionality that was released in Beta with 3.3
* Sandboxing: Introduced a “Sandbox” option into the Egress selector. This allows users to dynamically change the egress end point on a VE to and from a “Sandboxed” state in the same way they can from Egress to Egress.
* Language Support: Implemented additional tools at the VE level designed to assist with foreign language support – e.g. keyboard layout, browser extensions and Pinyin tooling.
#### Logging and Monitoring
* User Analytics: Introduced a new user metric – “Time Spent in VE”. These detailed user analytics will enable customers to evaluate usage more accurately and identify areas for improvement.
* Monitoring: Improved Monitoring of the Platform that includes additional alerting. This will improve cluster health visibility for the customer and improve response times from Replica when remediation is required.
{% endupdate %}
{% update date="2023-11-01" %}
## Replica 3.3.0
#### Features + Enhancements
* VE Refresh - New Look and Feel and Upgrades to Virtual Environments
* Enhanced Security and networking with advanced firewall overlay
* Unhealthy Egress are now flagged on the Create VE page
* VE Home directories now backed by faster storage technology
* Last Access for Windows VEs added
* Enclaves
* Download all files from enclave to VE not just file in the path
* Cloud Sandbox (Replica CRG subscribers only)
* Launch AWS or GCP Isolated Sandboxes instantaneously for research, training, or rapid prototyping.
* Set Time to Live (TTL) or Budget Limits for the environments
* Visualize spending across accounts through consolidated charts
* Set policy limits on what can be done in the sand box and where it can be accessed from eg. Replica
* Set Time to live (TTL) for Virtual Environments
* BETA Upgraded VDI backend to optimize performance and language character support (NICE DCV under advanced)
#### Notes
* In Progress release notes, expect additions/subtractions until released.
#### Bug Fixes
{% endupdate %}
{% update date="2023-09-11" %}
## Replica 3.2.0
#### Features + Enhancements
* Launching Dev VEs for users to run, host and consume services by other VEs
* Display Egress health for each VE
* Telephony decoupled from Profiles (send/receive SMS without requiring Profiles)
* SMS Relay - send/receive SMS from Replica through physical mobile phones
* Notifications and pop-up "Message of the Day" filtered by license type (e.g. alert admins only)
* Butler Features
* UI Updates (Upload)
* Code Viewer within the browser / Editor for enclaves
* Swagger API docs and UI for API
* Download all files as a combined zip file
* Reorganize files and Enclaves to support reassignments
* Metrics
* Display last access time on each VE
* Display who is actively using a VE (otherwise last accessed time is displayed)
* Additional GML egresses with automated setup and client generation for WireGuard connections
* Cloud Support
* Better AWS Gov Cloud support
* Added support for VEs in Malware zones without public IP addresses
* Migrate from AWS EFS to in-platform NFS
* VE Overlay now supports Full Screen + Keyboard lock
* VDI updates for performance
* **Beta** Butler VE Job Scheduling
* **Alpha** Cloud Sandbox
#### Bug Fixes
* Fixed a regression bug that prevented VE launches from the Replica browser extension
#### Breaking Changes
* Butler File Resource API change impacts Butler API users. Please see Butler API docs for revised File Resources API specification.
{% endupdate %}
{% update date="2023-05-23" %}
## Replica 3.1.0
#### New Features
* Hardware Environment snapshots
* New Butler features:
* Enclaves (beta)
* Clipboard passthrough
* VE to VE file transfer
* Hyperlink processor
* Multi-file delete
* Metrics dashboard
* PIV/CAC authentication support
* Configurable VE launch defaults
* One-time/Ephemeral VEs
* Linux VE on-demand Egress rotation
* Private Zone access
* In-VE authentication passthrough
* Jobs (beta)
#### Enhancements
* Routine security patches and updates to underlying components
* Butler UI enhancements
* Enhanced Butler file upload
* Improved image management infrastructure
* VE credentials displayed on overlay
#### Bug Fixes
* Users will now be returned to original page requested after authentication
* Fixed bug where resolution could display incorrectly in Environment details
* Fixed bug causing intermittent 502/503 errors
{% endupdate %}
{% update date="2022-10-12" %}
## Replica 3.0.0
#### New Features
* New Egress networking subsystem, enabling automatic reconnection to Egress points on network interruptions, faster connection times, and improved resource utilization
* Support for Wireguard Egress connection types
* Private Route feature to enable enterprise VPN connectivity
* Single-sign-on support for Audit and Logging Features
* One-click upload of multiple files to Replica Butler from file manager context menu
* Full-page translation plugin
* New Windows VM features
* Replica Butler availability via AWS and Azure
* Adjustable Disk sizing and Extra Drives
#### Enhancements
* Improved standardized logging throughout Replica
* RBAC improvements, including the ability to:
* Assign read-only access to Virtual Environments
* Assign Egress locations to specific users or groups
* Improved microservice architecture for scalability and reliability
* Security improvements to VE network architecture
* Routine security patches and updates to underlying components
* Improved resource utilization monitor in Linux Virtual Environments.
* Enhanced Windows VM Security
#### Bug Fixes
* Miscellaneous bug fixes and improvements.
{% endupdate %}
{% endupdates %}
# Frequently Asked Questions
This FAQ page provides quick answers to the most common questions about Replica, including setup, features, security, and support. It is designed to help you quickly understand how the platform works, resolve issues rapidly, and get the most value from the Replica platform without needing to contact support.
If you have further questions not answered in this guide, please contact
# How do I install additional software in my Virtual Environment?
### Linux Environments:
Linux Environments on the Replica platform support the installation of additional Linux software using the APT package manager.
When installing applications, you typically will need to execute your command superuser privileges by using the \`sudo\` command. When prompted for a password, you will need to use the password which is available to you under the [**View Credentials**](/user-guide/virtual-environments#toolbox-admin-credentials) menu option on your list of Virtual Environments.
Third-party packages available through APT have not necessarily been tested or approved by Replica Cyber.
See Also:
### Windows Environments:
Windows Environments on the Replica platform include an application gallery to easily install applications: Chocolatey GUI, available in the Start menu. Windows applications downloaded from the internet may also be installed as normal.
If prompted for a password, you will need to use the username and password available to you under the [**View Credentials**](/user-guide/virtual-environments#toolbox-admin-credentials) menu option on your list of Virtual Environments.
# How does IP address geolocation work?
The majority of third-party websites and services that attempt to geolocate IP addresses do so via commercial geolocation databases, such as MaxMind. The methods used to generate these databases are proprietary and can vary depending on the database, but generally are estimates of location based on a multiple sources of information. Furthermore, IP addresses are often reassigned to different physical locations by network providers, so these databases can quickly go out-of-date.
Due to this, it is not uncommon for two different geolocation databases to report different locations for a given IP address. IP geolocation services are often fairly accurate at the country level, but are less accurate at a local level. Because of the limitations of IP address geolocation, websites that attempt to geolocate your connection via these methods may not always return accurate information.
Egress locations included in the Replica platform are labelled by their true physical location as a top priority, rather than labelling them by estimates given by any particular IP address geolocation service.
# Can Replica Cyber see our activity?
To facilitate SaaS trials, we may monitor general usage to answer questions and troubleshoot any issues you may have during the trial period. In a production environment, all system access is audited, and we only access the system as necessary to provide/improve software, service, support, and security.
# How do I troubleshoot issues with a website in my Virtual Environment?
The most common reason that you may experience issues with a third-party website, is when it is inaccessible due to technical difficulties with the website itself. If you have trouble with one website, but not others, this typically indicates an issue with that website itself.
Some website operators block connections based on location or behavior of those connecting to it. If you suspect you are being blocked based upon your location, you may try connecting from another Egress location. If changing your egress doesn't work you may also want to try changing your browser image (e.g. Chromium to Firefox) because some sites will block you based on your browser and other attribution elements.
If you are running scripts or scrapers against a website, be mindful to limit the rate by which they run. Many websites intentionally block or serve CAPTCHAs when they suspect a visitor is not human.
# How do I troubleshoot issues with a third-party application in my Virtual Environment?
The most common issue that affects third-party applications within Replica, are issues with those applications themselves. If you have installed additional applications in your environment, be sure to check with that application’s vendor to see if the issue you are experiencing is due to a bug in the software itself. Additionally, close applications that you are not using, to free up resources. Because your Virtual Environments run in a shared environment with other users, Replica has inherent protections to prevent any single Virtual Environment from monopolizing shared resources.
# How do I troubleshoot login issues?
If you experience issues logging in, try the following steps:
* If you are logging in through a bookmark, ensure you have the correct URL bookmarked. The bookmark URL should be in the format of **`https://[instance].replicacyber.com`** without any additional text.
* If you receive a message that your account is disabled or your credentials are incorrect, contact your administrator to have them reset.
* If you previously had the page open for a while, for security purposes your session will timeout after the allotted time has passed. If you receive an error simply refresh the page or select your username and sign out to be taken back to the login page.
* If issues persist, restart your browser and clear your browser cache.
# How should I access Replica?
Replica is delivered as a web application accessible via the public internet, at a customer-specific URL. Replica uses HTTPS and WebSocket to deliver a secure and high-performance experience.
For best results, ensure your connection meets the following requirements:
* Connect directly to your Replica instance. Connecting through a VPN, remote browser, proxy, or virtualized desktop environment can cause decreased performance or compatibility issues. Common examples could include Zscaler, Akamai, or Citrix.
* Use a modern, up-to-date web browser. Replica is continually updated to support the current version of all major web browsers.
* If your organization utilizes security software that intercepts or blocks network traffic, be sure it is configured to whitelist connections to your Replica instance address to ensure proper operation.
* Ensure you have a good quality internet connection. If you are connected via WiFi, ensure you have a strong signal free from interference. You should use an ethernet connection if one is available to you.
# How do I type in another language?
Replica Virtual Environments will accept language in any input, directly from your local computer. If you wish to use a physical keyboard on your own system to type in Replica, you will need to change the keyboard input configuration on your local computer to reflect the language you want to use. The default languages set within your Virtual Environments are determined by the settings associated with the Egress you have chosen.
# How can I customize installed languages or character sets?
Languages and character sets are automatically installed in environments based on the languages configured for the egress location you have chosen. The languages associated with a particular egress location are set by default to the languages predominantly spoken at each location. These settings are configurable by the administrator, should they choose to customize them. This configuration is available in the 'Locale' section of the Egress configuration page.
\
Please note that this is a system-wide configuration for anyone using that particular egress location. If you would like to use an egress with different language configurations concurrently, it is possible to duplicate egress configurations with different language settings.
# Virtual Environment Lifetime and Best Practices
### How long can I use a VE before it is deleted?
There is no fixed expiration date on a Replica VE. VEs are designed to have flexible lifespans, ranging from minutes to months. Your company's business policies generally dictate if or how often a VE should be deleted. Our recommendation is to delete the VE when the activity you created the VE for is completed. These activities are usually discussed during intake as we help you become productive in Replica quickly. However, if you find yourself doing new activities that may benefit from a discussion with our product team, please send a request to
### Why should I delete a VE after I use it?
Replica Cyber was founded with the mission to protect life online and we take this mission seriously. The longer a VE lives (with internet connectivity) the more things need to be considered including security and functionality updates. Deleting a VE after use reduces risk to users and organizations. If you have a use case that would benefit from a discussion with our product team, please send a request to
# How do I copy and paste in my Virtual Environment with Firefox and Safari?
Firefox and Safari limit clipboard access in web applications. Because of this, standard copy and paste shortcuts may not work between your local computer and your Replica Virtual Environment.
## Use the Clipboard Button
If you use Firefox or Safari, use the built-in **Clipboard** button in the Replica interface.
### Copy Text From Your Virtual Environment
1. Highlight the text in your Virtual Environment.
2. Copy it in the session.
3. Click **Clipboard** in the top left.
4. Select **Copy to local device** using `ctrl` + `c`.
5. Paste the text on your local computer.
### Paste Text Into Your Virtual Environment
1. Copy the text on your local computer.
2. Click **Clipboard** in the top left.
3. Select **Paste to the clipboard utility** using `ctrl` + `v`.
4. Paste the text in your Virtual Environment using your normal paste shortcut.
## Browser Compatibility
* **Chrome and Edge**: Standard keyboard shortcuts work directly.
* **Firefox and Safari**: Use the **Clipboard** button.