Run your AI agents anywhere. Control them from anywhere.
ahpd is an open-source server that brings your AI agents, tools, and projects together.
Run agents on your computer, a remote server, or in containers. Connect from your browser, desktop, terminal, or phone.
Your work stays on the server. You can close an app, switch devices, or disconnect without losing your session.
Built on the Agent Host Protocol (AHP). See AHP compatibility for what it implements.
Read the documentation Β· GitHub Β· ahpio.com
Install with one line on Linux or macOS:
curl -fsSL https://ahpio.com/ahpd/install.sh | bashOn Windows, in PowerShell:
irm https://ahpio.com/ahpd/install.ps1 | iexThe script checks for Node 22.18 or newer, installs @ahpd/server without sudo, adds ahpd to your PATH, and runs ahpd configure. Install options
Or install with npm, then run the setup:
npm install -g @ahpd/server --allow-scripts=node-pty
ahpd configureChoose your agents, network settings, and project folders. To add an agent later, run ahpd plugin install @ahpd/agent-claude.
Start the host:
ahpd start --path /work/projectYour host is ready for an AHP client. Connect from the terminal with ahpc:
npx @softov/ahpc --host ws://127.0.0.1:9187ahpd --path /work/api --path /work/webProject paths are catalogue entries, not filesystem sandboxes. Access to other paths depends on the configured host capabilities and permissions.
By default, the host listens on loopback. To listen on another interface, configure a connection token:
ahpd --host 0.0.0.0 --connection-token-file ~/.config/ahpd/tokenOnly expose the host to networks you trust, and protect the token. See the remote access documentation.
AI agents can help you write code, fix problems, manage files, and automate tasks. But they often depend on the terminal or application where you started them.
ahpd gives your agents a place to run and gives you a way to reach them.
β³ Keep work running
Start a task and leave it running on your host. Your agent can continue its work when you close the client. Return later to review the results.
π± Work from any device
Start on your desktop. Check progress from your phone. Open the same session in your browser or terminal. Your work stays in sync.
π€ Choose your agents
Use Claude Code, Codex, Copilot, Gemini, pi, and other supported agents. Configure the agents you need and use them through one host.
π³ Run work in isolated environments
Use Docker containers to give tasks their own environment. Keep work separate when projects need different tools or dependencies.
β° Automate routine tasks
Schedule agent work or start it from a webhook. Let your host run tasks even when no client is connected.
π Control access
Control access to your agents and tools. Define who can interact with your host and what actions they can perform.
π Diagnostics
Inspect host status, logs, network information, and telemetry.
π° Control spending
See what each person, team, and project has spent on models. Set daily, weekly, or monthly limits, and the host refuses new work when a limit is reached.
π Share your models
Point your agent or a script at your host and call any model with your ahpd token. The host uses the provider's key, applies your policies, and records the cost. Model proxy
With the right capabilities enabled, agents and clients can work with the same host resources.
π Resources
Read, write, create, and delete files through resource ports.
β¨οΈ Terminals
Open a shell on your host from any client. Watch the commands your agent runs as they run, and come back later to read their full output.
π³ Git & GitHub
Inspect changes, branches, worktrees, and pull requests. Use separate worktrees to keep parallel sessions from sharing a working tree.
You do not need to commit to one agent or model provider.
ahpd supports several agent integrations. Each integration runs as a plugin.
β» @ahpd/agent-claude: Run Claude through the Claude Agent SDK. docs
ahpd plugin install @ahpd/agent-claude
Ο @ahpd/agent-pi: Run the pi coding agent directly in the host. docs
ahpd plugin install @ahpd/agent-pi
β @ahpd/agent-acp: Codex, Copilot, Gemini, and other supported agents through Agent Client Protocol. docs
ahpd plugin install @ahpd/agent-acp
β @ahpd/agent-cofold: Generic harness to use supported OpenAI-compatible models. docs
ahpd plugin install @ahpd/agent-cofoldEach capability can be configured to fit your environment.
@ahpd/computer: Create isolated environments for agentic tasks. docs
ahpd plugin install @ahpd/computer
@ahpd/bot: Give an agent its own identity, workspace, and session. docs
ahpd plugin install @ahpd/bot
@ahpd/webhook: Start work from an HTTP request. docs
ahpd plugin install @ahpd/webhook
@ahpd/tunnel-devtunnel: Reach your host from VS Code on another network, through a Microsoft Dev Tunnel. docs
ahpd plugin install @ahpd/tunnel-devtunnel
@ahpd/tasks: Keep one list of tasks and plans that every agent and person reads and writes. docs
ahpd plugin install @ahpd/tasks
@ahpd/push: Get a phone notification when a session needs you, with the app closed. docs
ahpd plugin install @ahpd/push
@ahpd/activepieces: Use Activepieces connectors as tools for your sessions and bots. docs
ahpd plugin install @ahpd/activepiecesahpd runs your agents and keeps their sessions. Connect with the client that suits you.
Manage sessions, files, terminals, and host settings from your browser.
Connect to multiple hosts, manage local installations, and work in dedicated windows.
Work with agents through an interactive terminal, CLI commands, or scripts.
# Connect to your host with the terminal client
npx @softov/ahpc --host <host-address> --token <your-token>Follow work, receive notifications, and respond when an agent needs your approval.
Android Β· iOS soon Β· Website
Connect with compatible applications, including supported VS Code integrations.
AHP Client Libraries Β· AHP Implementations
One host, every screen. Start work on one device and continue from another. Your sessions stay on the host.
ahpd has a small core and a plugin system. Add new agents, tools, URI schemes, environments, and services without modifying the daemon.
@ahpd/sdk lets you embed an AHP host in your application. It handles protocol negotiation, subscriptions, snapshots, state updates, reconnects, sessions, chats, and transcript paging.
import { createHost, listen } from '@ahpd/sdk';
import { claude } from '@ahpd/agent-claude';
const path = process.cwd();
const host = createHost({ path, agents: [claude({ paths: [path] })] });
await listen({ port: 9187 }, (peer) => host.accept(peer));You can extend your host without changing the server itself.
Implement the Agent interface or contribute host ports, tools, and URI schemes. Load extensions from npm packages, local directories, or manifest-backed files.
# Load plugins for one run, in place of the configured list
ahpd --plugin @ahpd/agent-claude --plugin @ahpd/computer
# A single file, with a plugin.json beside it that names its id and main
ahpd --plugin ./scratch-agent.mjs
# A directory with a manifest, tried against the working directory first
ahpd --plugin ./my-custom-agentA custom agent implements the same Agent interface and is named the same way as the agents above. A client speaks only AHP and depends on no agent SDK.
flowchart LR
classDef core fill:#0f172a,stroke:#10b981,stroke-width:1.5px,color:#fff
classDef plugin fill:#1e293b,stroke:#8b5cf6,stroke-width:1.5px,color:#fff
classDef claude fill:#1e293b,stroke:#F88c00,stroke-width:1.5px,color:#fff
classDef cofold fill:#1e293b,stroke:#3b82f6,stroke-width:1.5px,color:#fff
SERVER["@ahpd/server"]
SDK["@ahpd/sdk"]
subgraph Plugins ["Agent Plugins"]
CLAUDE["@ahpd/agent-claude"]
COFOLD["@ahpd/agent-cofold"]
ACP["@ahpd/agent-acp"]
PI["@ahpd/agent-pi"]
CUSTOM["Your agent"]
end
SERVER --> SDK
SERVER -. "dynamically loads" .-> Plugins
CLAUDE -->|"implements"| AGENT["Agent Interface"]
COFOLD -->|"implements"| AGENT
ACP -->|"implements"| AGENT
PI -->|"implements"| AGENT
CUSTOM -->|"implements"| AGENT
SDK -->|"hosts & manages"| AGENT
class SERVER,SDK core
class CLAUDE claude
class COFOLD cofold
class ACP,PI,CUSTOM plugin
Plugins execute inside the daemon with its permissions: install only code you trust. Add the integrations you need. Remove or disable the ones you do not use.
Write a plugin Β· Write an agent Β· Smallest agent example
The full documentation is at softov.github.io/ahpd.
| Document | Purpose |
|---|---|
| Get started | Install, configure, start, and connect VS Code |
| Install | Install, and run on Node, Bun or Deno |
| Upgrade | Upgrade the daemon and its plugins |
| Reference | Every command and flag |
| Plugins | Install, update, and configure plugins |
| Users | Users and authorization |
| Policy | Who may use which agent, model and computer, and how much |
| Usage | What each person, team and project has spent |
| Model proxy | Call a model through the host with your ahpd token |
| Write a plugin | The plugin contract, manifest and events |
| Write an agent | The Agent and Session contracts |
| Build your own host | createHost and the ports |
| AHP compatibility | What this host implements of AHP, command by command |
Every document is listed in docs/README.md, one line each.
Tips, PRs, and contributions are welcome!
Read DEVELOPER.md for detailed development guidelines.
Discuss development, issues, and ideas on the GitHub Discussions page.
Any development starts with cloning or forking the repository and installing dependencies.
git clone https://github.com/softov/ahpd
cd ahpd
pnpm install
pnpm build
pnpm test
pnpm typecheckProtocol captures can be checked against the strict schema:
pnpm wire -- packages/sdk/test/fixtures/wire.jsonlahpd is open source and released under the MIT license.
Run it on your own infrastructure. Choose your agents, configure your tools, and build the environment that works for you.
Use it for a personal project, a development team, or an application that needs agent capabilities.
Your infrastructure. Your agents. Your workflow.
ahpd is part of ahpio, the Agent Host Platform. Get to know the whole platform at ahpio.com.