Self-hosted, sharable kanban for humans and agents. One 4.7 MB binary, 5 MB of RAM, 10 to 60 tokens per agent reply, starts in 3 ms, zero setup.
Rust ai-agentsclaude-codeclicodexcoding-agentskanbanlocal-firstmcpmcp-servermodel-context-protocolproductivityproject-managementraspberry-pirustself-hostedsqlitetask-manager
use std::fmt::Write as _;
use std::io;
use std::net::{IpAddr, SocketAddr};
use std::path::{Path, PathBuf};
use std::sync::OnceLock;
use std::time::Duration;
use anyhow::{Context, Result, bail};
use axum::body::Body;
use axum::extract::Request;
use axum::http::{HeaderName, HeaderValue, StatusCode};
use axum::response::{IntoResponse, Response};
use rmcp::model::{ClientConfig, Implementation, ProtocolVersion, RequestMetaObject};
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value, json};
use tokio::io::{AsyncBufReadExt, AsyncReadExt, AsyncWriteExt, BufReader};
use tokio::net::TcpStream;
use tokio_util::io::ReaderStream;
use crate::home::{DEFAULT_PORT, Home};
pub const FILE: &str = "network";
pub const FOLDER_HEADER: &str = "x-kanzo-folder";
pub const REPOS_HEADER: &str = "x-kanzo-repos";
pub const IMAGES_HEADER: &str = "x-kanzo-images";
pub const COMPUTER_HEADER: &str = "x-kanzo-computer";
/// Larger than any image the board takes.
const BODY_LIMIT: usize = 32 * 1024 * 1024;
#[derive(Debug, Clone, PartialEq)]
pub enum Net {
Private,
Sharing,
Joined(String),
}
impl Net {
pub fn load(home: &Home) -> Self {
let text = std::fs::read_to_string(home.dir.join(FILE)).unwrap_or_default();
match text.trim() {
"share" => Net::Sharing,
line => match line.strip_prefix("join ") {
Some(host) => Net::Joined(host.trim().to_string()),
// config.toml can keep the board on the network for good, as before `kanzo share`.
None if !home.config.listen.is_loopback() => Net::Sharing,
None => Net::Private,
},
}
}
fn save(&self, home: &Home) -> io::Result<()> {
let path = home.dir.join(FILE);
match self {
Net::Private => std::fs::remove_file(path)
.or_else(|e| if e.kind() == io::ErrorKind::NotFound { Ok(()) } else { Err(e) }),
Net::Sharing => std::fs::write(path, "share\n"),
Net::Joined(host) => std::fs::write(path, format!("join {host}\n")),
}
}
}
#[derive(Debug, Serialize, Deserialize)]
#[serde(tag = "action", content = "host", rename_all = "lowercase")]
pub enum Change {
On,
Off,
Join(String),
Leave,
}
pub async fn change(home: &Home, change: Change) -> Result<Net, String> {
let now = Net::load(home);
let next = match (change, &now) {
(Change::On, Net::Joined(host)) => {
return Err(format!("This computer uses the board at {host}: run kanzo leave first."));
}
(Change::On, _) => Net::Sharing,
(Change::Off, _) if !home.config.listen.is_loopback() => {
return Err(format!(
"config.toml sets listen = \"{}\", which keeps the board on the network: change it there.",
home.config.listen
));
}
(Change::Off, Net::Sharing) | (Change::Leave, Net::Joined(_)) => Net::Private,
(Change::Off | Change::Leave, _) => now.clone(),
(Change::Join(_), Net::Sharing) => return Err("This board is shared: run kanzo share off first.".into()),
(Change::Join(host), _) => {
let host = address(&host)?;
if !is_kanzo(&host).await {
return Err(format!(
"No shared board at {host}: share it on that computer first, on the same network."
));
}
Net::Joined(host)
}
};
if next != now {
next.save(home).map_err(|e| format!("cannot save {FILE}: {e}"))?;
}
Ok(next)
}
fn address(host: &str) -> Result<String, String> {
let host = host.trim().trim_start_matches("http://").trim_end_matches('/');
if host.is_empty() || !host.chars().all(|c| c.is_ascii_alphanumeric() || ".-:[]".contains(c)) {
return Err(format!("{host:?} isn't an address: pass the one `kanzo share on` printed, like 192.168.0.12."));
}
let full = match host.parse::<IpAddr>() {
Ok(ip) => SocketAddr::new(ip, DEFAULT_PORT).to_string(),
Err(_) if host.rsplit_once(':').is_some_and(|(_, p)| p.parse::<u16>().is_ok()) => host.to_string(),
Err(_) => format!("{host}:{DEFAULT_PORT}"),
};
let local = full.parse::<SocketAddr>().is_ok_and(|a| a.ip().is_loopback() || a.ip().is_unspecified())
|| full.to_ascii_lowercase().starts_with("localhost:");
if local {
return Err("That's this computer: pass the address of the one sharing its board.".into());
}
Ok(full)
}
#[derive(Debug, Serialize, Deserialize)]
pub struct Status {
state: State,
host: Option<String>,
addresses: Vec<String>,
guests: Vec<Guest>,
}
#[derive(Debug, Serialize, Deserialize)]
pub struct Guest {
pub name: Option<String>,
pub address: IpAddr,
}
#[derive(Debug, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
enum State {
Private,
Sharing,
Joined,
}
impl Status {
pub fn new(net: &Net, port: u16, guests: Vec<Guest>) -> Self {
let (state, host, addresses) = match net {
Net::Private => (State::Private, None, vec![]),
Net::Sharing => (State::Sharing, None, addresses(port)),
Net::Joined(host) => (State::Joined, Some(host.clone()), vec![]),
};
Self { state, host, addresses, guests }
}
pub fn message(&self) -> String {
match self.state {
State::Sharing => {
let mut out = String::from("Shared on your network. On another computer, run");
out += if self.addresses.len() > 1 { " the line for its network:" } else { ":" };
if self.addresses.is_empty() {
out += "\n kanzo join <this computer's IP address>";
}
for address in &self.addresses {
let _ = write!(out, "\n kanzo join {address}");
}
if !self.guests.is_empty() {
let guests: Vec<String> = self
.guests
.iter()
.map(|g| g.name.as_ref().map_or(g.address.to_string(), |n| format!("{n} ({})", g.address)))
.collect();
let _ = write!(out, "\nUsing it now: {}", guests.join(", "));
}
out
}
State::Joined => format!(
"Using the board at {}. Your agents use it too, from their next call.",
self.host.as_deref().unwrap_or_default()
),
State::Private => "Not shared: the board is on this computer only.".into(),
}
}
}
/// One per network, like the home network and a VPN: which one works depends on where the other computer is.
fn addresses(port: u16) -> Vec<String> {
let interfaces = if_addrs::get_if_addrs().unwrap_or_default();
interfaces
.iter()
.filter(|i| i.is_oper_up() && !i.is_loopback() && i.ip().is_ipv4())
.map(|i| if port == DEFAULT_PORT { i.ip().to_string() } else { format!("{}:{port}", i.ip()) })
.collect()
}
pub async fn request(home: &Home, change: Option<Change>) -> Result<(Status, bool)> {
let port = home.config.port;
let (method, body) = match &change {
Some(c) => ("POST", serde_json::to_vec(c)?),
None => ("GET", Vec::new()),
};
let json = [("content-type", "application/json")];
match send(&format!("127.0.0.1:{port}"), method, "/api/network", &json, &body).await {
Ok(mut reply) => {
let mut text = String::new();
reply.body.read_to_string(&mut text).await?;
if reply.status == 200 {
return Ok((serde_json::from_str(&text).context("unexpected answer from the board")?, true));
}
match serde_json::from_str::<Value>(&text).ok().and_then(|v| Some(v["error"].as_str()?.to_string())) {
Some(error) => bail!(error),
None => bail!("the board on port {port} answered {}: restart it so it runs this version", reply.status),
}
}
Err(e) if e.kind() == io::ErrorKind::ConnectionRefused => {
let net = match change {
Some(c) => self::change(home, c).await.map_err(anyhow::Error::msg)?,
None => Net::load(home),
};
Ok((Status::new(&net, port, Vec::new()), false))
}
Err(e) => Err(e).with_context(|| format!("cannot reach the board on port {port}")),
}
}
/// Requests are HTTP/1.0, so the body is all that comes until the host closes the connection, with no chunks to decode.
struct Reply {
status: u16,
headers: Vec<(String, String)>,
body: BufReader<TcpStream>,
}
impl Reply {
fn header(&self, name: &str) -> Option<&str> {
self.headers.iter().find(|(n, _)| n == name).map(|(_, v)| v.as_str())
}
}
async fn send(host: &str, method: &str, path: &str, headers: &[(&str, &str)], body: &[u8]) -> io::Result<Reply> {
let connect = tokio::time::timeout(Duration::from_secs(3), TcpStream::connect(host));
let mut conn = connect.await.map_err(|_| io::Error::from(io::ErrorKind::TimedOut))??;
let mut head = format!("{method} {path} HTTP/1.0\r\nHost: {host}\r\nContent-Length: {}\r\n", body.len());
for (name, value) in headers {
let _ = write!(head, "{name}: {value}\r\n");
}
head.push_str("\r\n");
// One write: a separate one for the body can wait on a delayed ACK.
let mut request = head.into_bytes();
request.extend_from_slice(body);
conn.write_all(&request).await?;
let mut reader = BufReader::new(conn);
let mut line = String::new();
reader.read_line(&mut line).await?;
let status = line.split_whitespace().nth(1).and_then(|s| s.parse().ok());
let status = status.ok_or_else(|| io::Error::new(io::ErrorKind::InvalidData, "not an HTTP reply"))?;
let mut headers = Vec::new();
loop {
line.clear();
reader.read_line(&mut line).await?;
let Some((name, value)) = line.trim_end().split_once(':') else { break };
headers.push((name.trim().to_ascii_lowercase(), value.trim().to_string()));
}
Ok(Reply { status, headers, body: reader })
}
pub async fn is_kanzo(host: &str) -> bool {
let probe = async {
let mut reply = send(host, "GET", "/api/ping", &[], b"").await.ok()?;
let mut body = String::new();
reply.body.read_to_string(&mut body).await.ok()?;
Some(reply.status == 200 && body == "kanzo")
};
tokio::time::timeout(Duration::from_secs(2), probe).await.ok().flatten().unwrap_or(false)
}
fn computer() -> &'static str {
static NAME: OnceLock<String> = OnceLock::new();
NAME.get_or_init(crate::home::hostname)
}
fn unreachable(host: &str) -> String {
format!("The shared board at {host} isn't reachable; run kanzo leave to use this computer's board.")
}
pub async fn forward(host: &str, req: Request) -> Response {
let (parts, body) = req.into_parts();
let Ok(body) = axum::body::to_bytes(body, BODY_LIMIT).await else {
return StatusCode::PAYLOAD_TOO_LARGE.into_response();
};
// The host checks its own Host; the page's Origin is this board's, checked already.
let skip = ["host", "origin", "referer", "connection", "content-length", "transfer-encoding", "keep-alive"];
let mut headers: Vec<(&str, &str)> = parts
.headers
.iter()
.filter(|(name, _)| !skip.contains(&name.as_str()))
.filter_map(|(name, value)| Some((name.as_str(), value.to_str().ok()?)))
.collect();
headers.push((COMPUTER_HEADER, computer()));
let path = parts.uri.path_and_query().map_or("/", |p| p.as_str());
let Ok(reply) = send(host, parts.method.as_str(), path, &headers, &body).await else {
return crate::web::fail(StatusCode::BAD_GATEWAY, unreachable(host)).into_response();
};
let mut res = Response::new(Body::from_stream(ReaderStream::new(reply.body)));
*res.status_mut() = StatusCode::from_u16(reply.status).unwrap_or(StatusCode::BAD_GATEWAY);
for (name, value) in &reply.headers {
if let (Ok(name), Ok(value)) = (HeaderName::from_bytes(name.as_bytes()), HeaderValue::from_str(value))
&& name != "connection"
{
res.headers_mut().append(name, value);
}
}
res
}
/// The `initialize` the host opens a session with. Clients on protocol 2026-07-28 never send
/// one: they name themselves in every request's `_meta` instead.
pub fn handshake(initialized: Option<&ClientConfig>, meta: &RequestMetaObject) -> ClientConfig {
initialized.cloned().unwrap_or_else(|| {
let info = meta.client_info().unwrap_or_else(|| Implementation::new("agent", ""));
ClientConfig::new(meta.client_capabilities().unwrap_or_default(), info)
.with_protocol_version(ProtocolVersion::LATEST_WITH_INITIALIZE)
})
}
pub struct Upstream {
host: String,
session: Option<String>,
folder: String,
repos: String,
images: PathBuf,
}
impl Upstream {
pub fn new(host: String, folder: &Path, repos: &[String], images: &Path) -> Self {
let folder = folder.display().to_string();
Self { host, session: None, folder, repos: repos.join(","), images: images.to_path_buf() }
}
pub fn host(&self) -> &str {
&self.host
}
pub async fn call(
&mut self,
client: ClientConfig,
name: &str,
args: Option<Map<String, Value>>,
) -> Result<String, String> {
let init = json!({ "jsonrpc": "2.0", "id": 0, "method": "initialize", "params": client }).to_string();
let initialized = r#"{"jsonrpc":"2.0","method":"notifications/initialized"}"#;
let call =
json!({ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": name, "arguments": args } });
let call = call.to_string();
// A host that restarted forgot the session: open a new one, once.
let mut reply = Err(io::ErrorKind::NotConnected.into());
for _ in 0..2 {
if self.session.is_none() {
self.post(&init).await.map_err(|_| unreachable(&self.host))?;
let _ = self.post(initialized).await;
}
reply = self.post(&call).await;
match reply {
Ok((404, _)) => self.session = None,
_ => break,
}
}
let (status, messages) = reply.map_err(|_| unreachable(&self.host))?;
let Some(answer) = messages.into_iter().find(|m| m["id"] == 1) else {
return Err(format!("The shared board answered {status}."));
};
if let Some(error) = answer["error"]["message"].as_str() {
return Err(error.to_string());
}
let result = &answer["result"];
let text =
result["content"].as_array().into_iter().flatten().filter_map(|c| c["text"].as_str()).collect::<Vec<_>>();
let text = text.join("\n");
self.fetch_images(&text).await;
if result["isError"] == true { Err(text) } else { Ok(text) }
}
/// Names are their content's hash, so a copy never goes stale.
async fn fetch_images(&self, text: &str) {
let folder = self.images.display().to_string();
for (at, _) in text.match_indices(&folder) {
let rest = text[at + folder.len()..].trim_start_matches(['/', '\\']);
let file: String = rest.chars().take_while(|c| c.is_ascii_alphanumeric() || *c == '.').collect();
let path = self.images.join(&file);
if !crate::store::valid_image_file(&file) || path.exists() {
continue;
}
let Ok(mut reply) = send(&self.host, "GET", &format!("/images/{file}"), &[], b"").await else { continue };
let mut bytes = Vec::new();
if reply.status == 200 && reply.body.read_to_end(&mut bytes).await.is_ok() {
let _ = crate::home::write_whole(&path, &bytes);
}
}
}
async fn post(&mut self, line: &str) -> io::Result<(u16, Vec<Value>)> {
let images = self.images.display().to_string();
let mut headers = vec![
("content-type", "application/json"),
("accept", "application/json, text/event-stream"),
(FOLDER_HEADER, self.folder.as_str()),
(REPOS_HEADER, self.repos.as_str()),
(IMAGES_HEADER, images.as_str()),
(COMPUTER_HEADER, computer()),
];
if let Some(id) = &self.session {
headers.push(("mcp-session-id", id));
}
let mut reply = send(&self.host, "POST", "/mcp", &headers, line.as_bytes()).await?;
if let Some(id) = reply.header("mcp-session-id") {
self.session = Some(id.to_string());
}
let mut body = String::new();
reply.body.read_to_string(&mut body).await?;
let messages = if body.trim_start().starts_with('{') {
serde_json::from_str(&body).into_iter().collect()
} else {
body.lines().filter_map(|l| serde_json::from_str(l.strip_prefix("data:")?.trim()).ok()).collect()
};
Ok((reply.status, messages))
}
}
#[cfg(test)]
mod tests {
use rmcp::model::ClientCapabilities;
use super::*;
#[test]
fn addresses() {
assert_eq!(address("192.168.0.12").unwrap(), "192.168.0.12:4242");
assert_eq!(address(" http://192.168.0.12:4300/ ").unwrap(), "192.168.0.12:4300");
assert_eq!(address("mac-mini.local").unwrap(), "mac-mini.local:4242");
assert_eq!(address("fe80::1").unwrap(), "[fe80::1]:4242");
for bad in ["", "127.0.0.1", "localhost", "localhost:4300", "0.0.0.0", "a b", "evil.com/x", "u@host"] {
assert!(address(bad).is_err(), "{bad}");
}
}
#[test]
fn changes_follow_the_rules() {
let rt = tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap();
let tmp = tempfile::tempdir().unwrap();
let home = Home::open(tmp.path().to_path_buf()).unwrap();
let apply = |c| rt.block_on(change(&home, c));
assert_eq!(apply(Change::On).unwrap(), Net::Sharing);
assert_eq!(Net::load(&home), Net::Sharing);
assert!(apply(Change::Join("192.168.0.12".into())).unwrap_err().contains("share off"));
assert_eq!(apply(Change::Leave).unwrap(), Net::Sharing);
assert_eq!(apply(Change::Off).unwrap(), Net::Private);
assert!(!tmp.path().join(FILE).exists());
std::fs::write(tmp.path().join(FILE), "join 192.168.0.12:4242\n").unwrap();
assert!(apply(Change::On).unwrap_err().contains("kanzo leave"));
assert_eq!(apply(Change::Off).unwrap(), Net::Joined("192.168.0.12:4242".into()));
assert_eq!(apply(Change::Leave).unwrap(), Net::Private);
std::fs::write(tmp.path().join("config.toml"), "listen = \"0.0.0.0\"\n").unwrap();
let home = Home::open(tmp.path().to_path_buf()).unwrap();
assert_eq!(Net::load(&home), Net::Sharing);
assert!(rt.block_on(change(&home, Change::Join("192.168.0.12".into()))).unwrap_err().contains("share off"));
assert!(rt.block_on(change(&home, Change::Off)).unwrap_err().contains("config.toml"));
}
#[test]
fn handshake_names_a_client_that_never_initialized() {
let roots: ClientCapabilities = serde_json::from_value(json!({ "roots": { "listChanged": true } })).unwrap();
let mut meta = RequestMetaObject::new();
meta.set_protocol_version(ProtocolVersion::V_2026_07_28);
meta.set_client_capabilities(roots.clone());
let init = handshake(None, &meta);
assert_eq!(init.protocol_version, ProtocolVersion::V_2025_11_25);
assert_eq!(init.capabilities, roots);
assert_eq!(init.client_info.name, "agent");
meta.set_client_info(Implementation::new("claude-code", "2.1.309"));
assert_eq!(handshake(None, &meta).client_info.name, "claude-code");
}
#[test]
fn handshake_repeats_what_a_client_initialized_with() {
let client = ClientConfig::new(ClientCapabilities::default(), Implementation::new("codex-mcp-client", "1.0"))
.with_protocol_version(ProtocolVersion::V_2025_06_18);
let mut meta = RequestMetaObject::new();
meta.set_client_info(Implementation::new("from-meta", "1"));
assert_eq!(handshake(Some(&client), &meta), client);
}
#[test]
fn change_json() {
assert_eq!(serde_json::to_string(&Change::On).unwrap(), r#"{"action":"on"}"#);
let join: Change = serde_json::from_str(r#"{"action":"join","host":"pi.local"}"#).unwrap();
assert!(matches!(join, Change::Join(h) if h == "pi.local"));
}
}