# How Agent Environments Are Configured in Munder Difflin: A Technical Deep Dive

> Discover how Munder Difflin configures agent environments using declarative JSON manifests. Learn about sandbox parameters, resource access, and runtime constraints processed by the AgentProvider class.

- Repository: [Chaitanya Giri/munder-difflin](https://github.com/chaitanyagiri/munder-difflin)
- Tags: deep-dive
- Published: 2026-08-27

---

**Munder Difflin configures agent environments through a declarative manifest JSON that defines sandbox parameters, resource access, and runtime constraints, which the `AgentProvider` class processes to spawn isolated AI processes.**

Munder Difflin is an open-source platform that treats every AI agent as an independent, sandboxed process. When configuring agent environments, the system relies on a hierarchical manifest structure that declares exactly what resources each agent can access, from filesystem mounts to external servers. This declarative approach ensures reproducible, secure deployments while maintaining flexibility for different runtime scenarios, whether running locally or connecting to remote infrastructure.

## The Environment Manifest Structure

Every agent in Munder Difflin is defined by a manifest JSON file that contains a top-level `environment` object. This object tells the runtime how to isolate and provision the agent's execution context. According to the source code in [`src/shared/agentProvider.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/shared/agentProvider.ts), the harness reads this manifest during the initialization phase and extracts the environment configuration to build a secure sandbox.

The environment configuration supports several key aspects that determine resource availability and security boundaries.

### Environment Type and Runtime Mode

The `type` field specifies where the agent executes. Set `"type": "local"` (the default) to run the agent on the local machine, or use `"type": "remote"` to connect to a remote server. This distinction affects how the `AgentProvider` initializes the shell context and which networking capabilities are available to the agent process.

### Server Access Control

The manifest defines three tiers of server access under the `servers` key:

- **safeReadonly**: File servers and endpoints the agent can read but not modify
- **safeReadWrite**: Resources permitting bidirectional data flow
- **secret**: Sensitive endpoints (such as `https://secrets.mycorp.com`) that require explicit user consent

The [`src/shared/toolCatalog.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/shared/toolCatalog.ts) file implements the logic that consults this environment object to determine which servers are usable during tool execution. Each server entry includes a URL and a flag indicating whether the agent may transmit secrets to that endpoint.

### Filesystem Mounts and Environment Variables

The environment configuration supports direct filesystem integration through the `mounts` array, which maps host paths into the agent's workspace using `src` and `dest` properties. For example, mounting `/home/me/project` to `/workspace` gives the agent scoped access to specific directories without exposing the entire host filesystem.

Arbitrary environment variables are injected via the `variables` object. These key-value pairs are merged into the agent's shell context before any tool runs, allowing configuration of API keys, project roots, or custom tool paths.

### Resource Limits

Hard constraints prevent resource exhaustion through `tokenLimit`, `cpuQuota`, and `memoryQuota` fields. When `AgentProvider.spawnAgent()` launches the process, it applies these quotas to the sandbox environment, ensuring agents cannot monopolize system resources.

## The Configuration Lifecycle

The [`src/shared/agentProvider.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/shared/agentProvider.ts) file orchestrates a four-phase lifecycle that transforms the static manifest into a running sandboxed process.

**1. Manifest Loading**

`AgentProvider.loadManifest()` parses the JSON and extracts the `environment` object. This method handles both pre-made avatars from the Agent Gallery and fresh CLI agents created dynamically.

**2. Validation**

`AgentProvider.validateEnvironment()` enforces security policies by checking that required fields like `type` and server URLs are present. It also verifies that secret servers are only enabled after explicit user consent, preventing accidental credential exposure.

**3. Runtime Composition**

`AgentProvider.createShell()` constructs a shell wrapper that pre-loads environment variables, creates the requested directory mounts, and registers allowed servers with the tool layer. This composition step prepares the execution context before the agent binary starts.

**4. Process Spawning**

`AgentProvider.spawnAgent()` launches the agent process (whether Claude Code, Codex, or Antigravity) inside the prepared Pty (pseudo-terminal). The agent inherits the composed environment snapshot, ensuring it operates within the declared constraints.

Because the environment is part of the persistent manifest, agents retain their configuration across restarts. Changes made through the UI only affect **newly spawned** agents; running processes maintain the snapshot from their initialization time.

## Practical Implementation Examples

### Minimal Agent Manifest

The following JSON defines a frontend designer agent with scoped filesystem access and environment variables:

```json
{
  "name": "frontend-designer",
  "description": "Creates UI components",
  "model": "claude-3-opus-20240229",
  "environment": {
    "type": "local",
    "variables": {
      "PROJECT_ROOT": "/Users/me/Website",
      "API_KEY": "••••••"
    },
    "servers": {
      "safeReadonly": [{ "url": "file://~/Website" }],
      "secret": [{ "url": "https://secrets.mycorp.com" }]
    },
    "mounts": [
      { "src": "/Users/me/Website", "dest": "/workspace" }
    ],
    "tokenLimit": 8000
  }
}

```

### Programmatic Agent Spawning

To spawn an agent with a specific environment configuration using the TypeScript API:

```typescript
import { AgentProvider } from '@/shared/agentProvider';

// Load a manifest (normally supplied by the UI)
const manifest = await fetch('/agents/frontend-designer.json').then(r => r.json());

// The provider pulls out the environment and builds a sandbox
const agent = await AgentProvider.spawnAgent(manifest);

// The agent now runs with PROJECT_ROOT, the mounted /workspace, and only the safe-readonly server

```

### UI-Based Environment Updates

The Settings → Environment panel uses React components to expose the same JSON schema through forms. The [`EnvironmentEditor.tsx`](https://github.com/chaitanyagiri/munder-difflin/blob/main/EnvironmentEditor.tsx) component handles persistence:

```tsx
import { useState } from 'react';

function EnvironmentForm({ manifest, onSave }) {
  const [vars, setVars] = useState(manifest.environment.variables);
  
  const handleSave = () => {
    const updated = { 
      ...manifest, 
      environment: { 
        ...manifest.environment, 
        variables: vars 
      } 
    };
    onSave(updated); // Persists to the manifest file
  };
  
  return (
    // Form implementation that updates agent environments
  );
}

```

## Key Source Files and Architecture

Understanding how agent environments are configured in Munder Difflin requires familiarity with these core files:

- **[`src/shared/agentProvider.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/shared/agentProvider.ts)**: Core logic that reads manifests and builds sandboxed environments
- **[`src/shared/toolCatalog.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/shared/toolCatalog.ts)**: Tool catalog that respects environment constraints when accessing servers
- **[`src/renderer/src/components/agentControl/EnvironmentEditor.tsx`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/renderer/src/components/agentControl/EnvironmentEditor.tsx)**: UI component for editing environment configurations
- **[`docs/hires/spec/hire.schema.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/docs/hires/spec/hire.schema.json)**: JSON Schema defining the environment configuration structure
- **[`docs/hires/manifests/kevin-data.hire.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/docs/hires/manifests/kevin-data.hire.json)**: Example manifests demonstrating real-world environment setups

## Summary

- **Declarative Configuration**: Agent environments are defined via JSON manifests with a dedicated `environment` object containing type, servers, mounts, and resource limits.
- **Sandboxed Execution**: The `AgentProvider` class in [`src/shared/agentProvider.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/shared/agentProvider.ts) validates and composes these configurations into isolated runtime contexts.
- **Tiered Access Control**: Server access is categorized as safe-readonly, safe-read-write, or secret, with explicit consent required for sensitive endpoints.
- **Persistent but Snapshot-Based**: Environment changes persist to the manifest but only affect newly spawned agents, not currently running processes.
- **UI Integration**: The Settings → Environment panel provides a form-based interface for the same JSON schema, writing changes back to the manifest file.

## Frequently Asked Questions

### What file format does Munder Difflin use to configure agent environments?

Munder Difflin uses standard JSON manifest files with a top-level `environment` key. These manifests follow the schema defined in [`docs/hires/spec/hire.schema.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/docs/hires/spec/hire.schema.json) and can be edited directly or through the Settings → Environment UI panel.

### How do I restrict an agent from accessing sensitive servers?

Declare server access in the manifest's `environment.servers` object using the `safeReadonly`, `safeReadWrite`, and `secret` arrays. The [`src/shared/toolCatalog.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/shared/toolCatalog.ts) enforces these restrictions during tool execution, and secret servers require explicit user consent through `AgentProvider.validateEnvironment()`.

### Why don't changes to the environment affect running agents?

The `AgentProvider.spawnAgent()` method creates an immutable snapshot of the environment at spawn time. This design ensures runtime consistency and prevents configuration drift during execution. To apply new settings, you must terminate the current agent and spawn a new instance.

### Where is the environment configuration validated before spawning?

Validation occurs in `AgentProvider.validateEnvironment()` within [`src/shared/agentProvider.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/shared/agentProvider.ts). This method verifies required fields like `type` and server URLs, ensures secret servers are properly authorized, and checks that mount points are accessible before the sandbox is constructed.