Dify

Dify 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 adds 15 tools that run commands, code and services on boxd machines. It is in the Dify Marketplace (pull request), and its source is at boxd-sh/boxd-dify. It needs Dify 1.10.0 or later.

Set up

Install the plugin

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

Create an API key

boxd auth keys create dify --org <your-org>

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

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 (nyc or fra), and a prefix for machine names (dify- by default).

Run a workflow

Download 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:

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.

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, 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 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 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 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 sets a machine up once, forks it twice, and runs Python on one fork and JavaScript on the other at the same time.

boxd in the Dify Marketplace
The plugin’s README, with every error message and limit
Sandboxes on boxd

Getting started

Guides

Integrations and automations

Use cases

References