Bash

Bash Execution

Edge replaces upstream's native shell with just-bash, a pure JavaScript shell running inside Cloudflare's VFS.

What Upstream Provides

Upstream's bash tool spawns a real shell process via node:child_process. The model sends a command string, the host executes it as a child process with full Linux capabilities — native binaries (git, python, cargo), pipes, background processes, signals, and environment variables. Output is streamed back. The tool is registered through the standard ctx.tools pipeline.

What Edge Changed

Replacement just-bash replaces native shell

Cloudflare Workers cannot spawn child processes. Edge replaces the entire shell backend with just-bash (v3.3.0), a pure JavaScript shell that runs in the Worker's V8 isolate. It provides 20+ built-in commands:

• File operations: cat, ls, mkdir, rm, cp, mv, touch, head, tail
• Text processing: grep, rg, sed, awk, sort, wc, xargs, diff
• Search: find with glob and regex support
• Custom commands: git (via Computer API), assets, artifacts

All file operations run against Cloudflare Computer's virtual filesystem (VFS), not a real Linux filesystem.

Two shell backends

Backend	Mode	How it works	Plan
DirectShellBackend	Direct	just-bash runs in-process inside the Durable Object. Simplest path — no Worker-to-Worker communication.	All plans (including free trial)
WorkerShellBackend	Isolated	just-bash runs in a separate Worker via Cloudflare's Computer Worker Loader binding. Shell execution is isolated from the DO's memory.	Requires LOADER binding (Workers Paid)

The backend is selected automatically: if the LOADER environment binding exists, WorkerShellBackend is used; otherwise DirectShellBackend.

System prompt disclosure

The system prompt explicitly tells the model about the shell's limitations:

"The shell is just-bash, not Linux: native binaries and background processes are unavailable."

What Edge Did NOT Change

• Tool registration mechanism (ctx.tools.register())
• Tool execution pipeline (pre-execute, guards, around-dispatch, post-execute)
• Output schema (command, output, exitCode, outputTruncated)

Limitations vs Upstream

Capability	Upstream	Edge
Native binaries	✅ git, python, node, etc.	❌ Only built-in commands + Computer git
Background processes	✅ &, nohup	❌ Not supported
Pipes to external programs	✅ `cmd1	cmd2` with any binary
Environment variables	✅ Full env	⚠️ Limited set, no persistent export
Signals	✅ SIGTERM, SIGKILL	⚠️ AbortController-based cancellation
Filesystem	✅ Real Linux FS	⚠️ VFS — persistent within workspace, no /usr, no /tmp outside workspace

Performance Characteristics

Output limit: 65,536 UTF-8 bytes per execution. Output beyond this is truncated with a marker.

Timeout: Default 120 seconds, configurable via DSH_EDGE_DEFAULT_COMMAND_TIMEOUT_MS (max also 120s by default, configurable via DSH_EDGE_MAX_COMMAND_TIMEOUT_MS).

Execution model: Synchronous within the DO isolate (DirectShellBackend) or isolated Worker (WorkerShellBackend). No concurrent shell sessions per turn — each command runs to completion before the next.

Security: just-bash runs with executionLimitProfile: 'hardened' and defenseInDepth: { enabled: 'auto' }.

Architecture Summary

Component	Category	Upstream
just-bash shell	Replace	node:child_process
DirectShellBackend	Replace	Local process spawning
WorkerShellBackend	Replace	Isolated subprocess
Tool registration	Reuse	ctx.tools.register()

Key observation: Bash is the most heavily adapted tool in Edge. The entire execution engine is replaced — from native process spawning to a pure JS interpreter. Despite this, the model-facing interface is identical: same tool name, same parameters, same output format. The model adapts its behavior based on the system prompt disclosure.

TODO

Evaluate Cloudflare Containers for real bash. Cloudflare Containers (launched 2025) can run full Linux containers alongside Workers. This would enable native binaries (git, python, node), real pipes, and background processes — closing the capability gap with upstream. The Container would need to mount the VFS workspace and communicate shell results back to the DO. Requires Workers Paid plan at minimum. The existing WorkerShellBackend interface could potentially be extended to dispatch to a Container instead of a Worker Loader.