dify/dify-agent-runtime/README.md

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

```bash
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](../dify-agent/docs/dify-agent/index.md)
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 to `output.log`; the job accepts `/input`.
- `stdio` keeps tmux as the lifecycle owner but gives the child `/dev/null` as
  stdin and captures stdout and stderr through separate pipes. Public output
  and pagination read stdout from `output.log`; private diagnostics are written
  to `stderr.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

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

```sh
make gen-cli-help
```

## Testing

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

### Environment Variables

See [here](./internal/envvar/envvar.go)

Requires Linux ≥ 5.13 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 with
  `400 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 as `application/octet-stream` (chunked). An empty Home is not a special
  case: it streams an ordinary archive with no entries. Success is signaled by
  trailers `X-Snapshot-Status: ok`,
  `X-Snapshot-Sha256`, `X-Snapshot-Bytes`; a cleanly terminated stream WITHOUT
  the `ok` trailer, or an aborted connection, is a failure.
- `POST /v1/snapshot/restore` — raw tar+zstd body, no parameters. Extracts
  into `$HOME` under `os.Root` (path traversal, absolute names, and symlink
  escapes are refused). Returns `{"entries": N, "bytes_written": M}`;
  `400 archive_malformed` for invalid input, `500 restore_failed` for
  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)