ππΌββοΈ The blackboard for coding agents - agentic development environment for claude code, codex, cursor, opencode, grok and more.
Rust adeai-agentsclaudeclaude-codecodexcursorgeminigrokopencodespec-driven-developmentvibe-codingvim
//! Reaching the board from outside the local network.
//!
//! Both providers work the same way and it is why this is safe to do at all:
//! the child makes an **outbound** connection to the provider's edge and the
//! phone reaches the edge. agtx keeps listening on loopback; nothing here binds
//! a wider address, opens a port, or needs a firewall rule.
//!
//! **The two modes are not variations on one thing.** `tailscale serve` is
//! tailnet-only β reachable from anywhere, by your own signed-in devices.
//! `tailscale funnel` and `cloudflared` are the public internet. Tailscale's
//! own naming invites collapsing them, and "Tailscale, so it is private" is
//! exactly the mistake this module refuses to let a caller make: `public` has
//! to be typed in full.
//!
//! **The spawn path here is unverified.** Neither binary is installed on the
//! machine this was written on, so [`TunnelPlan`] β which provider, which
//! command, which teardown β is pure and fully tested, while starting the child
//! is not. That split is deliberate: the part that can be wrong in a quiet way
//! is the part under test.
use std::process::{Child, Command, Stdio};
use anyhow::{bail, Context, Result};
/// How far the tunnel reaches.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TunnelScope {
/// Your tailnet only. Reachable from anywhere, by your devices alone.
Private,
/// The open internet, to anyone with the URL.
Public,
}
impl TunnelScope {
pub fn parse(value: &str) -> Option<Self> {
match value {
"private" | "tailnet" => Some(TunnelScope::Private),
"public" => Some(TunnelScope::Public),
_ => None,
}
}
}
/// Which tool will be run, and how.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TunnelPlan {
pub program: String,
pub args: Vec<String>,
/// Run on shutdown to undo the exposure.
///
/// `tailscale serve` configures the *daemon* and outlives the process that
/// asked for it, so killing the child would leave the board exposed with
/// nothing on screen to say so. `cloudflared` holds the tunnel itself and
/// needs no teardown beyond dying.
pub teardown: Option<Vec<String>>,
pub scope: TunnelScope,
/// What to tell the user about where this is reachable from.
pub reach: &'static str,
/// Whether the command configures a daemon and exits, rather than *being*
/// the tunnel.
///
/// This decides how success is judged, and getting it wrong is silent:
/// `tailscale serve --bg` returns immediately, so a spawned handle proves
/// nothing β the exit status is the only signal, and a failure there means
/// no tunnel at all. `cloudflared` is the opposite: it runs for as long as
/// the tunnel lives, so waiting on it would block forever.
pub backgrounds: bool,
/// The URL the board is reached at, once this is running. `None` when only
/// the provider knows it β `cloudflared` invents a hostname and prints it.
pub public_url: Option<String>,
}
/// Choose a provider for `scope`, given which binaries exist.
///
/// `available` is passed in rather than probed so the choice is testable
/// without installing anything.
pub fn plan(scope: TunnelScope, port: u16, available: &dyn Fn(&str) -> bool) -> Result<TunnelPlan> {
let target = format!("http://127.0.0.1:{port}");
match scope {
TunnelScope::Private => {
if !available("tailscale") {
bail!(
"--tunnel private needs Tailscale, which is not installed. It is the only way \
to be reachable from anywhere *without* being reachable by everyone: install \
it from https://tailscale.com/download and sign this machine and your phone \
into the same tailnet."
);
}
Ok(TunnelPlan {
program: "tailscale".to_string(),
// `serve`, never `funnel`. The difference is the whole point of
// this arm.
args: vec![
"serve".to_string(),
"--bg".to_string(),
// Without this it prompts, and the child is spawned with
// null stdin β so it would block on a question nobody can
// see, or fail with nothing on screen explaining why.
"--yes".to_string(),
"--https=443".to_string(),
target,
],
teardown: Some(vec![
"tailscale".to_string(),
"serve".to_string(),
"--https=443".to_string(),
"off".to_string(),
]),
scope,
reach: "your tailnet β anywhere, but only devices signed into it",
backgrounds: true,
// Served on 443, so no port β and https, because that is what
// `--https=443` publishes.
public_url: tailnet_hostname().map(|h| format!("https://{h}")),
})
}
TunnelScope::Public => {
if available("cloudflared") {
return Ok(TunnelPlan {
program: "cloudflared".to_string(),
args: vec![
"tunnel".to_string(),
"--url".to_string(),
target,
"--no-autoupdate".to_string(),
],
// The child *is* the tunnel; when it dies the exposure ends.
teardown: None,
scope,
reach: "the open internet β anyone with the URL",
// The child *is* the tunnel and prints its own hostname.
backgrounds: false,
public_url: None,
});
}
if available("tailscale") {
return Ok(TunnelPlan {
program: "tailscale".to_string(),
args: vec![
"funnel".to_string(),
"--bg".to_string(),
"--yes".to_string(),
"--https=443".to_string(),
target,
],
teardown: Some(vec![
"tailscale".to_string(),
"funnel".to_string(),
"--https=443".to_string(),
"off".to_string(),
]),
scope,
reach: "the open internet β anyone with the URL",
backgrounds: true,
public_url: tailnet_hostname().map(|h| format!("https://{h}")),
});
}
bail!(
"--tunnel public needs cloudflared or Tailscale, and neither is installed. \
Consider `--tunnel private` instead: it reaches just as far without publishing \
an endpoint that can type into your agents."
)
}
}
}
/// A running tunnel, torn down on drop.
pub struct Tunnel {
child: Option<Child>,
teardown: Option<Vec<String>>,
pub public_url: Option<String>,
}
impl Tunnel {
pub fn start(plan: &TunnelPlan) -> Result<Self> {
if plan.backgrounds {
// Run to completion and judge it by the exit status. Spawning and
// holding the handle looks like it works and proves nothing: the
// process is *expected* to exit, so a failed tunnel and a healthy
// one are indistinguishable that way β which is how a board ends up
// served at a URL that resolves nowhere.
let out = Command::new(&plan.program)
.args(&plan.args)
.stdin(Stdio::null())
.output()
.with_context(|| format!("running {}", plan.program))?;
if !out.status.success() {
// Relay the provider's own words. It knows things agtx does not
// β that Serve is disabled for this tailnet, and the one-time
// URL that enables it.
let detail = String::from_utf8_lossy(&out.stderr);
let detail = detail.trim();
let detail = if detail.is_empty() {
String::from_utf8_lossy(&out.stdout).trim().to_string()
} else {
detail.to_string()
};
bail!("{} could not start the tunnel:\n{detail}", plan.program);
}
return Ok(Self {
child: None,
teardown: plan.teardown.clone(),
public_url: plan.public_url.clone(),
});
}
let mut child = Command::new(&plan.program)
.args(&plan.args)
.stdin(Stdio::null())
.stdout(Stdio::inherit())
.stderr(Stdio::piped())
.spawn()
.with_context(|| format!("starting {}", plan.program))?;
let stderr = child.stderr.take().context("capturing tunnel output")?;
let (tx, rx) = std::sync::mpsc::channel();
std::thread::spawn(move || {
use std::io::BufRead;
for line in std::io::BufReader::new(stderr).lines() {
let Ok(line) = line else { break };
if let Some(url) = quick_tunnel_url(&line) {
let _ = tx.send(url);
}
// Keep draining after discovery so provider logs cannot fill
// the pipe and stall the tunnel.
eprintln!("{line}");
}
});
// Own the child before waiting: errors and timeout must kill it too.
let mut tunnel = Self {
child: Some(child),
teardown: plan.teardown.clone(),
public_url: None,
};
let url = rx
.recv_timeout(std::time::Duration::from_secs(30))
.context("cloudflared did not report a public URL within 30 seconds")?;
tunnel.public_url = Some(url);
Ok(tunnel)
}
}
impl Drop for Tunnel {
fn drop(&mut self) {
if let Some(mut child) = self.child.take() {
let _ = child.kill();
let _ = child.wait();
}
// Teardown after the kill, because for `tailscale serve` the exposure
// lives in the daemon and would otherwise survive this process.
if let Some(cmd) = self.teardown.take() {
if let Some((program, args)) = cmd.split_first() {
let _ = Command::new(program)
.args(args)
.stdin(Stdio::null())
.stdout(Stdio::null())
.stderr(Stdio::null())
.status();
}
}
}
}
/// Whether a binary is on `PATH`.
pub fn installed(program: &str) -> bool {
Command::new("which")
.arg(program)
.stdout(Stdio::null())
.stderr(Stdio::null())
.status()
.map(|s| s.success())
.unwrap_or(false)
}
// ββ tailnet identity ββββββββββββββββββββββββββββββββββββββββββββββββββββ
/// This machine's tailnet DNS name, for building a URL before the tunnel runs.
///
/// `tailscale serve` proxies `https://<this>/` into a loopback listener, so the
/// hostname is not something agtx chooses β it has to be asked for, or the QR
/// would carry an address that does not exist.
pub fn tailnet_hostname() -> Option<String> {
let out = Command::new("tailscale")
.args(["status", "--json"])
.stdin(Stdio::null())
.stderr(Stdio::null())
.output()
.ok()?;
if !out.status.success() {
return None;
}
parse_tailnet_hostname(&String::from_utf8_lossy(&out.stdout))
}
/// Pull `Self.DNSName` out of `tailscale status --json`.
///
/// Split from the command so the parsing is testable without Tailscale
/// installed β which matters here, because it is not installed on the machine
/// this was written on.
pub fn parse_tailnet_hostname(json: &str) -> Option<String> {
let value: serde_json::Value = serde_json::from_str(json).ok()?;
let name = value.get("Self")?.get("DNSName")?.as_str()?;
// Tailscale reports a fully-qualified name with the root dot. Leaving it on
// produces a URL that most clients accept and some reject, which is the
// worst of both.
let trimmed = name.trim_end_matches('.');
if trimmed.is_empty() {
return None;
}
Some(trimmed.to_string())
}
/// Read only the assigned quick-tunnel hostname, not documentation links.
fn quick_tunnel_url(line: &str) -> Option<String> {
line.split_whitespace().find_map(|word| {
let host = word.strip_prefix("https://")?;
let label = host.strip_suffix(".trycloudflare.com")?;
(!label.is_empty()
&& label
.bytes()
.all(|b| b.is_ascii_alphanumeric() || b == b'-'))
.then(|| word.to_string())
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn discovers_only_quick_tunnel_urls() {
assert_eq!(
quick_tunnel_url("INF | https://some-host.trycloudflare.com |"),
Some("https://some-host.trycloudflare.com".into())
);
assert_eq!(
quick_tunnel_url("Visit https://developers.cloudflare.com"),
None
);
assert_eq!(
quick_tunnel_url("https://fake.trycloudflare.com.evil.test"),
None
);
}
#[test]
#[cfg(unix)]
fn running_tunnel_exposes_the_discovered_url() {
let plan = TunnelPlan {
program: "sh".into(),
args: vec![
"-c".into(),
"echo 'INF | https://test-board.trycloudflare.com |' >&2; exec sleep 30".into(),
],
teardown: None,
scope: TunnelScope::Public,
reach: "test",
backgrounds: false,
public_url: None,
};
let tunnel = Tunnel::start(&plan).unwrap();
assert_eq!(
tunnel.public_url.as_deref(),
Some("https://test-board.trycloudflare.com")
);
// Drop terminates the fake provider rather than waiting for sleep.
}
}