1# Agent Server Extensions
2
3<div class="warning">
4
5Note that starting from `v0.221`.x, [the ACP Registry](https://agentclientprotocol.com/registry) is the preferred way to install external agents in Zed.
6You can learn more about it in [the release blog post](https://zed.dev/blog/acp-registry)
7
8At some point in the near future, Agent Server extensions will be deprecated.
9
10</div>
11
12Agent Servers are programs that provide AI agent implementations through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com).
13Agent 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.
14
15You 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).
16
17## Defining Agent Server Extensions
18
19An extension can register one or more agent servers in the `extension.toml`:
20
21```toml
22[agent_servers.my-agent]
23name = "My Agent"
24
25[agent_servers.my-agent.targets.darwin-aarch64]
26archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-darwin-arm64.tar.gz"
27cmd = "./agent"
28args = ["--serve"]
29
30[agent_servers.my-agent.targets.linux-x86_64]
31archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-linux-x64.tar.gz"
32cmd = "./agent"
33args = ["--serve"]
34
35[agent_servers.my-agent.targets.windows-x86_64]
36archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-windows-x64.zip"
37cmd = "./agent.exe"
38args = ["--serve"]
39```
40
41### Required Fields
42
43- `name`: A human-readable display name for the agent server (shown in menus)
44- `targets`: Platform-specific configurations for downloading and running the agent
45
46### Target Configuration
47
48Each target key uses the format `{os}-{arch}` where:
49
50- **os**: `darwin` (macOS), `linux`, or `windows`
51- **arch**: `aarch64` (ARM64) or `x86_64`
52
53Each target must specify:
54
55- `archive`: URL to download the archive from (supports `.tar.gz`, `.zip`, etc.)
56- `cmd`: Command to run the agent server (relative to the extracted archive)
57- `args`: Command-line arguments to pass to the agent server (optional)
58- `sha256`: SHA-256 hash string of the archive's bytes (optional, but recommended for security)
59- `env`: Environment variables specific to this target (optional, overrides agent-level env vars with the same name)
60
61### Optional Fields
62
63You can also optionally specify at the agent server level:
64
65- `env`: Environment variables to set in the agent's spawned process. These apply to all targets by default.
66- `icon`: Path to an SVG icon (relative to extension root) for display in menus.
67
68### Environment Variables
69
70Environment variables can be configured at two levels:
71
721. **Agent-level** (`[agent_servers.my-agent.env]`): Variables that apply to all platforms
732. **Target-level** (`[agent_servers.my-agent.targets.{platform}.env]`): Variables specific to a platform
74
75When both are specified, target-level environment variables override agent-level variables with the same name. Variables defined only at the agent level are inherited by all targets.
76
77### Complete Example
78
79Here's a more complete example with all optional fields:
80
81```toml
82[agent_servers.example-agent]
83name = "Example Agent"
84icon = "icon/agent.svg"
85
86[agent_servers.example-agent.env]
87AGENT_LOG_LEVEL = "info"
88AGENT_MODE = "production"
89
90[agent_servers.example-agent.targets.darwin-aarch64]
91archive = "https://github.com/example/agent/releases/download/v2.0.0/agent-darwin-arm64.tar.gz"
92cmd = "./bin/agent"
93args = ["serve", "--port", "8080"]
94sha256 = "abc123def456..."
95
96[agent_servers.example-agent.targets.linux-x86_64]
97archive = "https://github.com/example/agent/releases/download/v2.0.0/agent-linux-x64.tar.gz"
98cmd = "./bin/agent"
99args = ["serve", "--port", "8080"]
100sha256 = "def456abc123..."
101
102[agent_servers.example-agent.targets.linux-x86_64.env]
103AGENT_MEMORY_LIMIT = "2GB" # Linux-specific override
104```
105
106## Installation Process
107
108When a user installs your extension and selects the agent server:
109
1101. Zed downloads the appropriate archive for the user's platform
1112. The archive is extracted to a cache directory
1123. Zed launches the agent using the specified command and arguments
1134. Environment variables are set as configured
1145. The agent server runs in the background, ready to assist the user
115
116Archives are cached locally, so subsequent launches are fast.
117
118## Distribution Best Practices
119
120### Use GitHub Releases
121
122GitHub Releases are a reliable way to distribute agent server binaries:
123
1241. Build your agent for each platform (macOS ARM64, macOS x86_64, Linux x86_64, Windows x86_64)
1252. Package each build as a compressed archive (`.tar.gz` or `.zip`)
1263. Create a GitHub release and upload the archives
1274. Use the release URLs in your `extension.toml`
128
129## SHA-256 Hashes
130
131It's good for security to include SHA-256 hashes of your archives in `extension.toml`. Here's how to generate it:
132
133### macOS and Linux
134
135```bash
136shasum -a 256 agent-darwin-arm64.tar.gz
137```
138
139### Windows
140
141```bash
142certutil -hashfile agent-windows-x64.zip SHA256
143```
144
145Then add that string to your target configuration:
146
147```toml
148[agent_servers.my-agent.targets.darwin-aarch64]
149archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-darwin-arm64.tar.gz"
150cmd = "./agent"
151sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
152```
153
154## Testing
155
156To test your Agent Server Extension:
157
1581. [Install it as a dev extension](./developing-extensions.md#developing-an-extension-locally)
1592. Open the [Agent Panel](../ai/agent-panel.md)
1603. Select your Agent Server from the list
1614. Verify that it downloads, installs, and launches correctly
1625. Test its functionality by conversing with it and watching the [ACP logs](../ai/external-agents.md#debugging-agents)
163
164## Icon Guideline
165
166In case your agent server has a logo, we highly recommend adding it as an SVG icon.
167For optimal display, follow these guidelines:
168
169- Make sure you resize your SVG to fit a 16x16 bounding box, with a padding of around one or two pixels
170- Ensure you have a clean SVG code by processing it through [SVGOMG](https://jakearchibald.github.io/svgomg/)
171- Avoid including icons with gradients as they will often make the SVG more complicated and possibly not render perfectly
172
173Note that we'll automatically convert your icon to monochrome to preserve Zed's design consistency.
174(You can still use opacity in different paths of your SVG to add visual layering.)
175
176---
177
178This is all you need to distribute an agent server through Zed's extension system!
179
180## Publishing
181
182Once 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.