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:

Plane	Files	Key point
Bundle / composition	cordis.patch.yml	per-profile id-targeted override layer
User settings	settings.yaml, .credentials.yaml	shared globally unless the patch redirects them
Skill injection	web-app bundle + agent presets	in web mode, 100% of skills come from the preset layer

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.