The Problem

Developers building AI‑driven agents need a reusable runtime that treats every capability—UI, storage, LLM client, tool integration—as a pluggable component. Without a common harness, projects duplicate wiring code, struggle with versioning, and cannot share plugins across languages or deployment targets.

What This Does

deepseek-harness is a portfolio of nine independent projects that together illustrate a “everything is a plugin” runtime built on the Cordis framework.

  • The web UI lives under apps/web/ with entry points apps/web/index.html and apps/web/src/main.ts. It loads plugins defined in packages/ and renders them via Vite (apps/web/vite.config.ts).
  • The CLI (apps/cli/) and its package.json expose the dsh command used to launch the UI (pnpm dsh web) or other agents.
  • Core plugin APIs are in packages/acp/acp/src/index.ts, packages/agent/, and packages/registry/. These modules export Cordis Plugin factories that other projects import.
  • Example agents (examples/acp-agent, examples/headless-agent, examples/jsonrpc-agent) show concrete plugin sets and how to register them with the harness.
  • Native helpers (native/landlock-run/...) provide low‑level sandbox binaries that can be invoked from TypeScript plugins.

All projects share a common pnpm‑managed monorepo layout, TypeScript configuration, and a set of YAML manifest files that describe plugin capabilities.

How It Is Wired

Execution starts at the CLI entry point defined in apps/cli/package.json (bin: {"dsh": "dist/cli.js"} after build). The compiled script loads apps/web/src/main.ts when the web sub‑command is used.

  1. apps/web/src/main.ts → imports @deepseek-ai/dsh (the core library built from packages/).
  2. The core library creates a Cordis Context and calls registerPlugins(context).
  3. registerPlugins walks the packages/ directory, loading each *.plugin.ts that exports a Plugin object (e.g., packages/acp/acp/src/index.ts).
  4. Each plugin may: Register HTTP routes (Express) – defined in packages/express-plugin/ (detected by the presence of Express in package.json). Declare Kubernetes manifests – YAML files under packages/k8s/. * Hook into the UI via React components – files ending in .tsx under packages/react-plugin/.
  5. After registration, main.ts boots an Express server (port 3080 by default) and mounts the Vite‑served React app. The server hands off control to the UI, which dynamically loads plugin UI bundles via code‑splitting.

The widest blast radius is the registerPlugins loop in the core library because any plugin’s setup function runs in the same Node process. Adding a misbehaving plugin can affect the entire harness. No circular dependencies were detected in the static graph; plugins are leaf nodes that only depend on the Cordis context.

How To Use It

# Clone the fork that contains the full portfolio
git clone https://github.com/moses-y/deepseek-harness.git
cd deepseek-harness

# Install dependencies (pnpm is the declared package manager)
pnpm install

# Build all packages
pnpm run build

# Launch the web UI (default http://127.0.0.1:3080)
pnpm dsh web

Configuration: The UI reads apps/web/.env if present; no mandatory environment variables are required for a basic run. Example agents may need a .env with OPENAI_API_KEY as documented in their README.md.

Running an example agent:

cd examples/acp-agent
pnpm install
pnpm run start   # invokes the same dsh CLI with the example’s plugin set

Real‑World Use

A SaaS platform that offers custom LLM‑powered assistants can embed deepseek-harness as a sandboxed runtime. Each tenant’s assistant is packaged as a plugin bundle placed under packages/tenant‑xyz/. The platform starts a separate Node process per tenant using the dsh CLI, registers only that tenant’s plugins, and exposes the UI through a reverse proxy. The shared Cordis core ensures consistent event handling while keeping tenant code isolated.

Code Health & Issues

Static analysis surfaced five concrete findings:

SeverityIssueLocation
HighPin third‑party GitHub Actions to a commit SHA (e.g., pnpm/action-setup@v4).github/workflows/*
MediumNo dependency‑vulnerability scan in CI.github/workflows/*
Mediumpersist-credentials: true on checkout step (exposes token).github/workflows/build-exe-for-python-sdk.yml
Mediumpostinstall script fetches binaries; scripts not disabled in CIpackage.json (root and sub‑packages)
LowMissing timeout-minutes on workflow jobs.github/workflows/release.yml

Other hygiene observations: tests exist (1943 files), GitLab CI is configured, a license file is present, and no secrets were found in the repository. No Dockerfile is provided, so container builds must be added if needed.

The Bottom Line

deepseek-harness offers a well‑structured, plugin‑centric runtime with concrete examples and a clear monorepo layout, making it a solid foundation for building extensible AI agents. The primary concerns are CI security hardening (action pinning, dependency scans, checkout credentials) and the lack of a Docker build path. Teams ready to adopt a Cordis‑based plugin model will find the code usable after addressing the listed CI issues.