dsh-fresh-environment-creator

One command to spin up a clean, fully-isolated dsh profile for agent experiments and plugin development.

中文

Why this exists

Agent experiments fail to reproduce when leftover skills, sessions, credentials, or workspaces leak
across runs. Plugin development needs a clean, predictable starting point instead of a drifting global
config. This project makes an isolated sandbox trivial and consistent, so everyone can experiment and
build plugins from the same clean base.

What it does

dsh-fresh generates a fresh, fully-isolated dsh profile isomorphic to the reference profile
profiles/exp. Five things belong to the profile alone:

1. settings.yaml and .credentials.yaml resolve only from this profile own documents (no shared global copies);
2. workspace, message feedback, and projection-cache records live only under this profile storages directory;
3. session logs live only under this profile sessions directory (no other profile conversations leak in);
4. the skill catalog is empty: a code-noskill preset is injected, the only layer that actually suppresses skills in web mode;
5. the WebUI port is configurable (default 5000, still overridable by --port).

Every change touches only that profile; no global configuration is modified.

Run via npx (no install)

Once this package is published to the npm registry, run it directly without any
install step — npx downloads it on first use, then writes the fresh profile into
the real $DSH_HOME:

npx -y @ocero/dsh-fresh-environment-creator my-sandbox
npx -y @ocero/dsh-fresh-environment-creator --help

For local development before publishing, either npm link once (then use dsh-fresh)
or run the entry directly:

npm link
dsh-fresh my-sandbox

Quick start

Requires Node >= 18:

npm install        # or: pnpm install
npm link           # exposes the dsh-fresh bin

Create an isolated profile (written into the real $DSH_HOME so dsh can see it):

dsh-fresh my-sandbox
dsh --profile my-sandbox --dump-config
dsh --profile my-sandbox

Generated layout

$DSH_HOME/profiles/<name>/
├── cordis.yml          empty root entry list (composition = patch layers)
├── cordis.patch.yml    per-profile id-targeted overrides
├── settings.yaml       per-profile user settings (incl. default agent preset)
├── .credentials.yaml   per-profile credentials (fill in your keys)
├── package.json        profile manifest: dsh.profile.bundles
├── pnpm-workspace.yaml pnpm install root (nodeLinker: hoisted)
├── storages/           isolated workspace / feedback / projection cache
└── sessions/           isolated session logs

$DSH_HOME/.agent-presets/code-noskill/
├── agent.cordis.yml    Code-Mode preset with skill rows disabled
└── preset.yml

How the isolation works

dsh has three configuration planes that are easy to confuse:

Two traps are handled for you:

• The profile own settings/credentials are dead files: unless cordis.patch.yml points the settings and
  credentials providers at this profile documents, dsh reads the global copies.
• Disabling skill-filesystem at the host layer does nothing in web mode: skills register in the agent
  preset scope layer. The real lever is the code-noskill preset (its agent.cordis.yml disables the
  skill rows) chosen as the default.

How dsh discovers a profile

dsh loads a custom profile only when $DSH_HOME/profiles//package.json exists; otherwise only
built-in template names are recognized and unknown names throw "profile ... does not exist". Run
dsh-fresh with the default --dsh-home so the profile lands in the real home.

The default bundles (@deepseek-ai/dsh-base, @deepseek-ai/dsh-web-app) are in-box and resolve from the
dsh installation, so no profile-local pnpm install is needed for them. Only third-party bundles (for
example @ocero-plugin/harmony-validate) need installing into the profile.

CLI reference

dsh-fresh <name> [options]
  --dsh-home <path>          DSH home (default: $DSH_HOME or ~/.dsh)
  --bundles a,b,c            bundle ids (default: dsh-base,dsh-web-app)
  --preset <name>            no-skill preset to install + set default (default: code-noskill)
  --no-preset                do not set any custom default preset
  --host-skills / --no-host-skills  include host-layer skill disables (default: included)
  --web / --no-web           include the webserver port override (default: web)
  --port <n>                 WebUI port (default: 5000)
  --model provider:model     default model (default: deepseek-official:deepseek-v4-pro)
  --credential K=V           write a literal credential (repeatable)
  --credential-env K=ENVVAR  write a credential from the current environment (repeatable)
  --install                  run "pnpm install" inside the profile after writing
  --force                    overwrite an existing profile directory
  --dry-run                  print the generated files, write nothing
  -h, --help                 show help

Programmatic API

import { createProfile } from "@ocero/dsh-fresh-environment-creator";

const report = await createProfile({
  name: "my-sandbox",
  dshHome: process.env.DSH_HOME,
  credentials: { DEEPSEEK_API_KEY: "sk-..." },
  dryRun: true,   // preview only; omit to write
});
console.log(report.dir);

Verify

dsh --profile my-sandbox --dump-config   # confirms the isolation patch is applied

Restart the process and open a NEW session for changes to take effect; existing sessions keep their
old skill catalog.

Tests

npm test    # node --test (writes only into an OS temp dir)

Direction

This is step one toward giving every experiment and plugin a consistent clean base. It stays small,
dependency-free and reproducible, and is designed to grow: preset templates, one-shot bundle injection,
per-experiment environment snapshots, and more. Contributions and feature ideas are welcome.