ZAK Agent

Local companion daemon for Governor IDE browser mode. Enables full terminal, filesystem, and git operations when using the IDE in a browser.

Quick Start

# Run directly with npx (no install needed)
npx zak-agent start

# Or install globally
npm install -g zak-agent
zak-agent start

What It Does

ZAK Agent is a lightweight local daemon that:

• Runs on your machine - Listens on localhost:9876 by default
• Enables real terminal - Execute any shell commands from the browser IDE
• Provides filesystem access - Read/write files without browser limitations
• Supports git operations - Clone, commit, push, pull repositories
• Maintains security - Only accepts localhost connections

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Browser IDE                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Editor    │  │   Terminal  │  │   File Explorer     │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│                           │                                  │
│                    WebSocket Client                          │
└───────────────────────────┼─────────────────────────────────┘
                            │ ws://localhost:9876
┌───────────────────────────┼─────────────────────────────────┐
│                     ZAK Agent                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  Terminal   │  │ Filesystem  │  │        Git          │  │
│  │  Handler    │  │   Handler   │  │      Handler        │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                            │
                    Your Local Machine
                (Files, Shell, Git repos)

Commands

# Start the agent
zak-agent start

# Start on a different port
zak-agent start --port 9999

# Show system information
zak-agent info

# Show help
zak-agent --help

Options

| Option | Default | Description | |--------|---------|-------------| | --port, -p | 9876 | Port to listen on | | --host, -h | localhost | Host to bind to | | --no-banner | false | Suppress startup banner |

Security

• Localhost only: The agent only accepts connections from localhost
• No remote access: Cannot be accessed from other machines
• Governor integration: All LLM operations still flow through Governor Cloud for constitutional enforcement
• No secrets stored: The agent doesn't store any credentials or API keys

Protocol

The agent uses a simple JSON-over-WebSocket protocol:

Request

{
  "id": "req_1",
  "type": "terminal:exec",
  "payload": {
    "command": "ls -la",
    "cwd": "/home/user/project"
  }
}

Response

{
  "id": "req_1",
  "success": true,
  "data": {
    "stdout": "...",
    "stderr": "",
    "exitCode": 0
  }
}

Supported Operations

| Type | Description | |------|-------------| | ping | Health check | | terminal:exec | Execute command | | terminal:spawn | Start interactive terminal | | terminal:write | Write to terminal | | terminal:kill | Kill terminal | | fs:read | Read file | | fs:write | Write file | | fs:readdir | List directory | | fs:exists | Check if path exists | | fs:mkdir | Create directory | | fs:delete | Delete file/directory | | fs:stat | Get file stats | | git:clone | Clone repository | | git:status | Get repo status | | git:diff | Get diff | | git:commit | Commit changes | | git:push | Push to remote | | git:pull | Pull from remote | | system:info | Get system info | | system:cwd | Get current directory | | system:home | Get home directory |

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build
pnpm build

# Type check
pnpm typecheck

Why Not Just Use Electron?

Electron is great for desktop apps, but:

1. Browser deployment - Users can access the IDE from any browser without installing
2. Dashboard integration - The IDE embeds seamlessly in the Governor Dashboard
3. Lower barrier - No download required for basic usage
4. Flexibility - Users choose their level of capability

The agent bridges the gap, giving browser users full capabilities when they need them.

Similar Projects

This pattern is used by:

• GitHub Codespaces (VS Code Server)
• Docker Desktop (daemon + UI)
• Cloudflare Wrangler (local dev server)
• Tauri (Rust backend + web frontend)

License

MIT