> For the complete documentation index, see [llms.txt](https://docs.replicacyber.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.replicacyber.com/developer-guide/butler-api-guide.md).

# 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.

<details open>

<summary>Use Butler Python package in Environment</summary>

**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
```

</details>

***

## Using the API Externally to Replica

Use the Python package to interact with Butler from systems outside of Replica.

<details open>

<summary>Install Package</summary>

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 .
```

</details>

<details open>

<summary>Configure Credentials</summary>

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 |

</details>

<details open>

<summary>Use Butler Python Package</summary>

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
```

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

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

```
GET https://docs.replicacyber.com/developer-guide/butler-api-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

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