@agent-os/workspace-env-local
Purpose
Section titled “Purpose”Local host adapter for @agent-os/workspace-env.
Invariant
Section titled “Invariant”The adapter maps a virtual workspace root such as /workspace to one explicit
host directory and declares generated tools as effectful host. Host execution
is never implicit: a consumer must construct this adapter directly, and the
tool contract carries the host execution domain.
This is not a just-bash fallback. It does not embed an in-memory shell and it
does not silently replace Cloudflare Sandbox or another provider. It uses real
Node fs and real host shell calls bound to the declared root.
Environment
Section titled “Environment”The default environment allowlist is empty. Pass envAllowlist explicitly when
local development commands need PATH or another host variable. The adapter
does not resolve symbolic envRefs or materialRefs; those must stay with a
material resolver or provider that owns them.
Minimal Usage
Section titled “Minimal Usage”Create an isolated root directory, then call makeLocalWorkspaceEnv. The
returned env can be passed to createWorkspaceTools.
For throwaway tests or onboarding demos, call makeTemporaryLocalWorkspaceEnv.
The returned root directory remains caller-owned and should be removed by the
test or demo harness.
Verification
Section titled “Verification”cd packages/execution-domains/workspace-env-localvp test run