1# Agent Server Extensions
2
3Agent Servers are programs that provide AI agent implementations through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com). Agent Server Extensions let you package up an Agent Server so that users can install the extension and have your agent easily available to use in Zed.
4
5You can see the agent servers that have already been exposed as extensions on [https://zed.dev/extensions](https://zed.dev/extensions?filter=agent-servers).
6
7## Defining Agent Server Extensions
8
9An extension can register one or more agent servers in the `extension.toml` like so:
10
11```toml
12[agent_servers.my-agent]
13name = "My Agent"
14
15[agent_servers.my-agent.targets.darwin-aarch64]
16archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-darwin-arm64.tar.gz"
17cmd = "./agent"
18args = ["--serve"]
19
20[agent_servers.my-agent.targets.linux-x86_64]
21archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-linux-x64.tar.gz"
22cmd = "./agent"
23args = ["--serve"]
24
25[agent_servers.my-agent.targets.windows-x86_64]
26archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-windows-x64.zip"
27cmd = "./agent.exe"
28args = ["--serve"]
29```
30
31### Required Fields
32
33- `name`: A human-readable display name for the agent server (shown in menus)
34- `targets`: Platform-specific configurations for downloading and running the agent
35
36### Target Configuration
37
38Each target key uses the format `{os}-{arch}` where:
39
40- **os**: `darwin` (macOS), `linux`, or `windows`
41- **arch**: `aarch64` (ARM64) or `x86_64`
42
43Each target must specify:
44
45- `archive`: URL to download the archive from (supports `.tar.gz`, `.zip`, etc.)
46- `cmd`: Command to run the agent server (relative to the extracted archive)
47- `args`: Command-line arguments to pass to the agent server (optional)
48
49### Optional Fields
50
51You can also optionally specify:
52
53- `sha256`: SHA-256 hash string of the archive's bytes. Zed will check this after the archive is downloaded and give an error if it doesn't match, so doing this improves security.
54- `env`: Environment variables to set in the agent's spawned process.
55- `icon`: Path to an SVG icon (relative to extension root) for display in menus.
56
57### Complete Example
58
59Here's a more complete example with all optional fields:
60
61```toml
62[agent_servers.example-agent]
63name = "Example Agent"
64icon = "icon/agent.svg"
65
66[agent_servers.example-agent.env]
67AGENT_LOG_LEVEL = "info"
68AGENT_MODE = "production"
69
70[agent_servers.example-agent.targets.darwin-aarch64]
71archive = "https://github.com/example/agent/releases/download/v2.0.0/agent-darwin-arm64.tar.gz"
72cmd = "./bin/agent"
73args = ["serve", "--port", "8080"]
74sha256 = "abc123def456..."
75
76[agent_servers.example-agent.targets.linux-x86_64]
77archive = "https://github.com/example/agent/releases/download/v2.0.0/agent-linux-x64.tar.gz"
78cmd = "./bin/agent"
79args = ["serve", "--port", "8080"]
80sha256 = "def456abc123..."
81```
82
83## Installation Process
84
85When a user installs your extension and selects the agent server:
86
871. Zed downloads the appropriate archive for the user's platform
882. The archive is extracted to a cache directory
893. Zed launches the agent using the specified command and arguments
904. Environment variables are set as configured
915. The agent server runs in the background, ready to assist the user
92
93Archives are cached locally, so subsequent launches are fast.
94
95## Distribution Best Practices
96
97### Use GitHub Releases
98
99GitHub Releases are a reliable way to distribute agent server binaries:
100
1011. Build your agent for each platform (macOS ARM64, macOS x86_64, Linux x86_64, Windows x86_64)
1022. Package each build as a compressed archive (`.tar.gz` or `.zip`)
1033. Create a GitHub release and upload the archives
1044. Use the release URLs in your `extension.toml`
105
106## SHA-256 Hashes
107
108It's good for security to include SHA-256 hashes of your archives in `extension.toml`. Here's how to generate it:
109
110### macOS and Linux
111```bash
112shasum -a 256 agent-darwin-arm64.tar.gz
113```
114
115### Windows
116```bash
117certutil -hashfile agent-windows-x64.zip SHA256
118```
119
120Then add that string to your target configuration:
121
122```toml
123[agent_servers.my-agent.targets.darwin-aarch64]
124archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-darwin-arm64.tar.gz"
125cmd = "./agent"
126sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
127```
128
129## Testing
130
131To test your Agent Server Extension:
132
1331. [Install it as a dev extension](./developing-extensions.md#developing-an-extension-locally)
1342. Open the [Agent Panel](../ai/agent-panel.md)
1353. Select your Agent Server from the list
1364. Verify that it downloads, installs, and launches correctly
1375. Test its functionality by conversing with it and watching the [ACP logs](../ai/external-agents.md#debugging-agents)
138
139This is all you need to distribute an agent server through Zed's extension system!