ππΌββοΈ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.
Rust adeai-agentsclaudeclaude-codecodexcursorgeminigrokopencodespec-driven-developmentvibe-codingvim
//! `agtx serve` β the board over HTTP.
//!
//! The server never links `App`. It reads SQLite, git and tmux, exactly as the
//! MCP server does, so it can run beside a TUI or without one. What it cannot
//! do is *execute* a transition: that machinery lives on `App` (see the mobile
//! plan's "one hard constraint"), which is why the heartbeat exists β a client
//! must be able to tell a queued tap from a completed one.
pub mod assets;
pub mod auth;
pub mod qr;
pub mod routes;
pub mod state;
pub mod tunnel;
pub mod writes;
pub mod ws;
use std::net::{IpAddr, SocketAddr};
use std::path::PathBuf;
use anyhow::{bail, Context, Result};
pub use state::{ServeMode, ServerState};
/// How `agtx serve` was invoked.
pub struct ServeOptions {
pub project_path: Option<PathBuf>,
pub host: IpAddr,
pub port: u16,
/// How far to expose the board, if at all.
pub tunnel: Option<tunnel::TunnelScope>,
/// A pairing code supplied by the caller rather than minted here.
///
/// Set when the TUI launches the server: it needs the URL β and the QR β
/// before the child exists.
pub pair_code: Option<String>,
/// Identifies this serve session in `mobile_devices`.
///
/// Stamped on every device paired here, so a device can be traced back to
/// the server that issued it. Minted on startup when the caller supplies
/// none. Pairings themselves persist until revoked.
///
/// Deliberately **not** the pairing code: that is a credential, and a
/// credential does not belong in a column that outlives its use.
pub session_id: Option<String>,
}
impl Default for ServeOptions {
fn default() -> Self {
Self {
project_path: None,
// Loopback, always, until a caller says otherwise. Anyone who
// reaches this server can read every task, diff and agent pane on
// the machine.
host: IpAddr::from([127, 0, 0, 1]),
port: 8787,
tunnel: None,
pair_code: None,
session_id: None,
}
}
}
impl ServeOptions {
/// Whether anything beyond this machine can reach the board.
///
/// A tunnel counts even though the listener stays on loopback: the provider
/// proxies into it, so the exposure is real and pairing must be required.
/// Reading only the bind address here is how a tunnelled server ends up
/// unauthenticated.
pub fn is_loopback(&self) -> bool {
self.host.is_loopback() && self.tunnel.is_none()
}
}
pub async fn serve(opts: ServeOptions) -> Result<()> {
// Off-loopback needs a credential, full stop. This exposes task
// descriptions, whole diffs, live agent panes, and an endpoint that types
// into a running agent β on a shared network that is arbitrary code
// execution for anyone who finds the port. The token is what makes `--host`
// answerable; without one the honest reply is still no.
// Loopback is its own boundary: reaching it already means being on this
// machine, where the tmux socket and the databases are readable anyway. So
// no pairing there β it would mean scanning a code to open a board on the
// machine already running it, for no gain. Off-loopback, pairing is what
// makes the bind answerable at all.
let require_auth = !opts.is_loopback();
// Recorded on every device this server pairs. Provenance rather than a
// lifetime: pairings persist until revoked. It is what a forget-on-exit or
// expiry policy would delete by, and scoping such a delete is not optional
// β `mobile_devices` is global, so a second agtx serving another project
// must keep its own devices.
let session_id = opts
.session_id
.clone()
.unwrap_or_else(|| uuid::Uuid::new_v4().to_string());
// An already-paired phone must survive the move from the single shared
// token to per-device ones. Without this it would simply stop connecting,
// with nothing on screen to say why.
if require_auth {
match auth::migrate_legacy_token(Some(&session_id)) {
Ok(Some(_)) => println!(" adopted the previous access token as a paired device"),
Ok(None) => {}
Err(e) => tracing::warn!(error = %e, "could not migrate the legacy access token"),
}
}
let mode = match &opts.project_path {
Some(path) => {
let path = path
.canonicalize()
.with_context(|| format!("resolving {}", path.display()))?;
if !crate::git::is_git_repo(&path) {
bail!("serve requires a git project directory: {}", path.display());
}
ServeMode::Project(path)
}
None => ServeMode::Global,
};
// Start the tunnel before the listener so a provider that is missing or
// refuses fails here, rather than after printing a QR for a URL that will
// never resolve.
let mut public_base: Option<String> = None;
let _tunnel = match opts.tunnel {
Some(scope) => {
let port = opts.port;
// Provider discovery and startup run subprocesses; cloudflared may
// also take up to 30 seconds to report its public hostname.
let started = tokio::task::spawn_blocking(move || {
let plan = tunnel::plan(scope, port, &tunnel::installed)?;
let started = tunnel::Tunnel::start(&plan)?;
println!("tunnel: {} β reachable from {}", plan.program, plan.reach);
Ok::<_, anyhow::Error>(started)
})
.await
.context("joining tunnel startup")??;
public_base = started.public_url.clone();
Some(started)
}
None => None,
};
let state = ServerState::with_session(mode, require_auth, Some(session_id.clone()));
// A code exists only while someone is looking at the terminal it was
// printed in, so it is minted here rather than on demand.
let pairing_code = if require_auth {
Some(match &opts.pair_code {
Some(supplied) => {
state.pairing.seed(supplied);
supplied.clone()
}
None => state.pairing.issue(),
})
} else {
None
};
let app = routes::router(state.clone());
let addr = SocketAddr::new(opts.host, opts.port);
let listener = tokio::net::TcpListener::bind(addr)
.await
.with_context(|| format!("binding {addr}"))?;
// The bound address rather than the requested one: port 0 is how a test or
// a second instance asks the OS to pick, and the answer is only known here.
let bound = listener.local_addr().unwrap_or(addr);
print_banner(
&bound,
public_base.as_deref(),
pairing_code.as_deref(),
opts.is_loopback(),
);
tracing::info!(addr = %bound, loopback = opts.is_loopback(), "web server started");
// Graceful shutdown is not a nicety here β it is what makes the tunnel
// teardown run at all. `tailscale serve` configures the *daemon*, so the
// exposure outlives this process, and `Tunnel`'s `Drop` is the only thing
// that removes it. Rust does not run destructors on a signal, so without
// this a Ctrl-C or a `kill` leaves the board published on the tailnet with
// nothing serving it.
axum::serve(listener, app)
.with_graceful_shutdown(shutdown_signal())
.await
.context("web server stopped")?;
Ok(())
}
/// Resolve on Ctrl-C or `SIGTERM`.
///
/// Both, because they arrive from different places and mean the same thing: a
/// person pressing Ctrl-C in the terminal, and the TUI stopping the child it
/// spawned for the `W` overlay.
async fn shutdown_signal() {
let ctrl_c = async {
let _ = tokio::signal::ctrl_c().await;
};
#[cfg(unix)]
let terminate = async {
match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) {
Ok(mut sig) => {
sig.recv().await;
}
// Nothing to do but wait for Ctrl-C instead; a server that refuses
// to start because it could not install a handler is worse.
Err(e) => {
tracing::warn!(error = %e, "could not listen for SIGTERM");
std::future::pending::<()>().await;
}
}
};
#[cfg(not(unix))]
let terminate = std::future::pending::<()>();
tokio::select! {
_ = ctrl_c => {}
_ = terminate => {}
}
println!("shutting down");
}
/// What to print so the URL can be typed into a phone.
///
/// The token goes in the **fragment**, which browsers do not transmit: the page
/// reads it, stores it, and strips it from the address bar. Putting it in the
/// path or the query would write the credential into every access log between
/// here and the browser.
fn print_banner(
bound: &SocketAddr,
public_base: Option<&str>,
pairing_code: Option<&str>,
loopback: bool,
) {
let host = if bound.ip().is_unspecified() {
// `0.0.0.0` is not an address anything can open. Name a real one, or
// the user is left to work out their own LAN address.
local_ipv4().unwrap_or_else(|| bound.ip().to_string())
} else {
bound.ip().to_string()
};
// A tunnel's hostname, when there is one. Without this the banner prints
// the *bound* address β which for a tunnel is loopback, so the QR would
// carry `http://127.0.0.1:β¦` and be useless to the phone it was drawn for.
let base = match public_base {
Some(b) => b.to_string(),
None => format!("http://{host}:{}", bound.port()),
};
let url = match pairing_code {
Some(code) => format!("{base}/#pair={code}"),
None => format!("{base}/"),
};
println!("agtx serve listening on {base}");
// The QR is for a *phone*, so it is printed only when one could reach this
// server. On loopback the URL resolves to the machine already running it,
// and a code for `127.0.0.1` scans perfectly and goes nowhere.
if !loopback {
match qr::render(&url) {
Some(code) => {
println!();
print!("{code}");
println!();
}
None => tracing::warn!("could not encode the pairing URL as a QR code"),
}
}
println!(" scan to pair: {url}");
if pairing_code.is_some() {
println!(
" the code is single-use and lasts {}s; already-paired devices need nothing",
auth::PAIRING_TTL.as_secs()
);
println!(" reachable by anything on this network β that includes typing into your agents");
}
}
/// This machine's first non-loopback IPv4, for the banner.
///
/// Read from the OS rather than guessed: `hostname -I` is Linux-only and
/// `ifconfig` output differs per platform, while a UDP socket "connected" to an
/// off-machine address makes the kernel pick the outbound interface without
/// sending anything.
fn local_ipv4() -> Option<String> {
let sock = std::net::UdpSocket::bind("0.0.0.0:0").ok()?;
sock.connect("192.0.2.1:80").ok()?; // TEST-NET-1: routed nowhere
Some(sock.local_addr().ok()?.ip().to_string())
}