Co-authored-by: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
dify-agent-runtime
Go implementation of the shellctl server and runtime utilities.
Architecture
cmd/
shellctl/ - main server binary (shellctl serve)
sanitize-pty/ - tmux pipe-pane PTY sanitizer (stdin→stdout filter)
runner-exit/ - post-drain SQLite exit recorder
dify-agent-cli/ - cli tool talking to agent backend
runner/ - process runner to bootstrap agent commands
internal/ - internal implementations
Agent configuration prompt
The sandbox's dify-agent CLI uses the authenticated Agent Stub connection:
dify-agent config prompt pull # Save ./.dify_conf/prompt.md; print its absolute path
dify-agent config prompt pull --to ./prompt.txt
dify-agent config prompt push # Read ./.dify_conf/prompt.md; print saved prompt JSON
dify-agent config prompt push ./prompt.txt
printf '%s' 'New instructions' | dify-agent config prompt push -
Pull and push preserve raw UTF-8 text, including mention markers, whitespace, and line endings. Empty input clears the prompt; a missing file is an error. Local edits must be pushed to persist. Only the current account's build draft is writable; snapshot and shared-draft configurations are read-only. Later requests built from the draft use the saved prompt; already-built requests retain their prompt. See the runtime contract for the Agent Stub and inner API endpoints.
Job execution modes
POST /v1/jobs/run accepts an optional mode field:
pty(default) keeps the interactive tmux PTY path. stdout and stderr are merged, sanitized, and written tooutput.log; the job accepts/input.stdiokeeps tmux as the lifecycle owner but gives the child/dev/nullas stdin and captures stdout and stderr through separate pipes. Public output and pagination read stdout fromoutput.log; private diagnostics are written tostderr.log. A stdio job completes only after both streams reach EOF and does not accept/input.
The response models are identical in both modes. Use stdio for bounded,
machine-readable control commands and pty for interactive jobs.
Building
make build
Produces binaries in bin/:
Building docker image
docker build -f dify-agent-runtime/docker/Dockerfile \
--build-context agent=./dify-agent \
-t dify-agent-runtime:latest \
dify-agent-runtime/
Running a Local docker container
Set SHELLCTL_AUTH_TOKEN to a nonblank secret and configure the Agent Backend's
DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN with the same value.
docker run -d --name dify-agent-runtime \
-p 15004:5004 \
-e SHELLCTL_AUTH_TOKEN \
dify-agent-runtime:latest \
shellctl serve --listen 0.0.0.0:5004 --require-auth-token
--require-auth-token rejects a missing, empty, or whitespace-only final token
before service initialization. A nonempty --token overrides
SHELLCTL_AUTH_TOKEN; valid values are preserved unchanged. The flag defaults
to off in the shared image, so E2B and Enterprise may omit a shellctl token.
Help text generation
Cli help can be generated and injected to dify-agent's system prompt.
make gen-cli-help
Testing
make test
Path Isolation
Each agent job runs inside a Landlock sandbox that restricts filesystem access:
| Access | Paths (defaults) |
|---|---|
| Read-Write | $HOME and the job's cwd (also used directly as TMPDIR, TMP, and TEMP) |
| Read-Write (dev) | /dev/null, /dev/zero, /dev/urandom, /dev/random, /dev/tty |
| Read-Only + Exec | /usr, /bin, /sbin, /lib, /lib64, /etc, /proc, /opt/dify-agent-tools, /opt/homebrew, /snap |
| Denied | Everything else (/tmp, other agents' homes, /var, /srv, etc.) |
The runner sets TMPDIR, TMP, and TEMP directly to the job's cwd. It does not create a separate temp directory, so the active Workspace is both the working directory and temp space.
Path isolation requires the Landlock kernel feature. Linux >= 5.19 (Landlock
ABI v2) is recommended: there $HOME and cwd allow cross-directory rename
and link within their trees via LANDLOCK_ACCESS_FS_REFER. On ABI v1 kernels
(Linux 5.13-5.18) the runner falls back to Landlock V1: the same path
restrictions apply, but REFER cannot be granted, so the kernel denies all
cross-directory rename/link with EXDEV, including inside $HOME/cwd.
Most tools fall back to copy (e.g. mv does copy+unlink), but
hard-link-preserving copies (e.g. Local Home snapshots with cross-directory
hard links) and tools that require rename across directories can fail. On
kernels without Landlock the job still aborts with exit code 125.
Extra SHELLCTL_LANDLOCK_RW_PATHS grant read-write access without REFER, so
cross-directory renames and hard links within those extra paths or between
them and $HOME/cwd remain denied.
Environment Variables
See here
Requires Linux ≥ 5.19 (Landlock ABI v2) with Landlock enabled. When path isolation is enabled,
any Landlock setup error aborts the job with exit code 125 before the user
script executes. Deployments may explicitly set
SHELLCTL_ENABLE_PATH_ISOLATION=false to disable this restriction.
API Routes
Home snapshot
Native save/restore of the runtime's Home directory ($HOME) as a tar+zstd
stream. One snapshot operation runs at a time per runtime (409 snapshot_busy
otherwise). Neither endpoint imposes a size limit — callers own size policy
and must bound the streams in their own logic (count bytes while reading a
save stream and abort at their cap; bound what they send to restore).
Each operation carries a total I/O deadline set by SHELLCTL_SNAPSHOT_TIMEOUT,
a Go duration string (10m, 15m30s). It bounds how long a stalled peer —
connection open, nobody reading — can hold the single-operation gate; a peer
that closes the connection releases it immediately. Unset or empty uses the
built-in default; an unparseable or non-positive value fails startup rather
than falling back to it.
POST /v1/snapshot/save— optional JSON body{"excludes": [...]}, gitignore syntax, matched at any depth; a malformed body is refused with400 invalid_request. The runtime's own state directory (.local/share/shellctl) is always excluded and no pattern can re-include it; an excluded directory is not descended into. The Workspace needs no such rule — it lives outside Home. Streams the Home asapplication/octet-stream(chunked). An empty Home is not a special case: it streams an ordinary archive with no entries. Success is signaled by trailersX-Snapshot-Status: ok,X-Snapshot-Sha256,X-Snapshot-Bytes; a cleanly terminated stream WITHOUT theoktrailer, or an aborted connection, is a failure.POST /v1/snapshot/restore— raw tar+zstd body, no parameters. Extracts into$HOMEunderos.Root(path traversal, absolute names, and symlink escapes are refused). Returns{"entries": N, "bytes_written": M};400 archive_malformedfor invalid input,500 restore_failedfor non-format failures (e.g. filesystem or environmental errors). Restore is NOT transactional — a mid-stream failure can leave a partially restored Home, so callers must treat the sandbox as unusable and recreate it rather than retry into it. Archives are plain tar+zstd; the decoder caps the zstd window at 64 MiB, so foreign archives produced with long-window settings are rejected as malformed.
Dependencies
- Go 1.26
modernc.org/sqlite(pure-Go SQLite driver, no CGO required)- tmux (runtime dependency, not a build dependency)