1# Agent Server Extensions
2
3Agent Servers are programs that provide AI agent implementations through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com).
4Agent 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.
5
6You can see the current Agent Server extensions either by opening the Extensions tab in Zed (execute the `zed: extensions` command) and changing the filter from `All` to `Agent Servers`, or by visiting [the Zed website](https://zed.dev/extensions?filter=agent-servers).
7
8## Defining Agent Server Extensions
9
10An extension can register one or more agent servers in the `extension.toml` like so:
11
12```toml
13[agent_servers.my-agent]
14name = "My Agent"
15
16[agent_servers.my-agent.targets.darwin-aarch64]
17archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-darwin-arm64.tar.gz"
18cmd = "./agent"
19args = ["--serve"]
20
21[agent_servers.my-agent.targets.linux-x86_64]
22archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-linux-x64.tar.gz"
23cmd = "./agent"
24args = ["--serve"]
25
26[agent_servers.my-agent.targets.windows-x86_64]
27archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-windows-x64.zip"
28cmd = "./agent.exe"
29args = ["--serve"]
30```
31
32### Required Fields
33
34- `name`: A human-readable display name for the agent server (shown in menus)
35- `targets`: Platform-specific configurations for downloading and running the agent
36
37### Target Configuration
38
39Each target key uses the format `{os}-{arch}` where:
40
41- **os**: `darwin` (macOS), `linux`, or `windows`
42- **arch**: `aarch64` (ARM64) or `x86_64`
43
44Each target must specify:
45
46- `archive`: URL to download the archive from (supports `.tar.gz`, `.zip`, etc.)
47- `cmd`: Command to run the agent server (relative to the extracted archive)
48- `args`: Command-line arguments to pass to the agent server (optional)
49
50### Optional Fields
51
52You can also optionally specify:
53
54- `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.
55- `env`: Environment variables to set in the agent's spawned process.
56- `icon`: Path to an SVG icon (relative to extension root) for display in menus.
57
58### Complete Example
59
60Here's a more complete example with all optional fields:
61
62```toml
63[agent_servers.example-agent]
64name = "Example Agent"
65icon = "icon/agent.svg"
66
67[agent_servers.example-agent.env]
68AGENT_LOG_LEVEL = "info"
69AGENT_MODE = "production"
70
71[agent_servers.example-agent.targets.darwin-aarch64]
72archive = "https://github.com/example/agent/releases/download/v2.0.0/agent-darwin-arm64.tar.gz"
73cmd = "./bin/agent"
74args = ["serve", "--port", "8080"]
75sha256 = "abc123def456..."
76
77[agent_servers.example-agent.targets.linux-x86_64]
78archive = "https://github.com/example/agent/releases/download/v2.0.0/agent-linux-x64.tar.gz"
79cmd = "./bin/agent"
80args = ["serve", "--port", "8080"]
81sha256 = "def456abc123..."
82```
83
84## Installation Process
85
86When a user installs your extension and selects the agent server:
87
881. Zed downloads the appropriate archive for the user's platform
892. The archive is extracted to a cache directory
903. Zed launches the agent using the specified command and arguments
914. Environment variables are set as configured
925. The agent server runs in the background, ready to assist the user
93
94Archives are cached locally, so subsequent launches are fast.
95
96## Distribution Best Practices
97
98### Use GitHub Releases
99
100GitHub Releases are a reliable way to distribute agent server binaries:
101
1021. Build your agent for each platform (macOS ARM64, macOS x86_64, Linux x86_64, Windows x86_64)
1032. Package each build as a compressed archive (`.tar.gz` or `.zip`)
1043. Create a GitHub release and upload the archives
1054. Use the release URLs in your `extension.toml`
106
107## SHA-256 Hashes
108
109It's good for security to include SHA-256 hashes of your archives in `extension.toml`. Here's how to generate it:
110
111### macOS and Linux
112
113```bash
114shasum -a 256 agent-darwin-arm64.tar.gz
115```
116
117### Windows
118
119```bash
120certutil -hashfile agent-windows-x64.zip SHA256
121```
122
123Then add that string to your target configuration:
124
125```toml
126[agent_servers.my-agent.targets.darwin-aarch64]
127archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-darwin-arm64.tar.gz"
128cmd = "./agent"
129sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
130```
131
132## Testing
133
134To test your Agent Server Extension:
135
1361. [Install it as a dev extension](./developing-extensions.md#developing-an-extension-locally)
1372. Open the [Agent Panel](../ai/agent-panel.md)
1383. Select your Agent Server from the list
1394. Verify that it downloads, installs, and launches correctly
1405. Test its functionality by conversing with it and watching the [ACP logs](../ai/external-agents.md#debugging-agents)
141
142## Icon Guideline
143
144In case your agent server has a logo, we highly recommend adding it as an SVG icon.
145For optimal display, follow these guidelines:
146
147- Make sure you resize your SVG to fit a 16x16 bounding box, with a padding of around one or two pixels
148- Ensure you have a clean SVG code by processing it through [SVGOMG](https://jakearchibald.github.io/svgomg/)
149- Avoid including icons with gradients as they will often make the SVG more complicated and possibly not render perfectly
150
151Note that we'll automatically convert your icon to monochrome to preserve Zed's design consistency.
152(You can still use opacity in different paths of your SVG to add visual layering.)
153
154---
155
156This is all you need to distribute an agent server through Zed's extension system!
157
158## Publishing
159
160Once your extension is ready, see [Publishing your extension](./developing-extensions.md#publishing-your-extension) to learn how to submit it to the Zed extension registry.