buildhive-agent 1.0.0-beta.1 → 1.0.0-beta.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 (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +91 -148
  3. package/package.json +1 -1
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 BuildHive
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,166 +1,109 @@
1
1
  # BuildHive Agent
2
2
 
3
- The BuildHive Agent is a lightweight service that runs on developer machines to execute CI/CD build jobs in a secure, isolated environment.
3
+ Reduce your cloud CI costs by 60-80%. BuildHive routes GitHub Actions jobs to idle machines you already own.
4
4
 
5
- ## Configuration
5
+ ## Quick Start
6
6
 
7
- The agent uses a hierarchical configuration system that loads settings from:
8
-
9
- 1. Default configuration values
10
- 2. Configuration files (JSON format)
11
- 3. Environment variable overrides
12
-
13
- ### Configuration Files
14
-
15
- The agent searches for configuration files in the following locations (in order):
16
-
17
- 1. `./buildhive-agent.json` (current directory)
18
- 2. `./config/buildhive-agent.json`
19
- 3. `./.config/buildhive-agent.json`
20
- 4. `~/.buildhive/buildhive-agent.json` (user home directory)
21
- 5. `/etc/buildhive/buildhive-agent.json` (system-wide)
22
-
23
- Alternative file names are also supported:
24
- - `buildhive-agent.config.json`
25
- - `.buildhive-agent.json`
26
-
27
- ### Environment Variables
28
-
29
- All configuration options can be overridden using environment variables:
30
-
31
- | Environment Variable | Configuration Field | Type | Example |
32
- |---------------------|---------------------|------|---------|
33
- | `BUILDHIVE_PLATFORM_URL` | `platformUrl` | string | `https://api.buildhive.dev` |
34
- | `BUILDHIVE_API_KEY` | `apiKey` | string | `your-api-key` |
35
- | `BUILDHIVE_AGENT_ID` | `agentId` | string | `agent-123` |
36
- | `BUILDHIVE_AGENT_NAME` | `name` | string | `My Agent` |
37
- | `BUILDHIVE_MAX_CONCURRENT_JOBS` | `maxConcurrentJobs` | number | `2` |
38
- | `BUILDHIVE_HEARTBEAT_INTERVAL` | `heartbeatInterval` | number | `30` |
39
- | `BUILDHIVE_TAGS` | `tags` | string (comma-separated) | `android,linux` |
40
- | `BUILDHIVE_LOG_LEVEL` | `logLevel` | string | `info` |
41
- | `BUILDHIVE_JOB_TIMEOUT_MINUTES` | `jobTimeoutMinutes` | number | `60` |
42
- | `BUILDHIVE_ENABLE_METRICS` | `enableMetrics` | boolean | `true` |
43
- | `BUILDHIVE_ENABLE_AUTO_UPDATES` | `enableAutoUpdates` | boolean | `false` |
44
-
45
- ### Configuration Schema
46
-
47
- #### Required Fields
48
-
49
- - `platformUrl`: URL of the BuildHive platform API
50
- - `apiKey`: Authentication key for the agent
51
- - `agentId`: Unique identifier for this agent
52
- - `name`: Human-readable name for the agent
53
-
54
- #### Optional Fields
55
-
56
- - `maxConcurrentJobs` (default: 1): Maximum number of jobs to run simultaneously
57
- - `heartbeatInterval` (default: 30): Heartbeat interval in seconds
58
- - `tags` (default: []): Tags for job matching
59
- - `logLevel` (default: "info"): Logging level (debug, info, warn, error)
60
- - `jobTimeoutMinutes` (default: 60): Maximum job execution time
61
- - `enableMetrics` (default: true): Enable metrics collection
62
- - `enableAutoUpdates` (default: true): Enable automatic agent updates
63
-
64
- #### Docker Configuration
65
-
66
- - `dockerConfig.baseImage` (default: "ubuntu:22.04"): Base Docker image
67
- - `dockerConfig.networkMode` (default: "none"): Network isolation mode
68
- - `dockerConfig.memoryLimit` (default: "2g"): Memory limit for containers
69
- - `dockerConfig.cpuLimit` (default: "1.0"): CPU limit for containers
70
- - `dockerConfig.volumeMounts` (default: []): Volume mount configurations
71
-
72
- #### Resource Limits
73
-
74
- - `maxMemoryUsage` (default: 80): Maximum memory usage percentage
75
- - `maxCpuUsage` (default: 80): Maximum CPU usage percentage
76
- - `maxDiskUsage` (default: 90): Maximum disk usage percentage
77
-
78
- #### Security
79
-
80
- - `allowedRepositories`: Whitelist of allowed repositories (optional)
81
- - `blockedRepositories`: Blacklist of blocked repositories (optional)
82
-
83
- Note: You cannot specify both `allowedRepositories` and `blockedRepositories`.
84
-
85
- ### Example Configuration
86
-
87
- ```json
88
- {
89
- "platformUrl": "https://api.buildhive.dev",
90
- "apiKey": "your-api-key-here",
91
- "agentId": "agent-unique-id",
92
- "name": "My Build Agent",
93
- "maxConcurrentJobs": 2,
94
- "heartbeatInterval": 30,
95
- "tags": ["android", "linux", "docker"],
96
- "dockerConfig": {
97
- "baseImage": "ubuntu:22.04",
98
- "networkMode": "none",
99
- "memoryLimit": "4g",
100
- "cpuLimit": "2.0",
101
- "volumeMounts": [
102
- {
103
- "hostPath": "/tmp/buildhive-cache",
104
- "containerPath": "/cache",
105
- "readOnly": false
106
- }
107
- ]
108
- },
109
- "maxMemoryUsage": 80,
110
- "maxCpuUsage": 75,
111
- "maxDiskUsage": 90,
112
- "logLevel": "info",
113
- "logRetentionDays": 7,
114
- "allowedRepositories": [
115
- "myorg/repo1",
116
- "myorg/repo2"
117
- ],
118
- "jobTimeoutMinutes": 120,
119
- "connectionTimeoutSeconds": 30,
120
- "enableMetrics": true,
121
- "enableAutoUpdates": true
122
- }
123
- ```
7
+ ```bash
8
+ # Install
9
+ npm install -g buildhive-agent
124
10
 
125
- ## Installation
11
+ # Check your environment
12
+ buildhive-agent doctor
126
13
 
127
- ```bash
128
- npm install
14
+ # Set up (interactive wizard)
15
+ buildhive-agent init
16
+
17
+ # Start running jobs
18
+ buildhive-agent start
129
19
  ```
130
20
 
131
- ## Development
21
+ ## Requirements
132
22
 
133
- ```bash
134
- # Build the project
135
- npm run build
23
+ - **Node.js** 18+
24
+ - **Docker** installed and running
25
+ - **2 GB+ RAM** free
26
+ - **10 GB+ disk** free
136
27
 
137
- # Run tests
138
- npm test
28
+ ## How It Works
139
29
 
140
- # Run tests in watch mode
141
- npm run test:watch
30
+ 1. You install the agent on any machine (laptop, desktop, server)
31
+ 2. The agent connects to your BuildHive platform via WebSocket
32
+ 3. When a CI job is submitted, the agent pulls the repo and runs it in Docker
33
+ 4. Results stream back to your dashboard in real-time
34
+ 5. If no agent is available, jobs fall back to GitHub Actions automatically
142
35
 
143
- # Run tests with coverage
144
- npm run test:coverage
36
+ ## Commands
145
37
 
146
- # Development mode with auto-rebuild
147
- npm run dev
148
- ```
38
+ | Command | Description |
39
+ |---------|-------------|
40
+ | `buildhive-agent init` | Interactive setup wizard (register + configure) |
41
+ | `buildhive-agent start` | Start the agent (foreground) |
42
+ | `buildhive-agent start -d` | Start as background daemon |
43
+ | `buildhive-agent stop` | Stop the daemon |
44
+ | `buildhive-agent status` | Show agent status and config |
45
+ | `buildhive-agent doctor` | Run 12 diagnostic checks |
46
+ | `buildhive-agent logs` | View agent logs |
47
+ | `buildhive-agent logs -f` | Follow log output (like tail -f) |
48
+ | `buildhive-agent config` | Display current configuration |
49
+ | `buildhive-agent test` | Test connection to platform |
50
+
51
+ ## Setup Wizard
52
+
53
+ The `init` command walks you through:
54
+
55
+ 1. Enter your BuildHive server URL
56
+ 2. Auto-detects system capabilities (OS, CPU, memory, SDKs)
57
+ 3. Checks Docker is running
58
+ 4. Tests server connectivity
59
+ 5. Registers your agent and generates an API key
60
+ 6. Saves config to `~/.buildhive/config.json`
61
+
62
+ ## Configuration
63
+
64
+ Config is loaded from (in priority order):
65
+
66
+ 1. Environment variables (`BUILDHIVE_*`)
67
+ 2. Config file (`~/.buildhive/config.json`)
68
+ 3. Built-in defaults
69
+
70
+ ### Key Environment Variables
71
+
72
+ | Variable | Description | Default |
73
+ |----------|-------------|---------|
74
+ | `BUILDHIVE_PLATFORM_URL` | Server URL | `http://localhost:3001` |
75
+ | `BUILDHIVE_API_KEY` | Agent API key | (required) |
76
+ | `BUILDHIVE_AGENT_NAME` | Display name | hostname |
77
+ | `BUILDHIVE_MAX_CONCURRENT_JOBS` | Parallel jobs | `1` |
78
+ | `BUILDHIVE_JOB_TIMEOUT_MINUTES` | Job timeout | `60` |
79
+ | `BUILDHIVE_LOG_LEVEL` | Log verbosity | `info` |
80
+
81
+ ## Security
82
+
83
+ - Jobs run in Docker containers with **all capabilities dropped**
84
+ - **Read-only root filesystem** with limited tmpfs
85
+ - **Network isolation** (no outbound by default)
86
+ - **Resource limits** enforced (CPU, memory, disk, processes)
87
+ - **No privilege escalation** (`--security-opt no-new-privileges`)
88
+ - Git tokens are scrubbed from error messages and logs
89
+
90
+ ## Logs
149
91
 
150
- ## Usage
92
+ Logs are written to `~/.buildhive/logs/buildhive-agent.log` with:
93
+ - Automatic rotation (10MB per file, 5 files retained)
94
+ - Structured JSON format for production
95
+ - Human-readable console output
151
96
 
152
- ```typescript
153
- import { loadConfig, saveConfig, validateConfigFile } from '@buildhive/agent';
97
+ ## Troubleshooting
154
98
 
155
- // Load configuration
156
- const config = await loadConfig();
99
+ Run `buildhive-agent doctor` to check:
100
+ - Docker installed and daemon running
101
+ - Node.js version compatibility
102
+ - Server connectivity
103
+ - API key validity
104
+ - Disk space and memory
105
+ - Installed SDKs
157
106
 
158
- // Save configuration
159
- await saveConfig(config, './my-config.json');
107
+ ## License
160
108
 
161
- // Validate a configuration file
162
- const validation = validateConfigFile('./config.json');
163
- if (!validation.isValid) {
164
- console.error('Configuration errors:', validation.errors);
165
- }
166
- ```
109
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "buildhive-agent",
3
- "version": "1.0.0-beta.1",
3
+ "version": "1.0.0-beta.2",
4
4
  "description": "BuildHive CI Agent - Distributed build execution agent",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",