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 current Agent Server Extensions by opening the Extensions tab in Zed (execute the `zed: extensions` command) 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
112```bash
113shasum -a 256 agent-darwin-arm64.tar.gz
114```
115
116### Windows
117
118```bash
119certutil -hashfile agent-windows-x64.zip SHA256
120```
121
122Then add that string to your target configuration:
123
124```toml
125[agent_servers.my-agent.targets.darwin-aarch64]
126archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-darwin-arm64.tar.gz"
127cmd = "./agent"
128sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
129```
130
131## Testing
132
133To test your Agent Server Extension:
134
1351. [Install it as a dev extension](./developing-extensions.md#developing-an-extension-locally)
1362. Open the [Agent Panel](../ai/agent-panel.md)
1373. Select your Agent Server from the list
1384. Verify that it downloads, installs, and launches correctly
1395. Test its functionality by conversing with it and watching the [ACP logs](../ai/external-agents.md#debugging-agents)
140## Icon Guideline
141
142In case your agent server has a logo, we highly recommend adding it as an SVG icon.
143For optimal display, follow these guidelines:
144
145- Make sure you resize your SVG to fit a 16x16 bounding box, with a padding of around one or two pixels
146- Ensure you have a clean SVG code by processing it through [SVGOMG](https://jakearchibald.github.io/svgomg/)
147- Avoid including icons with gradients as they will often make the SVG more complicated and possibly not render perfectly
148
149Note that we won't include colors; any icon you include will be displayed in monochrome so as to preserve Zed's design consistency.
150This is all you need to distribute an agent server through Zed's extension system!