Agentgrid

AgentGrid

[中文文档](README.zh-CN.md) | [Vision](docs/vision.md) | [5-Minute Quick Start](docs/quickstart.md) | [Install](docs/install.md) | [Deploy](docs/deployment.md) | [CLI](docs/cli.md) | [Release](docs/release.md)

AgentGrid is an open-source scheduling layer for AI agents that need to operate real machines, desktops, tools, devices, jobs, and evidence.

It is not a natural-language automation product. AI clients do the reasoning. AgentGrid provides the structured runtime underneath: capability discovery, placement, worker execution, artifacts, audit trails, and recoverable jobs across private and cloud machines.

Why AgentGrid

AI agents are getting good at planning, coding, and using tools, but many real workflows still require access to actual computers:

• Windows workstations with desktop-only software
• Linux build nodes and private servers
• browser stations, SDK stations, and internal tooling
• hardware benches, serial ports, flashers, and test rigs
• evidence such as screenshots, logs, files, reports, DOM snapshots, and test results

AgentGrid turns those machines into a discoverable, schedulable, auditable capability grid.

Core Ideas

• Hub: the control plane for users, organizations, nodes, tasks, jobs, tools, artifacts, events, and the web console.
• Worker: a cross-platform Rust agent running on Linux, macOS, and Windows nodes.
• Capability Graph: node -> device -> tool -> plugin -> probe -> evidence -> suitable task.
• Placement Engine: schedules by hard constraints, soft scores, resource load, probe status, history, and risk.
• Evidence Pipeline: every execution can return structured output, artifacts, logs, screenshots, and timelines.
• Job Runtime: retries, leases, checkpoints, shard execution, recovery, and reducers.
• AgentMessage: structured AI-to-AI collaboration messages.
• MCP + SDKs: standard surfaces for AI clients and humans.

Ecosystem Vision

AgentGrid is designed as infrastructure for an ecosystem:

• worker plugins that add new tool families
• reusable task templates and workbench runbooks
• SDKs for Rust, Node, Python, iOS, Android, and future clients
• MCP servers for AI clients
• integrations with skill-based systems, local-first design tools, and agent workbenches

Projects such as Open Design can fit naturally above AgentGrid: their skills and design workflows can become AgentGrid tools or plugins, while AgentGrid supplies real-machine scheduling, desktop execution, artifacts, and audit evidence.

Features

• Hub web console built with Ant Design Pro
• node status, resources, CPU cores, memory, disk, OS, IP, and heartbeat
• node join authorization with machine fingerprint and join token
• command, HTTP, file, Git, Docker, browser, desktop, plugin, and AgentMessage tasks
• Windows Desktop Helper for screenshot, click, type, and key operations
• task result details, logs, artifacts, and screenshots
• task queue, priorities, target node/OS placement, and schedule explanations
• Job Runtime with dry-run plans, shards, checkpoints, recovery scan, and reducers
• Tool Registry, Node Tools, Tool Probe, and capability manifests
• Webhooks, Event Bus, execution records, and audit logs
• MCP server and SDKs
• OpenAPI and JSON Schema contracts

Quick Start

Install the latest release:

curl -fsSL https://raw.githubusercontent.com/hanfeihu/agentgrid/main/scripts/install.sh | bash

Windows PowerShell, run as Administrator:

irm "https://raw.githubusercontent.com/hanfeihu/agentgrid/main/scripts/install.ps1" | iex

Then run one local Hub, one local Worker, and one command task:

agentgrid-hub --host 127.0.0.1 --port 20181 --db /opt/agentgrid/agentgrid-hub.db --web-dir /opt/agentgrid/web
agentgrid-worker --hub http://127.0.0.1:20181 --id local-worker --name "Local Worker" --capability command --capability file --capability http
agentgrid submit-command --program hostname --wait

For a step-by-step path, see [5-Minute Quick Start](docs/quickstart.md).

Build from source:

• Rust stable toolchain
• Node.js 20+ for the web console

Build and check:

cargo check -p agentgrid-hub -p agentgrid-worker-app -p agentgrid-cli -p agentgrid-mcp
npm --prefix apps/agentgrid-web install
npm --prefix apps/agentgrid-web run build

Run the Hub:

cargo run -p agentgrid-hub -- \
  --host 127.0.0.1 \
  --port 20181 \
  --db data/agentgrid-hub.db \
  --web-dir apps/agentgrid-web/dist

Run a Worker:

cargo run -p agentgrid-worker-app -- \
  --hub http://127.0.0.1:20181 \
  --id local-worker \
  --name "Local Worker" \
  --capability command \
  --capability file \
  --capability http

Open the console:

http://127.0.0.1:20181

Submit a command task:

cargo run -p agentgrid-cli -- submit-command \
  --program hostname \
  --wait

Documentation

| Topic | English | Chinese | | --- | --- | --- | | 5-minute quick start | [docs/quickstart.md](docs/quickstart.md) | [docs/zh-CN/quickstart.md](docs/zh-CN/quickstart.md) | | Vision and ecosystem | [docs/vision.md](docs/vision.md) | [docs/zh-CN/vision.md](docs/zh-CN/vision.md) | | Maturity and known gaps | [docs/maturity.md](docs/maturity.md) | [docs/zh-CN/maturity.md](docs/zh-CN/maturity.md) | | Architecture | [docs/architecture.md](docs/architecture.md) | [docs/zh-CN/architecture.md](docs/zh-CN/architecture.md) | | Install | [docs/install.md](docs/install.md) | [docs/zh-CN/install.md](docs/zh-CN/install.md) | | Deployment | [docs/deployment.md](docs/deployment.md) | [docs/zh-CN/deployment.md](docs/zh-CN/deployment.md) | | CLI | [docs/cli.md](docs/cli.md) | [docs/zh-CN/cli.md](docs/zh-CN/cli.md) | | Mobile SDK | [docs/mobile-sdk.md](docs/mobile-sdk.md) | [docs/zh-CN/mobile-sdk.md](docs/zh-CN/mobile-sdk.md) | | Node join | [docs/node-join-standard.md](docs/node-join-standard.md) | [docs/zh-CN/node-join.md](docs/zh-CN/node-join.md) | | Artifacts and releases | [docs/artifacts.md](docs/artifacts.md) | [docs/zh-CN/artifacts.md](docs/zh-CN/artifacts.md) | | Release process | [docs/release.md](docs/release.md) | [docs/zh-CN/release.md](docs/zh-CN/release.md) | | OpenAPI | [docs/openapi/agentgrid-openapi.yaml](docs/openapi/agentgrid-openapi.yaml) | Same | | Command reference | [docs/agentgrid-command-reference.md](docs/agentgrid-command-reference.md) | Same |

Project Layout

agentgrid/
├── apps/
│   ├── agentgrid-hub/       # Rust Hub server
│   ├── agentgrid-worker/    # Cross-platform Worker
│   ├── agentgrid-cli/       # CLI for AI clients and humans
│   ├── agentgrid-mcp/       # MCP server
│   └── agentgrid-web/       # Web console
├── crates/
│   ├── agentgrid-protocol/
│   ├── agentgrid-scheduler/
│   └── agentgrid-sdk/
├── sdk/
│   ├── node/
│   ├── python/
│   └── mobile/
├── schemas/
├── docs/
└── examples/

Security Note

AgentGrid can execute commands and operate desktops on machines you own or administer. Do not expose a Hub publicly without authentication, network controls, and operational policy. Production secrets, SMTP codes, SSH passwords, private keys, and server inventories must stay outside git.

License

AgentGrid is released under the Apache License, Version 2.0. See [LICENSE](LICENSE), [NOTICE](NOTICE), and [OPENSOURCE.md](OPENSOURCE.md).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hanfeihu
• Source: hanfeihu/agentgrid
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.