> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Dify

> Give Dify workflows and agents boxd machines: run commands and code, keep files between runs, fork a machine, and serve a port over HTTPS.

![The Dify wordmark inside the boxd card.](https://mintcdn.com/azin/hzxvJlAVnEvK1ZI1/images/boxd-x-dify.png?fit=max\&auto=format\&n=hzxvJlAVnEvK1ZI1\&q=85\&s=31d263e362ce31e08955bb561e574579)

[Dify](https://dify.ai) is an open-source platform for building AI workflows and agents. Its plugins add tools that a workflow node or an agent can call.

The [boxd plugin](https://marketplace.dify.ai/plugin/boxd/boxd) adds 15 tools that run commands, code and services on boxd machines. It is in the Dify Marketplace ([pull request](https://github.com/langgenius/dify-plugins/pull/3733)), and its source is at [boxd-sh/boxd-dify](https://github.com/boxd-sh/boxd-dify). It needs Dify 1.10.0 or later.

## Set up

**1. Install the plugin**

In Dify, open **Plugins**, click **Install plugin**, choose **Marketplace** and search for `boxd`.

**2. Create an API key**

```bash theme={"theme":"github-dark"}
boxd auth keys create dify --org <your-org>
```

Machines are created and billed in the key's organization.

**3. Authorize the plugin**

On the **Plugins** page, select **boxd**, click **Authorize** and paste the key. Dify checks it by listing your machines once.

The other fields are optional: an organization, a [region](https://docs.boxd.sh/guides/regions.md) (`nyc` or `fra`), and a prefix for machine names (`dify-` by default).

**4. Run a workflow**

Download [`quickstart.yml`](https://github.com/boxd-sh/boxd-dify/blob/main/examples/quickstart.yml). In **Studio**, choose **Import DSL file**, pick the file, and run the workflow with its default input.

It has three nodes: **Start**, the boxd **Run Code** tool, and **End**. Your Python runs on a new machine, and the workflow returns its `stdout` and `exit_code`:

```text theme={"theme":"github-dark"}
hello from dify-3fa9c1d2
```

The machine exists for this one call. The plugin deletes it when the code has finished.

To build the same thing by hand, add a **Tool** node to a workflow, pick **boxd** and **Run Code**, and write the code in the node. In an **Agent** app, add the boxd tools under **Tools** and the agent creates machines, writes files and runs commands on its own.

## Call it from your code

Click **Publish** on the workflow, create an API key under **API Access**, and post to Dify's workflow API. `DIFY_API_URL` is `https://api.dify.ai/v1` on Dify Cloud and `http://<your-host>/v1` on a self-hosted Dify.

```bash theme={"theme":"github-dark"}
curl -s -X POST "$DIFY_API_URL/workflows/run" \
  -H "Authorization: Bearer $DIFY_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"code": "print(6 * 7)"}, "response_mode": "blocking", "user": "quickstart"}'
```

The response holds `"outputs": {"stdout": "42\n", "exit_code": 0}`.

## One call, or a machine you keep

**Run Command** and **Run Code** work without a `machine_id`. The plugin then creates a machine, runs the code, and deletes the machine.

To keep state, call **Create Machine** first and pass its `machine_id` to the other tools. Files, installed packages and running services stay on the machine between calls and between runs of your workflow. A tool that works inside a machine starts or wakes it first, so a workflow can come back to a machine that has hibernated.

## Tools

| Tool | What it does |
| - | - |
| Create Machine | Creates an isolated machine and returns its `machine_id`. Takes a name, a [size](https://docs.boxd.sh/guides/machine-specs.md), a snapshot, labels and a delete-after time. |
| List Machines | Lists machines with id, name and status. By default only the ones the plugin created. |
| Manage Machine | Starts, stops, pauses, resumes, hibernates or wakes a machine. |
| Fork Machine | Makes a [live copy](https://docs.boxd.sh/guides/fork.md) of a machine, with its disk, memory and running processes. |
| Delete Machine | Deletes a machine the plugin created. It refuses any other machine. |
| Run Command | Runs a bash command. Returns `stdout`, `stderr` and `exit_code`. |
| Run Code | Runs a Python, JavaScript, TypeScript or Bash snippet. |
| Start Service | Starts a long-running process in the background and returns a `service_id`. |
| Get Service Logs | Returns a service's latest output and whether it still runs. |
| Upload File, Download File | Move a file between Dify and a machine. |
| Read File, Write File, List Files | Work with text files and directories on a machine. |
| Get Preview URL | Returns a public HTTPS `url` for a port inside a machine. |

`machine_id`, `stdout`, `stderr`, `exit_code`, `service_id` and `url` are workflow variables, so a later node can use them directly.

## What each machine gets

* **Isolation:** every machine the plugin creates or forks is isolated. It has no boxd credentials and no route to your organization's other machines. The API key stays in Dify.
* **A label:** every machine carries `created-by=dify`. **Delete Machine** only deletes machines with that label.
* **A deadline, if you set one:** with **Delete after** on **Create Machine** or **Fork Machine**, boxd [deletes the machine](https://docs.boxd.sh/guides/delete-after.md) after that many seconds, also when the workflow stops halfway. A machine made for a single call always gets one hour.
* **A timeout per command:** 1 to 600 seconds, 120 by default. A command that runs out is stopped inside the machine, and the result has `timed_out` set. Use **Start Service** for anything that does not exit.
* **Public preview URLs:** anyone with a URL from **Get Preview URL** can reach the service behind it. A new URL can take up to a minute before it answers.

## More examples

The repository has two more workflows to import:

* [`persistent_workspace.yml`](https://github.com/boxd-sh/boxd-dify/blob/main/examples/persistent_workspace.yml) creates a machine on the first run, appends a line to a file on every run, and hibernates the machine in between.
* [`parallel_forks.yml`](https://github.com/boxd-sh/boxd-dify/blob/main/examples/parallel_forks.yml) sets a machine up once, forks it twice, and runs Python on one fork and JavaScript on the other at the same time.

## Read more

* [boxd in the Dify Marketplace](https://marketplace.dify.ai/plugin/boxd/boxd)
* [The plugin's README](https://github.com/boxd-sh/boxd-dify#readme), with every error message and limit
* [Sandboxes on boxd](https://docs.boxd.sh/use-cases/sandboxes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.