Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.
Rust acpagent-client-protocolai-agentsai-assistantclaudeclaude-codecodexcoding-agentscursorgeminigemini-cligrok-bot-alternativeiosiphonelinuxmacosmcpopen-sourcerustself-hosted
//! The official ACP agent registry (<https://agentclientprotocol.com/registry>):
//! ~40 coding agents with a known-good way to launch each over ACP — an npx or
//! uvx package, or a per-platform binary archive we download on first use.
//!
//! Registry JSON is untrusted input: ids, versions and commands become paths on
//! disk, so they're checked before use.
use crate::LockExt;
use crate::shell;
use anyhow::{Context, Result, anyhow, bail};
use serde_json::Value;
use sha2::{Digest, Sha256};
use std::path::{Component, Path, PathBuf};
use std::sync::Mutex;
use std::time::Duration;
const URL: &str = "https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json";
/// Upstream updates hourly; once a day is plenty for picking agents.
const REFRESH_EVERY: Duration = Duration::from_hours(24);
static CACHE: Mutex<Option<Value>> = Mutex::new(None);
/// How this machine would launch a registry agent.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Launch {
/// A per-platform archive, downloaded once into `~/.codync/agents`.
Download,
Npx,
Uvx,
}
fn cache_file() -> PathBuf {
crate::service::data_dir().join("registry.json")
}
/// Registry agents (from memory, else the on-disk copy).
pub fn agents() -> Vec<Value> {
let mut cache = CACHE.locked();
if cache.is_none() {
*cache = std::fs::read_to_string(cache_file()).ok().and_then(|s| serde_json::from_str(&s).ok());
}
cache.as_ref().and_then(|v| v["agents"].as_array().cloned()).unwrap_or_default()
}
pub fn agent(id: &str) -> Option<Value> {
agents().into_iter().find(|a| a["id"] == id)
}
/// Replaces the registry for a test, which serializes on `TestSearchPath` and puts `None` back.
#[cfg(test)]
pub(crate) fn set_cache(registry: Option<Value>) {
*CACHE.locked() = registry;
}
pub async fn refresh_loop() {
loop {
match fetch().await {
Ok(v) => {
if let Err(error) = tokio::fs::write(cache_file(), v.to_string()).await {
tracing::warn!(%error, "couldn't cache the ACP registry");
}
*CACHE.locked() = Some(v);
}
Err(error) => {
tracing::info!(error = format!("{error:#}"), "ACP registry refresh failed; using the cached copy");
}
}
tokio::time::sleep(REFRESH_EVERY).await;
}
}
async fn fetch() -> Result<Value> {
let v: Value =
crate::http().get(URL).timeout(Duration::from_secs(20)).send().await?.error_for_status()?.json().await?;
if !v["agents"].is_array() {
bail!("unexpected registry format");
}
Ok(v)
}
pub fn platform() -> Option<&'static str> {
Some(match (std::env::consts::OS, std::env::consts::ARCH) {
("macos", "aarch64") => "darwin-aarch64",
("macos", "x86_64") => "darwin-x86_64",
("linux", "aarch64") => "linux-aarch64",
("linux", "x86_64") => "linux-x86_64",
("windows", "aarch64") => "windows-aarch64",
("windows", "x86_64") => "windows-x86_64",
_ => return None,
})
}
/// This machine's build in a registry `distribution`.
fn binary(distribution: &Value) -> Option<&Value> {
binary_for(distribution, platform()?)
}
/// Windows on ARM falls back to the x64 build, which Windows 11 runs through Prism.
fn binary_for<'a>(distribution: &'a Value, platform: &str) -> Option<&'a Value> {
let prism = (platform == "windows-aarch64").then_some("windows-x86_64");
std::iter::once(platform).chain(prism).map(|p| &distribution["binary"][p]).find(|target| target.is_object())
}
pub fn launch_kind(agent: &Value) -> Option<Launch> {
let d = &agent["distribution"];
let on_path = crate::agent::backends::on_path;
if binary(d).is_some() {
return Some(Launch::Download);
}
if d["npx"].is_object() && on_path("npx") {
return Some(Launch::Npx);
}
if d["uvx"].is_object() && on_path("uvx") {
return Some(Launch::Uvx);
}
None
}
/// The agent runs through `npx` here (no build of its own for this platform).
pub fn needs_node(agent: &Value) -> bool {
let d = &agent["distribution"];
d["npx"].is_object() && binary(d).is_none()
}
fn args_of(v: &Value) -> String {
v["args"]
.as_array()
.map(|a| a.iter().filter_map(Value::as_str).map(shell::quote).collect::<Vec<_>>().join(" "))
.unwrap_or_default()
}
/// `KEY=value ` pairs from a registry `env` object.
pub fn env_prefix(env: &Value) -> String {
shell::env_prefix(env.as_object().into_iter().flatten().filter_map(|(k, v)| Some((k.as_str(), v.as_str()?))))
}
/// One path component made only of `[A-Za-z0-9._-]` and not `.`/`..`.
fn safe_component(s: &str) -> Option<&str> {
let ok = !s.is_empty()
&& s != "."
&& s != ".."
&& s.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-'));
ok.then_some(s)
}
/// A relative path that stays inside its base directory (no `..`, no root).
fn contained(rel: &str) -> Option<&Path> {
let p = Path::new(rel);
p.components().all(|c| matches!(c, Component::Normal(_) | Component::CurDir)).then_some(p)
}
/// How to run a registry agent: `program` alone (what ACP `terminal` sign-in
/// methods add their own args to) and `args` for its ACP mode.
pub struct Cmd {
pub program: String,
pub args: String,
}
impl Cmd {
/// The shell command that starts it over ACP stdio.
pub fn acp(&self) -> String {
if self.args.is_empty() { self.program.clone() } else { format!("{} {}", self.program, self.args) }
}
}
/// One way to start an agent. A registry build is resolved only when it's tried: that can mean a
/// download, which an installed CLI that starts never needs.
pub enum Candidate {
/// Runs as it is: an installed CLI's own ACP mode, or a bot's own command.
Ready(Cmd),
/// A registry agent, downloaded first if needed.
Build(Value),
}
impl Candidate {
/// `progress` receives short status lines ("Downloading Cursor…").
pub async fn resolve(self, progress: impl Fn(&str)) -> Result<Cmd> {
match self {
Self::Ready(cmd) => Ok(cmd),
Self::Build(agent) => command(&agent, progress).await,
}
}
}
/// Downloads the agent first if needed.
/// `progress` receives short status lines ("Downloading Cursor…").
pub async fn command(agent: &Value, progress: impl Fn(&str)) -> Result<Cmd> {
let name = agent["name"].as_str().unwrap_or("agent");
let d = &agent["distribution"];
match launch_kind(agent) {
Some(Launch::Download) => {
let target = binary(d).ok_or_else(|| anyhow!("no download for this platform"))?;
let cmd =
target["cmd"].as_str().and_then(contained).ok_or_else(|| anyhow!("registry entry has a bad cmd"))?;
let dir = install_binary(agent, target, cmd, &progress).await?;
Ok(Cmd {
program: format!("{}{}", env_prefix(&target["env"]), shell::quote(&dir.join(cmd).to_string_lossy())),
args: args_of(target),
})
}
Some(Launch::Npx) => {
prepare_npx(d["npx"]["package"].as_str().unwrap_or_default(), name, &progress).await?;
Ok(npx_cmd(&d["npx"]))
}
Some(Launch::Uvx) => Ok(Cmd {
program: format!(
"{}uvx {}",
env_prefix(&d["uvx"]["env"]),
shell::quote(d["uvx"]["package"].as_str().unwrap_or_default())
),
args: args_of(&d["uvx"]),
}),
None if needs_node(agent) => bail!("{name} needs Node.js on this computer: add it in Extensions"),
None => bail!("{name} has no build for this computer (needs uv)"),
}
}
fn npx_cmd(npx: &Value) -> Cmd {
Cmd {
program: format!(
"{}npx -y {}",
env_prefix(&npx["env"]),
shell::quote(npx["package"].as_str().unwrap_or_default())
),
args: args_of(npx),
}
}
/// npx installs a package into `<npm cache>/_npx/<hash>` and writes its `package.json` last.
/// An install cut short (the first Codex download takes minutes, longer than the ACP handshake
/// may) leaves the packages without their bin links, and npx then fails with "command not
/// found" on every later run. So the download happens here, without the handshake's timeout,
/// and a half-finished one is started over.
async fn prepare_npx(package: &str, name: &str, progress: &impl Fn(&str)) -> Result<()> {
static INSTALLING: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
let _one_at_a_time = INSTALLING.lock().await;
let dir = npm_cache().await?.join("_npx").join(npx_hash(package));
if tokio::fs::try_exists(dir.join("package.json")).await.unwrap_or(false) {
return Ok(());
}
let _ = tokio::fs::remove_dir_all(&dir).await;
progress(&format!("Downloading {name}…"));
let install = tokio::process::Command::new(shell::program("npm"))
// `exit 0`, not `true`: on Windows npm runs `-c` in cmd.exe, which has no `true`.
.args(["exec", "--yes", "--package", package, "-c", "exit 0"])
// Away from any project, so npx doesn't settle for a local node_modules.
.current_dir(crate::service::data_dir())
.stdin(std::process::Stdio::null())
.kill_on_drop(true)
.output();
let failure = match tokio::time::timeout(Duration::from_mins(20), install).await {
Ok(Ok(out)) if out.status.success() => return Ok(()),
Ok(Ok(out)) => npm_error(&String::from_utf8_lossy(&out.stderr)).to_owned(),
Ok(Err(e)) => format!("{e}"),
Err(_) => "timed out".to_owned(),
};
let _ = tokio::fs::remove_dir_all(&dir).await;
bail!("couldn't download {name} with npm: {failure}")
}
/// The line of npm's stderr that says what went wrong: its own `npm notice` lines (a newer npm
/// is out) come after the error.
fn npm_error(stderr: &str) -> &str {
stderr.lines().map(str::trim).rfind(|l| !l.is_empty() && !l.starts_with("npm notice")).unwrap_or_default()
}
/// `npm config get cache`, asked once.
async fn npm_cache() -> Result<&'static Path> {
static DIR: tokio::sync::OnceCell<PathBuf> = tokio::sync::OnceCell::const_new();
let dir = DIR
.get_or_try_init(|| async {
let out = tokio::process::Command::new(shell::program("npm"))
.args(["config", "get", "cache"])
.stdin(std::process::Stdio::null())
.output()
.await
.context("running npm")?;
let dir = String::from_utf8_lossy(&out.stdout).trim().to_owned();
if !out.status.success() || dir.is_empty() {
bail!("npm didn't report its cache directory");
}
Ok(PathBuf::from(dir))
})
.await?;
Ok(dir)
}
/// npx's cache key for one package spec (libnpmexec: the first 16 hex digits of its SHA-512).
fn npx_hash(package: &str) -> String {
use std::fmt::Write as _;
sha2::Sha512::digest(package.as_bytes())[..8].iter().fold(String::with_capacity(16), |mut s, b| {
let _ = write!(s, "{b:02x}");
s
})
}
pub(crate) fn sha256_hex(bytes: &[u8]) -> String {
use std::fmt::Write as _;
Sha256::digest(bytes).iter().fold(String::with_capacity(64), |mut s, b| {
let _ = write!(s, "{b:02x}");
s
})
}
/// `~/.codync/agents/<id>/<version>`, where a binary distribution is unpacked.
fn binary_dir(agent: &Value) -> Result<PathBuf> {
let id = agent["id"].as_str().and_then(safe_component).ok_or_else(|| anyhow!("registry entry has a bad id"))?;
let version = agent["version"].as_str().and_then(safe_component).unwrap_or("latest");
Ok(crate::service::data_dir().join("agents").join(id).join(version))
}
/// Starting this agent would first install its current build, and with it remove the one before.
pub fn update_pending(agent: &Value) -> bool {
launch_kind(agent) == Some(Launch::Download) && binary_dir(agent).is_ok_and(|dir| !dir.join(".installed").exists())
}
/// Downloads + extracts a binary distribution into [`binary_dir`].
async fn install_binary(agent: &Value, target: &Value, cmd: &Path, progress: &impl Fn(&str)) -> Result<PathBuf> {
// A sign-in check and a usage reading can start the same agent at once: installing side by side,
// each would delete the other's files.
// ponytail: one lock for every agent's install, as npx has. Per agent if one big download holding up another hurts.
static INSTALLING: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
let dir = binary_dir(agent)?;
let installed = async || tokio::fs::try_exists(dir.join(".installed")).await.unwrap_or(false);
if installed().await {
return Ok(dir);
}
let _one_at_a_time = INSTALLING.lock().await;
if installed().await {
return Ok(dir);
}
let id = agent["id"].as_str().unwrap_or("agent");
let url = target["archive"].as_str().ok_or_else(|| anyhow!("registry entry has no archive"))?;
if !url.starts_with("https://") {
bail!("refusing a non-HTTPS download for {id}");
}
progress(&format!("Downloading {}…", agent["name"].as_str().unwrap_or(id)));
let bytes = crate::http()
.get(url)
.timeout(Duration::from_mins(10))
.send()
.await?
.error_for_status()?
.bytes()
.await
.with_context(|| format!("downloading {id}"))?;
if let Some(want) = target["sha256"].as_str()
&& !sha256_hex(&bytes).eq_ignore_ascii_case(want)
{
bail!("download checksum mismatch for {id}");
}
progress("Installing…");
let file_name =
url.rsplit('/').next().and_then(|f| f.split('?').next()).and_then(safe_component).unwrap_or("download");
let (dir2, file_name, cmd) = (dir.clone(), file_name.to_owned(), cmd.to_owned());
tokio::task::spawn_blocking(move || -> Result<()> {
let _ = std::fs::remove_dir_all(&dir2);
std::fs::create_dir_all(&dir2)?;
let archive = dir2.join(file_name);
std::fs::write(&archive, &bytes)?;
extract(&archive, &dir2, &cmd)?;
std::fs::write(dir2.join(".installed"), "")?;
remove_other_versions(&dir2);
Ok(())
})
.await?
.with_context(|| format!("installing {id}"))?;
Ok(dir)
}
/// Registry builds update often; keep only the version just installed.
fn remove_other_versions(installed: &Path) {
let Some(parent) = installed.parent() else { return };
let Ok(entries) = std::fs::read_dir(parent) else { return };
for e in entries.flatten() {
let p = e.path();
if p != installed && p.is_dir() {
let _ = std::fs::remove_dir_all(p);
}
}
}
/// Blocking: unpacks `archive` into `dir` and makes `cmd` executable.
pub(crate) fn extract(archive: &Path, dir: &Path, cmd: &Path) -> Result<()> {
let name = archive.file_name().map(|n| n.to_string_lossy().to_lowercase()).unwrap_or_default();
// Multi-part extensions (`.tar.gz`) rule out `Path::extension`; `name` is already lowercased.
#[allow(clippy::case_sensitive_file_extension_comparisons)]
// Windows' bsdtar (`tar.exe`) reads zips too; it has no `unzip`.
let status = if name.ends_with(".zip") && cfg!(unix) {
std::process::Command::new("unzip").arg("-q").arg("-o").arg(archive).arg("-d").arg(dir).status()
} else if [".zip", ".tar.gz", ".tgz", ".tar.bz2", ".tbz2", ".tar.xz", ".tar"].iter().any(|e| name.ends_with(e)) {
// Both GNU tar and bsdtar refuse `..` members by default.
std::process::Command::new("tar").arg("-xf").arg(archive).arg("-C").arg(dir).status()
} else {
// Raw binary: it *is* the command.
let exe = dir.join(cmd);
if let Some(parent) = exe.parent() {
std::fs::create_dir_all(parent)?;
}
std::fs::rename(archive, &exe)?;
#[cfg(unix)]
chmod_x(&exe)?;
return Ok(());
}
.context("running the extractor")?;
if !status.success() {
bail!("couldn't extract {}", archive.display());
}
let _ = std::fs::remove_file(archive);
#[cfg(unix)]
if dir.join(cmd).exists() {
chmod_x(&dir.join(cmd))?;
}
Ok(())
}
#[cfg(unix)]
fn chmod_x(path: &Path) -> Result<()> {
use std::os::unix::fs::PermissionsExt;
let mut p = std::fs::metadata(path)?.permissions();
p.set_mode(p.mode() | 0o755);
std::fs::set_permissions(path, p)?;
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
#[test]
fn npx_command_is_quoted() {
let npx = json!({"package": "@s/[email protected]", "args": ["--acp", "a b"], "env": {"K": "v", "BAD;rm": "x"}});
let expected =
if cfg!(windows) { "K=v npx -y @s/[email protected] --acp \"a b\"" } else { "env K=v npx -y @s/[email protected] --acp 'a b'" };
assert_eq!(npx_cmd(&npx).acp(), expected);
}
#[test]
fn npm_errors_skip_its_update_notice() {
let stderr = "'true' is not recognized as an internal or external command\n\
npm notice New major version of npm available! 10.9.2 -> 11.6.2\n\
npm notice To update run: npm install -g [email protected]\n";
assert_eq!(npm_error(stderr), "'true' is not recognized as an internal or external command");
assert_eq!(npm_error(""), "");
}
#[test]
fn npx_hash_matches_npm() {
// ~/.npm/_npx/317ff93dc6c5b519 after `npx -y @agentclientprotocol/[email protected]`.
assert_eq!(npx_hash("@agentclientprotocol/[email protected]"), "317ff93dc6c5b519");
}
#[test]
fn keeps_only_the_installed_version() {
let root = std::env::temp_dir().join(format!("codync-ver-{}", uuid::Uuid::new_v4()));
for v in ["1.0.0", "1.1.0"] {
std::fs::create_dir_all(root.join(v)).unwrap();
}
remove_other_versions(&root.join("1.1.0"));
assert!(!root.join("1.0.0").exists());
assert!(root.join("1.1.0").exists());
}
#[cfg(unix)]
#[test]
fn raw_binary_extract_marks_executable() {
use std::os::unix::fs::PermissionsExt;
let dir = std::env::temp_dir().join(format!("codync-reg-{}", uuid::Uuid::new_v4()));
std::fs::create_dir_all(&dir).unwrap();
let archive = dir.join("tool-darwin");
let contents = b"#!/bin/sh\necho hi\n";
std::fs::write(&archive, contents).unwrap();
extract(&archive, &dir, Path::new("./bin/tool")).unwrap();
let executable = dir.join("bin/tool");
assert_eq!(std::fs::read(&executable).unwrap(), contents);
assert_eq!(std::fs::metadata(&executable).unwrap().permissions().mode() & 0o111, 0o111);
assert!(!archive.exists());
std::fs::remove_dir_all(&dir).unwrap();
}
#[test]
fn windows_on_arm_falls_back_to_the_x64_binary() {
let x64 = json!({"binary": {"windows-x86_64": {"cmd": "./x64.exe"}}});
assert_eq!(binary_for(&x64, "windows-aarch64"), Some(&x64["binary"]["windows-x86_64"]));
assert_eq!(binary_for(&x64, "linux-aarch64"), None);
let both = json!({"binary": {"windows-x86_64": {"cmd": "./x64.exe"}, "windows-aarch64": {"cmd": "./arm.exe"}}});
assert_eq!(binary_for(&both, "windows-aarch64"), Some(&both["binary"]["windows-aarch64"]));
}
#[test]
fn registry_paths_cannot_escape_the_agents_dir() {
assert_eq!(safe_component("cursor"), Some("cursor"));
assert_eq!(safe_component("1.0.3-beta"), Some("1.0.3-beta"));
for bad in ["", ".", "..", "a/b", "../x", "x y"] {
assert_eq!(safe_component(bad), None, "{bad:?}");
}
assert!(contained("./dist-package/cursor-agent").is_some());
assert!(contained("../../bin/sh").is_none());
assert!(contained("/bin/sh").is_none());
}
}