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