@herdctl/web 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +146 -0
  2. package/package.json +3 -3
package/README.md ADDED
@@ -0,0 +1,146 @@
1
+ # @herdctl/web
2
+
3
+ > Web dashboard for herdctl fleet management
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@herdctl/web.svg)](https://www.npmjs.com/package/@herdctl/web)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
7
+
8
+ **Documentation**: [herdctl.dev](https://herdctl.dev)
9
+
10
+ ## Overview
11
+
12
+ `@herdctl/web` provides a real-time web dashboard for monitoring and managing your [herdctl](https://herdctl.dev) agent fleet. View agent status, trigger and manage jobs, chat with agents, and control schedules - all from your browser with live updates via WebSocket.
13
+
14
+ Herdctl is an open-source system for running fleets of autonomous AI agents powered by Claude Code. This package is part of the herdctl monorepo.
15
+
16
+ ## Installation
17
+
18
+ ```bash
19
+ npm install @herdctl/web
20
+ ```
21
+
22
+ > **Note**: The dashboard is typically started automatically via the `herdctl` CLI. Direct installation is only needed for programmatic use.
23
+
24
+ ## Quick Start
25
+
26
+ ### Via CLI (Recommended)
27
+
28
+ ```bash
29
+ # Start your fleet with the web dashboard enabled
30
+ herdctl start --web
31
+
32
+ # Or specify a custom port
33
+ herdctl start --web --web-port 3200
34
+ ```
35
+
36
+ ### Via Configuration
37
+
38
+ Add web dashboard settings to your `herdctl.yaml`:
39
+
40
+ ```yaml
41
+ fleet:
42
+ name: my-fleet
43
+ web:
44
+ enabled: true
45
+ port: 3100 # Default port
46
+ host: "0.0.0.0" # Default host
47
+ ```
48
+
49
+ Then start your fleet normally:
50
+
51
+ ```bash
52
+ herdctl start
53
+ ```
54
+
55
+ ### Programmatic Usage
56
+
57
+ ```typescript
58
+ import { FleetManager } from "@herdctl/core";
59
+ import { WebManager } from "@herdctl/web";
60
+
61
+ const fleet = new FleetManager({ configPath: "./herdctl.yaml" });
62
+ await fleet.initialize();
63
+
64
+ const web = new WebManager(fleet, {
65
+ port: 3100,
66
+ host: "0.0.0.0",
67
+ stateDir: ".herdctl",
68
+ });
69
+
70
+ await web.initialize();
71
+ await web.start();
72
+ // Dashboard available at http://localhost:3100
73
+ ```
74
+
75
+ ## Features
76
+
77
+ ### Fleet Dashboard
78
+ - Real-time fleet status with uptime, agent counts, and job statistics
79
+ - Agent cards showing current status, schedule count, and recent activity
80
+ - Recent jobs feed with status indicators
81
+
82
+ ### Agent Detail Pages
83
+ - Agent configuration and metadata
84
+ - Job history with pagination and filtering
85
+ - Live output streaming from running jobs
86
+ - DiceBear-generated avatars for each agent
87
+
88
+ ### Chat with Agents
89
+ - Interactive conversations with any agent
90
+ - Session management with conversation history
91
+ - Streaming responses via WebSocket
92
+ - Create, resume, and delete chat sessions
93
+
94
+ ### Schedule Management
95
+ - View all schedules across agents
96
+ - Enable and disable schedules
97
+ - Manually trigger schedules
98
+ - See last run and next run times
99
+
100
+ ### Job Control
101
+ - Trigger jobs manually with custom prompts
102
+ - Cancel running jobs
103
+ - Fork existing jobs with optional prompt overrides
104
+ - Copy CLI commands for any job
105
+
106
+ ### Real-Time Updates
107
+ - WebSocket connection for live fleet events
108
+ - Job status changes broadcast instantly
109
+ - Agent output streaming to subscribed clients
110
+ - Connection status indicator with auto-reconnect
111
+
112
+ ## REST API
113
+
114
+ The dashboard exposes a REST API for programmatic access:
115
+
116
+ | Endpoint | Description |
117
+ |----------|-------------|
118
+ | `GET /api/fleet/status` | Fleet status snapshot |
119
+ | `GET /api/agents` | List all agents |
120
+ | `GET /api/agents/:name` | Agent detail |
121
+ | `POST /api/agents/:name/trigger` | Trigger a job |
122
+ | `GET /api/jobs` | List jobs (with pagination/filtering) |
123
+ | `POST /api/jobs/:id/cancel` | Cancel a job |
124
+ | `POST /api/jobs/:id/fork` | Fork a job |
125
+ | `GET /api/schedules` | List all schedules |
126
+ | `POST /api/schedules/:agent/:schedule/enable` | Enable a schedule |
127
+ | `POST /api/schedules/:agent/:schedule/disable` | Disable a schedule |
128
+
129
+ ## Documentation
130
+
131
+ For complete setup instructions, visit [herdctl.dev](https://herdctl.dev):
132
+
133
+ - [Web Dashboard Guide](https://herdctl.dev/integrations/web-dashboard/)
134
+ - [Fleet Configuration](https://herdctl.dev/configuration/fleet-config/)
135
+
136
+ ## Related Packages
137
+
138
+ - [`herdctl`](https://www.npmjs.com/package/herdctl) - CLI for running agent fleets
139
+ - [`@herdctl/core`](https://www.npmjs.com/package/@herdctl/core) - Core library for programmatic use
140
+ - [`@herdctl/chat`](https://www.npmjs.com/package/@herdctl/chat) - Shared chat infrastructure (used internally)
141
+ - [`@herdctl/discord`](https://www.npmjs.com/package/@herdctl/discord) - Discord connector
142
+ - [`@herdctl/slack`](https://www.npmjs.com/package/@herdctl/slack) - Slack connector
143
+
144
+ ## License
145
+
146
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@herdctl/web",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Web dashboard for herdctl fleet management",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -24,8 +24,8 @@
24
24
  "react-router": "^7.2.0",
25
25
  "remark-gfm": "^4.0.1",
26
26
  "zustand": "^5.0.3",
27
- "@herdctl/chat": "0.2.2",
28
- "@herdctl/core": "5.2.0"
27
+ "@herdctl/chat": "0.2.4",
28
+ "@herdctl/core": "5.2.2"
29
29
  },
30
30
  "devDependencies": {
31
31
  "@tailwindcss/vite": "^4.1.18",