Introduction to Cordis

In the open-source autonomous agent ecosystem, most popular frameworks (such as LangChain or AutoGPT) utilize traditional monolithic object-oriented Python architectures. However, when handling long execution lifecycles, dynamic tool swaps, multi-turn state tracing, and enterprise service governance, monolithic frameworks frequently encounter memory leaks and dependency conflicts.

DeepSeek Harness adopts the Cordis Microkernel Architecture as its central execution engine. Cordis is an ultra-lightweight service bus framework purpose-built for Spatial and Temporal Composability.

This tutorial provides a comprehensive overview of Cordis design philosophy, local zero-build sandboxing, and core architectural rules for agent developers.

Architectural Perspective: Why DeepSeek Chose Cordis#

In standard agent execution loops, LLM requests, file I/O, and timers are often entangled in an unstructured process loop. Cordis rearchitects agent systems through two dimensions:

┌─────────────────────────────────────────────────────────────┐
│                 Cordis Microkernel Architectural View       │
├─────────────────────────────────────────────────────────────┤
│  1. Spatial Composability                                   │
│     • Everything is a Plugin: Models, Tools, Sandboxes, UI  │
│     • Declarative Dependency Injection: Resolves DAG order  │
├─────────────────────────────────────────────────────────────┤
│  2. Temporal Composability                                  │
│     • Scoped Fiber Context: Auto-reclaims listeners & timers│
│     • Zero-Downtime HMR: Edits apply live with zero leaks   │
└─────────────────────────────────────────────────────────────┘

• Ultra-Lightweight with Zero Business Bias: The core runtime contains only a few thousand lines of code. It contains no hardcoded prompts or execution scripts, focusing purely on DAG dependency graphs, event routing, and teardown lifecycles;
• Deterministic Self-Healing: When an upstream service is updated or reloaded, all downstream dependent plugins cleanly unmount and re-activate once the upstream service returns to the active state.

Core Mechanics: Zero-Build Sandbox & Offline Development#

The Harness environment allows rapid local testing without complex compilation steps:

# 1. Launch runtime directly using the bundled Cordis runner and tsx
node --import tsx vendor/cordis/bin.js ./cordis.yml

# 2. Launch web dashboard with live patch mode
pnpm dsh web --patch ./cordis.yml

Keyless Offline Sandboxing: The microkernel design allows developers to mount Mock LLM adapters or rule engines without providing real cloud API keys, enabling deterministic step-debugging of Tool execution pipelines and Trajectory logging locally.

Three TypeScript Rules for Agent Developers#

1. Leverage TypeScript Module Augmentation: When exposing a new service on Context, augment the interface via declare module '@deepseek-ai/cordis' for global IDE autocomplete;
2. Follow Standard Schema Invariants: Always export both a static interface Config and a runtime @deepseek-ai/schemastery Schema<Config> object, adhering to the Fail Loudly principle;
3. Manage Unmanaged Handles via ctx.effect: Register teardown logic for WebSockets, database pools, or child processes within ctx.effect return functions.

Path to Production: Moving Forward#

Having established a solid conceptual foundation of Cordis, proceed through the hands-on learning roadmap:

┌─────────────────────────────────────────────────────────────┐
│                 Recommended Learning Roadmap                │
├─────────────────────────────────────────────────────────────┤
│  • Basics: First Plugin ➔ Custom Tool ➔ Schema Configuration│
│  • Framework: Fiber Lifecycle ➔ Services & DI ➔ Event Bus   │
│  • Practice: Three-Role Architecture ➔ Custom LLM Adapter   │
└─────────────────────────────────────────────────────────────┘

Frequently Asked Questions (FAQ)#

Q1: How does Cordis differ fundamentally from traditional IoC containers (e.g. NestJS or InversifyJS)?

Answer: NestJS is built for backend web services with static lifecycles after boot; Cordis is designed for dynamic runtime hot-swapping. Every Context Fiber branch tracks all derived side-effects, allowing seamless live mounting and unmounting of plugins.

Q2: Why is pnpm recommended for Harness plugin development?

Answer: Harness consists of decoupled Seam, Provider, and Tool packages. pnpm Workspace monorepos link multiple local packages via symlinks, enabling instant cross-package debugging.

Q3: How does the Trajectory audit logger integrate with Cordis?

Answer: The Trajectory logger is a core Cordis plugin that listens to session/* and tool/* events, non-invasively capturing execution snapshots and persisting immutable session history.

Q4: How do I initialize Cordis inside an existing Node.js project?

Answer: Install @deepseek-ai/cordis, instantiate const ctx = new Context(), and attach modular capabilities using ctx.plugin().