agentdock

<div align="center"> # Tool List **Equip AI with hands to reach every device.** An independent tool running layer for AI Agents, providing a unified, secure, and controllable file, command, Git, Skill, MCP, browser automation, and task execution capability for local computers, remote servers, and container environments. [Quick Start](https://uvwt.github.io/agentdock-docs/docs/getting-started/install) · [Online Documentation](https://uvwt.github.io/agentdock-docs/) · [Release Notes](https://github.com/uvwt/agentdock/releases) · [Issue Tracker](https://github.com/uvwt/agentdock/issues) [](https://github.com/uvwt/agentdock/actions/workflows/ci.yml) [](https://github.com/uvwt/agentdock/releases) [](https://hub.docker.com/r/agentdockio/agentdock) [](https://github.com/uvwt/agentdock/pkgs/container/agentdock) [](./LICENSE) </div> <p align="center"> <img src="./docs/assets/agentdock-multi-device.png" alt="AgentDock provides a unified view of multiple device states through one AI Agent" width="100%" /> </p> ## What is AgentDock? AgentDock is an independent tool running layer for AI Agents. It encapsulates file systems, command execution, Git, Skill, dynamic MCP, browser automation, and recoverable tasks on devices into a unified MCP capability, allowing different AI clients to operate local computers, remote servers, and container environments in a consistent manner. AgentDock does not provide a chat interface or model inference. It focuses on solving one problem: > Let AI Agents operate real environments within clear permission boundaries and return structured, trackable, and verifiable execution results. ```text AI Client / Agent │ │ MCP ▼ ┌───────────────────────────────┐ │ AgentDock │ │ │ │ Files · Commands · Git │ │ Skills · Dynamic MCP │ │ Browser · Tasks · Recall │ └───────────────┬───────────────┘ │ ▼ Local machine / VPS / Docker ``` ## What can you do with AgentDock? - Let AI read and modify local projects, run tests, and operate Git - Let AI manage VPS, Docker services, and deployment configurations - Let AI check logs, processes, ports, and real running states - Let AI operate logged-in web pages and macOS desktop applications - Extend external capabilities through Skill and dynamic MCP - Save long-term task execution states and continue after interruption - Connect macOS, Linux, Windows, and container environments with the same tool model ## Why use AgentDock? | Capability | Description | | --- | --- | | Unified Tool Entry | Provides file, command, Git, Skill, task, and browser capabilities through one MCP service | | Consistent Local and Remote | Same tool model runs on macOS, Linux, Windows, VPS, and Docker environments | | Clear Execution Boundary | Constrains path, permission, timeout, output length, and sensitive information | | Structured Execution Result | Distinguishes tool call status, command exit status, standard output, and error information | | Extendable Runtime | Supports independent Skill and dynamic MCP Server without writing all capabilities into the core program | | Recoverable Task | Supports task steps, checkpoints, blocking, recovery, final review, and completion conditions | | Ready for Production | Provides Docker, systemd, macOS, and Windows installation methods and releases official images | ## Quick Start Ordinary users do not need to download source code, install Go, or build images themselves. Complete installation guide: [Install AgentDock](https://uvwt.github.io/agentdock-docs/docs/getting-started/install) ### Docker Deployment Official images are synchronized to GitHub Container Registry and Docker Hub. The attached Compose file uses GHCR by default, and official images run with non-root users. ```bash mkdir agentdock cd agentdock curl -fL \ https://github.com/uvwt/agentdock/releases/latest/download/docker-compose.yml \ -o docker-compose.yml export AGENTDOCK_AUTH_TOKEN="$(openssl rand -hex 32)" docker compose pull docker compose up -d ``` Check running status: ```bash docker compose ps docker compose logs -f ``` Default MCP address: ```text http://127.0.0.1:18766/mcp ``` Stop service: ```bash docker compose down ``` Complete configuration, data persistence, and client access methods see [Docker Quick Deployment](https://uvwt.github.io/agentdock-docs/docs/getting-started/docker). ## Connect to AI Client AgentDock provides tool capabilities through MCP Streamable HTTP. The following is a general configuration example, and specific field formats depend on the AI client used: ```json { "mcpServers": { "agentdock": { "url": "http://127.0.0.1:18766/mcp", "headers": { "Authorization": "Bearer <AGENTDOCK_AUTH_TOKEN>" } } } } ``` If AgentDock only listens to the loopback address and explicitly disables authentication, you do not need to send the `Authorization` header. When exposing to the LAN or public network, you must enable authentication and configure HTTPS and network access control. ## Platform Installation | Platform | Documentation | | --- | --- | | Docker | [Docker Quick Deployment](https://uvwt.github.io/agentdock-docs/docs/getting-started/docker) | | Linux | [Linux Automatic Installation](https://uvwt.github.io/agentdock-docs/docs/getting-started/linux) | | Linux / VPS | [systemd Deployment](https://uvwt.github.io/agentdock-docs/docs/getting-started/vps) | | macOS | [macOS Installation](https://uvwt.github.io/agentdock-docs/docs/getting-started/macos) | | Windows | [Windows Native Installation](https://uvwt.github.io/agentdock-docs/docs/getting-started/windows) | Each platform document includes installation commands, startup checks, MCP addresses, and authentication methods. Browser automation, macOS desktop operation, Windows / WSL, reverse proxy, and data migration are located in the corresponding advanced documents. ## Version Updates Official Release binaries support direct version viewing and updates: ```bash agentdock --version agentdock update ``` `agentdock update` downloads the latest Release matching the current platform, verifies the SHA-256, and validates the new binary, then backs up and replaces the current version. If a LaunchAgent, systemd, Windows Service, or Windows user startup item is detected, it automatically restarts and verifies the new version; otherwise, it recovers the old version. Development builds cannot be updated through this command. ## Core Capabilities ### File and Command - UTF-8 text reading, searching, directory traversal, and structured modification - Atomic file writing, path boundary, and private directory protection - Command execution with timeout and output boundary - Standard output, standard error, and exit code separation - Long command sessions, PTY, session observation, input, and stop - Output truncation and sensitive information desensitization - Support for macOS, Linux, Windows, and WSL ### Git and GitHub - Repository state, difference, and commit record reading - Branch, commit, pull, and push - GitHub repository access check - Modification before and after state check and difference verification ### Skill and Dynamic MCP - Skill package verification, installation, activation, and rollback - Stable version, development version, Canary, and fixed version channel - Skill independent environment variables and running environment - Dynamic MCP Server registration, start-stop, refresh, and removal - Streamable HTTP and stdio transmission - Tool search, Schema check, and controlled call - MCP Server configuration isolation ### Browser and Desktop Automation - Browser session start, stop, and cleanup - Page jump, click, input, select, and wait - Page text, interactive elements, error, and network response check - Login status, persistent browser Profile, and screenshot - macOS system Chrome and desktop automation support ### Recoverable Task - Persistent task state - Clear goal, step, and completion condition - Phase checkpoint - Blocking reason record and interruption recovery - Final review and completion verification - Reusable workflow template ### Recall and NexusDock Integration AgentDock can optionally integrate with NexusDock to provide centralized capabilities for multiple devices and Agents: - Long-term project memory - Running manual and experience record - Workflow template - Private note - Multi-device state collaboration NexusDock is an optional integration. If not configured, AgentDock's basic file, command, Git, Skill, MCP, browser, and task capabilities still run independently. ## Using OAuth to Connect to ChatGPT When ChatGPT accesses public AgentDock through a custom MCP plugin, OAuth is recommended. AgentDock supports Authorization Code, PKCE S256, dynamic client registration, and Refresh Token. ChatGPT can automatically complete client registration without manually creating Client ID or Client Secret. Server-side configuration: ```bash AGENTDOCK_OAUTH_ENABLED=true AGENTDOCK_SERVER_URL=https://agentdock.example.com AGENTDOCK_OAUTH_PASSWORD=<at least 12 characters authorization password> AGENTDOCK_OAUTH_TOKEN_SECRET=<at least 32 bytes random signature key> ``` Then, go to ChatGPT's **Settings > Plugins > Advanced Settings**, enable developer mode, create a plugin, and fill in the MCP Server URL: ```text https://agentdock.example.com/mcp ``` After saving the plugin, the browser will open the AgentDock authorization page. Confirm the request comes from the newly created ChatGPT plugin, input `AGENTDOCK_OAUTH_PASSWORD`, and complete the authorization. Then, verify the connection through a `server_info` or other read-only tool call. The public entrance must use HTTPS, and `AGENTDOCK_SERVER_URL` only fills in the Origin without appending `/mcp`. Complete steps, endpoint verification, and FAQs see [ChatGPT Connection Tutorial](https://uvwt.github.io/agentdock-docs/docs/guides/chatgpt). ## Image Versions | Image Tag | Purpose | | --- | --- | | `latest` / `<version>` | Official running image without Go compilation toolchain | | `dev-latest` / `dev-<version>` | Development image with Go, C, and C++ build toolchain | | `browser-latest` / `browser-<version>` | Browser automation image with Chromium runtime environment | Official images are synchronized to: ```text ghcr.io/uvwt/agentdock agentdockio/agentdock ``` It is recommended to use a specific version for production environments instead of directly relying on `latest`: ```yaml services: agentdock: image: ghcr.io/uvwt/agentdock:<version> ``` ## Runtime Directory | Path | Purpose | | --- | --- | | `~/AgentDock` | Default working directory for relative file operations | | `~/.agentdock` | AgentDock state, configuration, session, and extension data | Docker deployment uses a named volume to save persistent data by default to reduce Linux bind mount UID and GID conflicts. When AgentDock needs to access the host directory, explicitly mount the required path instead of directly mounting the entire root directory. ## Port Description | Runtime Method | Default Address | | --- | --- | | Docker release configuration | `http://127.0.0.1:18766/mcp` | | Source code development mode | `http://127.0.0.1:8765/mcp` | The port can be adjusted through configuration, and the client should use the actual deployment configuration. ## Security Model AgentDock directly operates real resources within the host or container and should be deployed and authorized as an infrastructure service. ### Network Security - When listening only to the loopback address, authentication can be disabled according to actual needs - When listening to non-loopback addresses, Bearer Token or OAuth must be enabled - When providing services to the public network, HTTPS must be configured - Recommended to cooperate with firewall, reverse proxy, and network access control - Do not expose unauthenticated MCP services to the public network ### Permission Boundary - Run AgentDock with an independent system user - Grant only the file permissions required to complete actual tasks - Only mount required directories in Docker - Do not grant unnecessary root, Docker Socket, or host permissions - Use independent environment storage for sensitive variables of Skill and dynamic MCP ### Execution Verification - Command exit status and tool call status separation - File modification verification of real differences - Verification of process, port, log, and service response after deployment - Long task setting of clear completion conditions - Not just judging task success based on "command executed" ## Running from Source Code This section is for AgentDock contributors and developers who need to debug runtime. ```bash git clone https://github.com/uvwt/agentdock.git cd agentdock make check make run ``` Source code development mode listens to: ```text http://127.0.0.1:8765/mcp ``` ## Development and Contribution Run complete checks before submitting code: ```bash make check ``` The project uses GitHub Actions to continuously execute tests, static checks, builds, and release verification. User documentation is maintained independently in [`uvwt/agentdock-docs`](https://github.com/uvwt/agentdock-docs). When modifying user-visible behavior, configuration parameters, installation methods, or tool Schema, synchronize and update corresponding documents. Submit issues or feature suggestions using [GitHub Issues](https://github.com/uvwt/agentdock/issues). ## Project Boundary AgentDock is a tool running layer, not a complete AI application platform. It does not include a chat interface, large model inference service, model account, or API quota, nor does it bypass authentication or system security control. AgentDock can be called by ChatGPT, Claude, Codex, or other AI Agents supporting MCP. The actual connection method depends on the client's support for MCP transmission and authentication configuration. ## Related Links - [Online Documentation](https://uvwt.github.io/agentdock-docs/) - [Documentation Source Code](https://github.com/uvwt/agentdock-docs) - [GitHub Releases](https://github.com/uvwt/agentdock/releases) - [GitHub Container Registry](https://github.com/uvwt/agentdock/pkgs/container/agentdock) - [Docker Hub](https://hub.docker.com/r/agentdockio/agentdock) ## License Apache License 2.0. See [LICENSE](./LICENSE).