dsh-worlds

Run the agent's execution world inside a container — so it survives the harness that started it.

DeepSeek Harness records this limitation in packages/terminal/terminal/README.md:

"Sessions are process-local and are not restored after a harness restart."

The session log is durable. The computer the agent was working on is not — the shell dies with the harness, taking your cwd, exported variables, and background processes with it.

dsh-worlds fixes that by moving the execution world into a Docker container. No CRIU, no microVMs: a container simply outlives its client.

harness process A            harness process B (a different process)
      |                                    |
      +------> [ container: dsh-world ]  "The existing `dsh-bash-local`, `dsh-terminal-bash`, and `dsh-lsp-stdio` **need no forks**. They delegate every execution-world operation to `ctx.fs` and `ctx.subprocess`."

Implement those two seams and Bash, persistent PTY terminals, LSP, and every file tool relocate into the container automatically. That is a deliberate architectural gift, and this project is what happens when you take it.

## Status

| Capability | Checks |
|---|---|
| Docker Engine API client + stream demux | 11 unit + 12 live |
| `ctx.fs` — all 12 methods | 38 live |
| Bounded collect buffers (offset-based, non-consuming) | 11 unit |
| `ctx.subprocess` — spawn, tree termination, `waitForExit` | 22 live |
| PTY — `spawnTerminal`, resize, foreground signalling | 17 live |
| **Total** | **111** |

Zero npm dependencies. `node:http`, `node:net`, `node:crypto` only.

## Try it

Requires Docker and a [dsh](https://github.com/deepseek-ai/deepseek-harness) checkout that has been built.

```sh
git clone https://github.com/frozo-ai/dsh-worlds
cd dsh-worlds
npm test              # unit suites, no Docker needed
npm run verify        # live: Docker client
npm run verify:fs     # live: filesystem provider
npm run verify:subprocess
npm run verify:terminal

Then install it into a dsh profile — it ships a dsh.bundle manifest, so it mounts by package name with no path editing:

dsh plugin --profile headless add github:frozo-ai/dsh-worlds

Add dsh-worlds to the profile's dsh.profile.bundles, then run normally — no --patch flag needed:

dsh --profile headless "use the terminal tool and run: tty; cat /etc/alpine-release"
#   -> /dev/pts/0
#      3.24.1

The demo

# harness A: create state, start a background process, then exit
dsh --profile headless "bash: echo session-state-v1 > /srv/state.txt && (nohup sleep 900 &)"

# harness B: a brand new process, same world
dsh --profile headless "bash: cat /srv/state.txt; ps -o args | grep '[s]leep 900'"
#   -> session-state-v1
#      sleep 900     <-- started by a harness that no longer exists

Honest limits

• The container is the boundary, not the sandbox seam. The overlay disables sandbox, bash-sandbox and permission-presets, and forces danger-full-access. Per-call sandbox modes (read-only / workspace-write) are no longer enforced at the bash layer. Host confinement is meaningless for a process that isn't on this kernel — but the container fences the host, not the workspace, which is coarser.
• stdin: 'pipe' (ongoing protocol writes) is not implemented; it rejects loudly rather than hanging. Batch stdin: { data } works.
• inputWaiting is a heuristic — a blocked tty read and an idle sleep are indistinguishable from /proc alone.
• The image must provide bash, ps, and base64. DockerWorld installs bash/procps via apk or apt when missing, and fails loudly if it can't.
• Path mirroring: dsh passes the host workspace path as cwd and the provider creates it inside the container. Real workspace access needs a bind mount (binds in WorldConfig).
• dsh itself is a developer preview with breaking changes; pin versions.

SCOPE.md carries the full interface map, size benchmarks, and every bug found along the way.

MIT. Not affiliated with DeepSeek AI.