use std::path::{Path, PathBuf};
use anyhow::Context;
use crate::daemon;
use super::common;
use super::{before_terminator, exec_with_env, find_on_path, has_flag, server};
const DOCKER_AGENT_API_KEY_ENV: &str = "LLMMAN_API_KEY";
const DOCKER_AGENT_MODEL_NAME: &str = "llmman";
pub(super) fn launch_docker_agent(
model: &str,
api_key: &str,
extra_args: &[String],
) -> anyhow::Result<()> {
check_docker_agent_args(extra_args)?;
let bin = find_docker_agent().ok_or_else(docker_agent_missing)?;
let path = docker_agent_agent_file(&docker_agent_config_dir()?, model);
write_docker_agent_file(&path, model, &format!("{}/v1", server()))?;
let args = docker_agent_args(&path, extra_args);
exec_with_env(&bin, &args, &[(DOCKER_AGENT_API_KEY_ENV, api_key)])
}
pub(super) fn docker_agent_missing() -> anyhow::Error {
anyhow::anyhow!(
"docker-agent is not installed\n\n\
llmman looks for it on PATH and in ~/.docker/cli-plugins, where Docker Desktop \
and `brew install docker-agent` put it.\n\
Releases: https://github.com/docker/docker-agent/releases"
)
}
pub(super) fn check_docker_agent_args(extra_args: &[String]) -> anyhow::Result<()> {
if has_flag(before_terminator(extra_args), "--model", None) {
anyhow::bail!(
"docker-agent's --model would replace the endpoint llmman configured and send the \
request to api.openai.com; select the model with `llmman launch docker-agent \
--model <model>` instead"
);
}
if let Some(file) = docker_agent_config_argument(extra_args) {
anyhow::bail!(docker_agent_own_agent_file_error(file));
}
Ok(())
}
fn docker_agent_own_agent_file_error(file: &str) -> String {
format!(
"llmman launch docker-agent passes its own agent file, so `{file}` would be read as a \
message rather than an agent.\n\
To run your own agent against this daemon, point its model at llmman and run \
docker-agent directly:\n \
models:\n {DOCKER_AGENT_MODEL_NAME}:\n provider: openai\n \
model: <model>\n base_url: {}/v1\n \
token_key: {DOCKER_AGENT_API_KEY_ENV}\n \
agents:\n root:\n model: {DOCKER_AGENT_MODEL_NAME}",
daemon::server()
)
}
pub(super) fn docker_agent_config_dir() -> anyhow::Result<PathBuf> {
let conf = crate::config::user_path().context("no home directory")?;
let dir = conf.parent().context("llmman.conf has no directory")?;
Ok(dir.join("launch").join("docker-agent"))
}
fn docker_agent_agent_file(dir: &Path, model: &str) -> PathBuf {
dir.join(format!("agent-{}.yaml", docker_agent_file_stem(model)))
}
const DOCKER_AGENT_NAME_MAX: usize = 80;
fn docker_agent_file_stem(model: &str) -> String {
use sha2::Digest as _;
let safe: String = model
.chars()
.map(|c| {
if c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-') {
c
} else {
'-'
}
})
.take(DOCKER_AGENT_NAME_MAX)
.collect();
let digest = hex::encode(sha2::Sha256::digest(model.as_bytes()));
format!("{safe}-{}", &digest[..8])
}
fn write_docker_agent_file(path: &Path, model: &str, base_url: &str) -> anyhow::Result<()> {
if let Some(dir) = path.parent() {
std::fs::create_dir_all(dir).with_context(|| format!("create {}", dir.display()))?;
}
let contents = docker_agent_document(model, base_url);
crate::fsutil::write_atomic(path, contents.as_bytes())
.with_context(|| format!("write {}", path.display()))
}
fn docker_agent_document(model: &str, base_url: &str) -> String {
let quoted_model = common::yaml_quote(model);
let quoted_base_url = common::yaml_quote(base_url);
format!(
"# Written by `llmman launch docker-agent`; edits are overwritten.\n\
version: \"2\"\n\
models:\n {DOCKER_AGENT_MODEL_NAME}:\n provider: openai\n model: {quoted_model}\n \
base_url: {quoted_base_url}\n token_key: {DOCKER_AGENT_API_KEY_ENV}\n\
agents:\n root:\n model: {DOCKER_AGENT_MODEL_NAME}\n \
description: The agent `llmman launch docker-agent` runs.\n \
instruction: You are a helpful AI assistant with access to the shell and \
the filesystem.\n \
toolsets:\n - type: shell\n - type: filesystem\n"
)
}
fn docker_agent_args(path: &Path, extra_args: &[String]) -> Vec<String> {
let mut args = vec!["run".to_string(), path.to_string_lossy().into_owned()];
args.extend_from_slice(extra_args);
args
}
fn docker_agent_config_argument(extra_args: &[String]) -> Option<&String> {
docker_agent_config_argument_with(extra_args, |path| Path::new(path).is_file())
}
fn docker_agent_config_argument_with(
extra_args: &[String],
exists: impl Fn(&str) -> bool,
) -> Option<&String> {
const EXTENSIONS: &[&str] = &[".yaml", ".yml", ".hcl"];
let first = extra_args.first()?;
if first.starts_with('-') {
return None;
}
let lowered = first.to_lowercase();
let named_like_one = EXTENSIONS.iter().any(|ext| lowered.ends_with(ext));
(named_like_one && exists(first)).then_some(first)
}
pub(super) fn find_docker_agent() -> Option<PathBuf> {
find_on_path("docker-agent").or_else(|| docker_agent_fallback(&dirs::home_dir()?))
}
fn docker_agent_fallback(home: &Path) -> Option<PathBuf> {
let binary = if cfg!(windows) {
"docker-agent.exe"
} else {
"docker-agent"
};
let candidate = home.join(".docker").join("cli-plugins").join(binary);
candidate.is_file().then_some(candidate)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn docker_agent_args_lead_with_run_and_the_generated_agent_file() {
let path = Path::new("/tmp/llmman/agent.yaml");
let extra = ["--exec".to_string(), "say pong".to_string()];
assert_eq!(
docker_agent_args(path, &extra),
vec![
"run".to_string(),
"/tmp/llmman/agent.yaml".to_string(),
"--exec".to_string(),
"say pong".to_string(),
]
);
assert_eq!(
docker_agent_args(path, &[]),
vec!["run".to_string(), "/tmp/llmman/agent.yaml".to_string()]
);
}
#[test]
fn docker_agent_document_routes_an_openai_provider_model_at_the_daemon() {
let document = docker_agent_document("m", "http://127.0.0.1:17434/v1");
assert!(document.contains("provider: openai"), "{document}");
assert!(document.contains("model: \"m\""), "{document}");
assert!(
document.contains("base_url: \"http://127.0.0.1:17434/v1\""),
"{document}"
);
assert!(
document.contains(&format!(" {DOCKER_AGENT_MODEL_NAME}:")),
"{document}"
);
assert!(
document.contains(&format!("model: {DOCKER_AGENT_MODEL_NAME}\n")),
"{document}"
);
}
#[test]
fn docker_agent_document_names_the_key_variable_rather_than_a_key() {
let document = docker_agent_document("m", "http://127.0.0.1:17434/v1");
assert!(
document.contains(&format!("token_key: {DOCKER_AGENT_API_KEY_ENV}")),
"{document}"
);
assert!(!document.contains("api_key"), "{document}");
assert!(!document.contains("sk-"), "{document}");
}
#[test]
fn docker_agent_document_gives_the_agent_shell_and_filesystem() {
let document = docker_agent_document("m", "http://127.0.0.1:17434/v1");
assert!(document.contains("instruction:"), "{document}");
assert!(document.contains("toolsets:"), "{document}");
assert!(document.contains("- type: shell"), "{document}");
assert!(document.contains("- type: filesystem"), "{document}");
}
#[test]
fn docker_agent_document_quotes_the_values_it_interpolates() {
let document = docker_agent_document("docker.io/ai/qwen3.5:0.8b", "http://h:1/v1");
assert!(
document.contains("model: \"docker.io/ai/qwen3.5:0.8b\""),
"{document}"
);
assert!(
document.contains("base_url: \"http://h:1/v1\""),
"{document}"
);
}
#[test]
fn docker_agent_spots_a_caller_supplied_agent_file() {
for file in ["team.yaml", "./agent.yml", "/tmp/AGENT.YAML", "infra.hcl"] {
let extra = [file.to_string(), "do the thing".to_string()];
assert_eq!(
docker_agent_config_argument_with(&extra, |_| true).map(String::as_str),
Some(file),
"{file} was not recognized as an agent file"
);
}
}
#[test]
fn docker_agent_does_not_mistake_a_message_or_a_flag_value_for_an_agent_file() {
let cases: &[(&str, &[&str])] = &[
(
"a message that ends in .yaml",
&["--exec", "summarize the config.yaml"],
),
("a flag's value", &["--prompt-file", "notes.yaml"]),
("a leading flag", &["--exec", "--yolo", "say pong"]),
("a question about a file", &["what does agent.yaml do?"]),
];
for (why, args) in cases {
let extra: Vec<String> = args.iter().map(|a| a.to_string()).collect();
assert_eq!(
docker_agent_config_argument_with(&extra, |_| true),
None,
"refused {why}: {args:?}"
);
}
let absent = ["explain agent.yaml".to_string()];
assert_eq!(docker_agent_config_argument_with(&absent, |_| false), None);
}
#[test]
fn docker_agent_names_its_agent_file_after_the_model() {
let dir = Path::new("/tmp/llmman/launch/docker-agent");
let file = |model: &str| docker_agent_agent_file(dir, model);
let name = |model: &str| {
file(model)
.file_name()
.and_then(|n| n.to_str())
.unwrap()
.to_string()
};
assert!(
name("docker.io/ai/qwen3.5:0.8b").starts_with("agent-docker.io-ai-qwen3.5-0.8b-"),
"{}",
name("docker.io/ai/qwen3.5:0.8b")
);
for (one, other) in [
("docker.io/ai/qwen3.5:0.8b", "docker.io/ai/qwen3.5:9b"),
("docker.io/ai/qwen3.5:0.8b", "docker.io/ai/gemma4:12b"),
("qwen/qwen3-coder", "qwen/qwen3-max"),
("a/b-c:d", "a/b:c-d"),
(
&format!("{}one", "m".repeat(DOCKER_AGENT_NAME_MAX)),
&format!("{}two", "m".repeat(DOCKER_AGENT_NAME_MAX)),
),
] {
assert_ne!(file(one), file(other), "{one} and {other} share a file");
}
assert!(name(&"x".repeat(4096)).len() <= 255, "name is unbounded");
for model in ["a/b", "a:b", "a\\b", "a b", "a*b", "a?b", "a\"b", "..", "."] {
let file = docker_agent_agent_file(dir, model);
assert_eq!(file.parent(), Some(dir), "{model} escaped its directory");
let name = file.file_name().and_then(|n| n.to_str()).unwrap();
assert!(
name.starts_with("agent-") && name.ends_with(".yaml"),
"{name}"
);
assert!(
!name.contains(std::path::MAIN_SEPARATOR) && name != ".." && name != ".",
"{model} produced {name}"
);
}
}
#[test]
fn docker_agent_fallback_finds_the_cli_plugin_directory() {
let home = std::env::temp_dir().join(format!(
"llmman-docker-agent-{}-{}",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
));
let plugins = home.join(".docker").join("cli-plugins");
std::fs::create_dir_all(&plugins).unwrap();
assert_eq!(docker_agent_fallback(&home), None);
let binary = plugins.join(if cfg!(windows) {
"docker-agent.exe"
} else {
"docker-agent"
});
std::fs::create_dir(&binary).unwrap();
assert_eq!(
docker_agent_fallback(&home),
None,
"a directory is not a binary"
);
std::fs::remove_dir(&binary).unwrap();
std::fs::write(&binary, "").unwrap();
assert_eq!(docker_agent_fallback(&home), Some(binary));
let _ = std::fs::remove_dir_all(&home);
}
#[test]
fn docker_agent_reads_a_model_flag_after_the_terminator_as_a_message() {
let args = |a: &[&str]| a.iter().map(|s| s.to_string()).collect::<Vec<_>>();
assert!(check_docker_agent_args(&args(&["--exec", "--", "--model=foo"])).is_ok());
assert!(check_docker_agent_args(&args(&["--exec", "--", "--model", "foo"])).is_ok());
assert!(check_docker_agent_args(&args(&["--exec", "--model=foo"])).is_err());
assert!(check_docker_agent_args(&args(&["--model", "foo", "--", "hi"])).is_err());
}
#[test]
fn docker_agent_refuses_a_forwarded_model_flag() {
for spelling in ["--model", "--model=openai/gpt-5"] {
let extra = [spelling.to_string(), "openai/gpt-5".to_string()];
let error = launch_docker_agent("m", "k", &extra)
.unwrap_err()
.to_string();
assert!(error.contains("api.openai.com"), "{spelling}: {error}");
}
}
#[test]
fn docker_agent_leaves_an_unrelated_short_flag_to_docker_agent() {
for spelling in ["-m", "-m=openai/gpt-5"] {
let extra = [spelling.to_string(), "openai/gpt-5".to_string()];
assert!(
!has_flag(&extra, "--model", None),
"{spelling} was read as --model"
);
}
assert!(has_flag(&["--model".to_string()], "--model", None));
}
#[test]
fn docker_agent_refuses_a_caller_supplied_agent_file_with_the_way_forward() {
let path = std::env::temp_dir().join(format!(
"llmman-docker-agent-{}-{}.yaml",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
));
std::fs::write(&path, "agents: {}\n").unwrap();
let named = path.to_string_lossy().into_owned();
let error = launch_docker_agent("m", "k", std::slice::from_ref(&named))
.unwrap_err()
.to_string();
let _ = std::fs::remove_file(&path);
assert!(error.contains(&named), "{error}");
assert!(error.contains("provider: openai"), "{error}");
assert!(error.contains(DOCKER_AGENT_API_KEY_ENV), "{error}");
}
#[test]
fn docker_agent_agent_file_error_does_not_escape_a_windows_path() {
let windows = r"C:\Users\me\AppData\Local\Temp\team.yaml";
let error = docker_agent_own_agent_file_error(windows);
assert!(error.contains(windows), "{error}");
assert!(!error.contains(r"\\"), "separators were doubled: {error}");
}
}