Custom Binary Paths
Relevant source files
The following files were used as context for generating this wiki page:
The Custom Binary Paths feature allows developers to specify a manual location for the cu (Container Use) binary within the Zed editor environment. By default, the extension attempts to discover the binary automatically through the system's execution path; however, users can override this behavior through workspace or global settings. This is particularly useful when the binary is installed in a non-standard directory or when managing multiple versions of the Container Use MCP server.
Sources: README.md:15-18, src/container_use_mcp.rs:25-30
Architecture and Configuration
The system utilizes a hierarchical lookup strategy to determine the executable path. It first checks for a user-defined configuration, then looks for a cached path within the extension state, and finally falls back to a system search using the which command.
Configuration Schema
The custom path is defined within the settings object of the container-use-mcp context server configuration. This is represented internally by the ContainerUseMcpSettings struct, which uses serde for deserialization and schemars to generate a JSON schema for the Zed settings UI.
| Field | Type | Description |
|---|---|---|
cu_path | Option<String> | The absolute path to the cu binary. |
Sources: src/container_use_mcp.rs:11-14, src/container_use_mcp.rs:88-91, extension.toml:13-14
Data Structure Implementation
The extension maintains state through the ContainerUseMcpExtension struct, which includes a field for caching the resolved path to avoid repeated system calls.
struct ContainerUseMcpExtension {
cached_binary_path: Option<String>,
}
Sources: src/container_use_mcp.rs:16-18, Cargo.toml:14-16
Binary Resolution Logic
The resolution process follows a specific priority order. The extension implements the context_server_binary_path method to handle this logic.
Resolution Flow
- Manual Override: The system checks if
cu_pathis provided in thesettings.json. If present, this path is assigned tocached_binary_path. - Cache Verification: If a path exists in the cache, the system verifies its existence on the filesystem using
fs::metadata. - System Discovery: If no manual path is valid, the extension executes a shell command (
which cu) to locate the binary in the user's$PATH.
The following diagram illustrates the decision-making process for binary path resolution:
Execution Environment
Once resolved, the binary is invoked as a Command with the stdio argument. This establishes the MCP communication channel between Zed and the containerized environment.
{
"context_servers": {
"container-use-mcp": {
"settings": {
"cu_path": "/path/to/cu"
}
}
}
}
Sources: README.md:21-29, src/container_use_mcp.rs:81-85
System Requirements and Capabilities
The extension explicitly requests the capability to execute the which process to facilitate binary discovery. This is defined in the extension manifest.
| Component | Requirement | File Reference |
|---|---|---|
| Process Capability | process:exec for which | extension.toml |
| CLI Argument | stdio for MCP communication | src/container_use_mcp.rs |
| Agent Integration | .rules file in project root | configuration/installation_instructions.md |
Sources: extension.toml:16-19, src/container_use_mcp.rs:83, configuration/installation_instructions.md:1-1
Summary
The Custom Binary Paths feature provides a flexible mechanism for integrating the cu binary into Zed. By supporting both automated discovery via system pathing and explicit user overrides through configuration files, the extension ensures compatibility across diverse development environments. The implementation leverages Rust's safety features to validate paths on the filesystem before attempting execution, providing clear error messaging when the binary is missing.