git.delta.rocks / remowt / refs/commits / 42e2f16609cb

difftreelog

feat basic plugin loading

mwqtzvovYaroslav Bolyukin2026-06-07parent: #69f690d.patch.diff
in: trunk

11 files changed

modifiedCargo.lockdiffbeforeafterboth
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1080,22 +1080,6 @@
 ]
 
 [[package]]
-name = "fleet-nix-daemon"
-version = "0.1.0"
-dependencies = [
- "anyhow",
- "bifrostlink",
- "bifrostlink-macros",
- "camino",
- "remowt-client",
- "serde",
- "thiserror 2.0.18",
- "tokio",
- "tracing",
- "uuid",
-]
-
-[[package]]
 name = "foldhash"
 version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
@@ -2270,6 +2254,7 @@
  "polkit-shared",
  "rand 0.8.5",
  "remowt-link-shared",
+ "remowt-plugin",
  "remowt-pty",
  "serde",
  "tempfile",
@@ -2333,6 +2318,36 @@
 ]
 
 [[package]]
+name = "remowt-nix-daemon"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "bifrostlink",
+ "bifrostlink-macros",
+ "camino",
+ "remowt-client",
+ "serde",
+ "thiserror 2.0.18",
+ "tokio",
+ "tracing",
+ "uuid",
+]
+
+[[package]]
+name = "remowt-plugin"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "bifrostlink",
+ "bifrostlink-ports",
+ "bytes",
+ "remowt-link-shared",
+ "tokio",
+ "tracing",
+ "tracing-subscriber",
+]
+
+[[package]]
 name = "remowt-pty"
 version = "0.1.0"
 dependencies = [
modifiedCargo.tomldiffbeforeafterboth
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -10,6 +10,7 @@
 remowt-client = { path = "crates/remowt-client" }
 polkit-shared = { version = "0.1.0", path = "crates/polkit-shared" }
 remowt-link-shared = { version = "0.1.0", path = "crates/remowt-link-shared" }
+remowt-plugin = { version = "0.1.0", path = "crates/remowt-plugin" }
 ui-prompt = { version = "0.1.0", path = "crates/ui-prompt" }
 
 bifrostlink = "0.2.0"
modifiedcmds/remowt-agent/Cargo.tomldiffbeforeafterboth
--- a/cmds/remowt-agent/Cargo.toml
+++ b/cmds/remowt-agent/Cargo.toml
@@ -14,6 +14,7 @@
 polkit-shared.workspace = true
 rand.workspace = true
 remowt-link-shared.workspace = true
+remowt-plugin.workspace = true
 remowt-pty.workspace = true
 serde = { workspace = true, features = ["derive"] }
 tempfile.workspace = true
modifiedcmds/remowt-agent/src/main.rsdiffbeforeafterboth
before · cmds/remowt-agent/src/main.rs
1use std::borrow::Cow;2use std::collections::{BTreeMap, HashMap};3use std::fs::Permissions;4use std::future::pending;5use std::os::unix::fs::PermissionsExt as _;6use std::path::PathBuf;7use std::sync::{Arc, Mutex, OnceLock};89use bifrostlink::declarative::RemoteEndpoints;10use bifrostlink::Rpc;11use bifrostlink_ports::stdio::from_stdio;12use bifrostlink_ports::unix_socket::from_socket;13use clap::Parser;14use polkit_shared::{emphasize, BackendRequest, Identity, PidDisplay};15use remowt_link_shared::editor::EditorEndpointsClient;16use remowt_link_shared::{Address, BifConfig, Fs, Pty, Systemd};17use tokio::fs;18use tokio::net::UnixStream;19use tokio::runtime::Builder;20use tokio::task::AbortHandle;21use tracing::{info, trace};22use ui_prompt::bifrost::PromptEndpointsClient;23use ui_prompt::{PrependSourcePrompter, Prompter, Source};24use zbus::fdo;25use zbus::zvariant::{OwnedValue, Str};26use zbus::{interface, proxy, Connection};27use zbus_polkit::policykit1::Subject;2829use self::helper::{Helper, SocketHelper, SuidHelper};3031pub mod askpass;32pub mod bus;33pub mod editor;34pub mod helper;3536struct CancelTaskOnDrop {37	tasks: Arc<Mutex<HashMap<String, AbortHandle>>>,38	handle: String,39}40impl Drop for CancelTaskOnDrop {41	fn drop(&mut self) {42		info!("cancel on drop");43		if let Some(task) = self44			.tasks45			.lock()46			.expect("not poisoned")47			.remove(&self.handle)48		{49			task.abort();50		}51	}52}5354struct Agent<H, P> {55	tasks: Arc<Mutex<HashMap<String, AbortHandle>>>,56	helper: H,57	prompter: P,58}59impl<H, P> Agent<H, P> {60	fn new(helper: H, prompter: P) -> Self {61		Agent {62			tasks: Arc::new(Mutex::new(HashMap::new())),63			helper,64			prompter,65		}66	}67}6869#[interface(name = "org.freedesktop.PolicyKit1.AuthenticationAgent")]70impl<H, P> Agent<H, P>71where72	H: Helper + Clone + Send + Sync + 'static,73	P: Prompter + Clone + Send + Sync + 'static,74{75	/// BeginAuthentication method76	#[allow(clippy::too_many_arguments)]77	async fn begin_authentication(78		&self,79		action_id: String,80		message: String,81		_icon_name: String,82		mut details: BTreeMap<String, String>,83		cookie: String,84		identities: Vec<Identity>,85	) -> zbus::fdo::Result<()> {86		use std::fmt::Write;87		info!("begin auth");88		let _cancel_guard = Arc::new(OnceLock::new());89		let task = {90			let helper = self.helper.clone();91			let prompter = self.prompter.clone();92			let cookie = cookie.clone();93			let _cancel_guard = _cancel_guard.clone();94			tokio::task::spawn(async move {95				let _cancel_guard = _cancel_guard.clone();96				trace!("conversation task");97				let mut description = format!("{message}\n\n<b>Action id:</b> {action_id}",);98				if let Some(subject) = details.remove("polkit.caller-pid") {99					let _ = write!(description, "\n<b>Caller:</b> ");100					if let Ok(pid) = subject.parse::<u32>() {101						let _ = write!(description, "{}", PidDisplay(pid));102					} else {103						let _ = write!(description, "{}", emphasize("invalid pid"));104					}105				}106				if let Some(subject) = details.remove("polkit.subject-pid") {107					let _ = write!(description, "\n<b>Subject:</b> ");108					if let Ok(pid) = subject.parse::<u32>() {109						let _ = write!(description, "{}", PidDisplay(pid));110					} else {111						let _ = write!(description, "{}", emphasize("invalid pid"));112					}113				}114				let mut prompter = PrependSourcePrompter {115					source: vec![Source(Cow::Borrowed("polkit agent"))],116					description: description.clone(),117					prompter,118				};119120				let identity_displays: Vec<String> =121					identities.iter().map(|v| v.to_string()).collect();122				let identity_displays: Vec<&str> =123					identity_displays.iter().map(|v| v.as_str()).collect();124				info!("choose identity");125				let choosen_identity = match identity_displays.len() {126					0 => {127						return Err(fdo::Error::AuthFailed(128							"no identity to authenticate as".to_owned(),129						))130					}131					1 => 0,132					_ => {133						prompter134							.prompt_enum(135								"Identity",136								"Select identity to use for polkit authorization",137								&identity_displays,138								&[],139							)140							.await?141					}142				};143				info!("identity chosen");144145				let _ = write!(146					description,147					"\n<b>Identity:</b> {}",148					identities[choosen_identity as usize]149				);150				prompter.description = description;151152				prompter.source.push(Source(Cow::Borrowed("polkit daemon")));153154				helper155					.help_me(156						&cookie,157						prompter,158						identities[choosen_identity as usize].clone(),159					)160					.await161					.map_err(|e| fdo::Error::Failed(e.to_string()))?;162				// let connection = Connection::system().await?;163				// let helper = PolkitHelperProxy::new(&connection).await?;164165				Ok(())166			})167		};168		self.tasks169			.lock()170			.unwrap()171			.insert(cookie.clone(), task.abort_handle());172		info!("abort handle stored");173		let _ = _cancel_guard.set(CancelTaskOnDrop {174			tasks: self.tasks.clone(),175			handle: cookie.clone(),176		});177178		let _ = task.await;179180		Ok(())181	}182183	/// CancelAuthentication method184	async fn cancel_authentication(&self, cookie: &str) -> zbus::fdo::Result<()> {185		info!("auth cancelled");186		if let Some(abort) = self.tasks.lock().unwrap().remove(cookie) {187			info!("abort handle found");188			abort.abort();189		}190		// debug!("Authentication cancled ! {cookie}");191		Ok(())192	}193}194195const OBJ_PATH: &str = "/org/freedesktop/PolicyKit1/AuthenticationAgent";196197#[proxy(198	interface = "lach.PolkitHelper",199	default_service = "lach.polkit.helper1",200	default_path = "/lach/PolkitHelper"201)]202trait PolkitHelper {203	fn init_conversation(&self, request: BackendRequest) -> zbus::Result<()>;204}205206#[derive(Parser)]207enum Opts {208	AskPass {209		prompt: String,210		description: String,211	},212	Editor {213		/// Argument to nvim214		path: String,215	},216	RealAgent {217		#[arg(long)]218		path: Option<PathBuf>,219		/// Expect own address to be AgentPrivileged, skip installing polkit agent220		#[arg(long)]221		privileged: bool,222	},223}224225fn main() -> anyhow::Result<()> {226	// Log to stderr: `privileged-agent` uses stdout as the bifrost transport,227	// so anything written there would corrupt the stream.228	tracing_subscriber::fmt()229		.with_writer(std::io::stderr)230		.init();231	let opts = Opts::parse();232233	let runtime = Builder::new_current_thread().enable_all().build()?;234235	match opts {236		Opts::AskPass {237			prompt,238			description,239		} => runtime.block_on(askpass::ask(&prompt, description)),240		Opts::Editor { path } => runtime.block_on(editor::edit(path)),241		Opts::RealAgent { path, privileged } => runtime.block_on(main_real_agent(path, privileged)),242	}243}244async fn main_real_agent(path: Option<PathBuf>, privileged: bool) -> anyhow::Result<()> {245	let address = if privileged {246		Address::AgentPrivileged247	} else {248		Address::Agent249	};250	let mut rpc = Rpc::<BifConfig>::new(address);251252	Fs::new().register_endpoints(&mut rpc);253	Systemd.register_endpoints(&mut rpc);254	Pty::new().register_endpoints(&mut rpc);255256	let user_prompter = PromptEndpointsClient::wrap(rpc.remote(Address::User));257	let editor_client = EditorEndpointsClient::wrap(rpc.remote(Address::User));258259	let bus = bus::spawn().await?;260	askpass::serve(&bus.conn, user_prompter.clone()).await?;261	editor::serve(&bus.conn, editor_client).await?;262263	let helpers = tempfile::Builder::new().prefix("remowt-path.").tempdir()?;264	let exe = std::env::current_exe()?;265	let askpass_helper = helpers.path().join("remowt-askpass");266	let editor_helper = helpers.path().join("remowt-editor");267	{268		let script = format!(269			"#!/bin/sh\nexec {} ask-pass \"password\" \"$1\"\n",270			sh_quote(&exe.to_string_lossy())271		);272		fs::write(&askpass_helper, script).await?;273		fs::set_permissions(&askpass_helper, Permissions::from_mode(0o755)).await?;274	}275	{276		let script = format!(277			"#!/bin/sh\nexec {} editor \"$1\"\n",278			sh_quote(&exe.to_string_lossy())279		);280		fs::write(&editor_helper, script).await?;281		fs::set_permissions(&editor_helper, Permissions::from_mode(0o755)).await?;282	}283284	// Safety: Hoping tokio own threads won't read any of those...285	unsafe {286		prepend_path(helpers.path());287		std::env::set_var("SUDO_ASKPASS", &askpass_helper);288		std::env::set_var("SSH_ASKPASS", &askpass_helper);289		std::env::set_var("SSH_ASKPASS_REQUIRE", "force");290		std::env::set_var("EDITOR", &editor_helper);291		std::env::set_var("VISUAL", &editor_helper);292		std::env::set_var("DBUS_SESSION_BUS_ADDRESS", &bus.address);293	}294295	let port = match path {296		Some(path) => from_socket(UnixStream::connect(path).await?),297		None => from_stdio(),298	};299	rpc.add_direct(Address::User, port, bifrostlink::Rtt(0));300301	let polkit_conn = if !privileged {302		// The unprivileged agent doubles as a polkit authentication agent so303		// `run0` (e.g. our own elevation) routes its prompt to the User over304		// bifrost instead of failing on a tty-less session.305		let conn = Connection::system().await?;306		let helper = SocketHelper {307			fallback: SuidHelper,308		};309		register_auth_agent(&conn, Agent::new(helper, user_prompter)).await?;310		Some(conn)311	} else {312		None313	};314315	let _keep_alive = (bus, helpers, polkit_conn);316	pending().await317}318319async fn register_auth_agent<H, P>(conn: &Connection, agent: Agent<H, P>) -> anyhow::Result<()>320where321	H: Helper + Clone + Send + Sync + 'static,322	P: Prompter + Clone + Send + Sync + 'static,323{324	let proxy = zbus_polkit::policykit1::AuthorityProxy::new(conn).await?;325	conn.object_server().at(OBJ_PATH, agent).await?;326327	let subject = auth_agent_subject()?;328	proxy329		.register_authentication_agent(&subject, "C", OBJ_PATH)330		.await?;331	info!(kind = subject.subject_kind, "registered polkit agent");332	Ok(())333}334335fn auth_agent_subject() -> anyhow::Result<Subject> {336	let mut details = HashMap::new();337	if let Ok(session_id) = std::env::var("XDG_SESSION_ID") {338		let val: OwnedValue = Str::from(session_id).into();339		details.insert("session-id".to_string(), val);340		return Ok(Subject {341			subject_kind: "unix-session".to_string(),342			subject_details: details,343		});344	}345346	details.insert("pid".to_string(), OwnedValue::from(std::process::id()));347	Ok(Subject {348		subject_kind: "unix-process".to_string(),349		subject_details: details,350	})351}352353fn sh_quote(s: &str) -> String {354	format!("'{}'", s.replace('\'', "'\\''"))355}356357/// Prepend `dir` to the process `PATH`.358///359/// # SAFETY360///361/// Same as `set_var`362unsafe fn prepend_path(dir: &std::path::Path) {363	let value = match std::env::var_os("PATH") {364		Some(existing) => {365			let mut v = dir.as_os_str().to_owned();366			v.push(":");367			v.push(existing);368			v369		}370		None => dir.as_os_str().to_owned(),371	};372	unsafe {373		std::env::set_var("PATH", value);374	}375}
modifiedcrates/remowt-client/src/lib.rsdiffbeforeafterboth
--- a/crates/remowt-client/src/lib.rs
+++ b/crates/remowt-client/src/lib.rs
@@ -9,6 +9,7 @@
 use bifrostlink_ports::unix_socket::from_socket;
 use bytes::{Bytes, BytesMut};
 use camino::{Utf8Path, Utf8PathBuf};
+use remowt_link_shared::plugin::PluginEndpointsClient;
 use remowt_link_shared::{
 	Address, BifConfig, ElevateEndpoints, ElevateError, Elevator, Fs, Pty, PtyClient, ShellId,
 	Systemd,
@@ -508,6 +509,26 @@
 	pub fn endpoints<R: RemoteEndpoints<BifConfig>>(&self) -> R {
 		R::wrap(self.rpc.remote(Address::Agent))
 	}
+
+	pub async fn load_plugin(&self, id: u16, name: &str) -> Result<()> {
+		let client: PluginEndpointsClient<BifConfig> = self.endpoints();
+		client
+			.load_plugin(id, name.to_owned())
+			.await?
+			.map_err(|e| anyhow!("agent failed to load plugin: {e}"))
+	}
+	pub async fn run0_load_plugin_path(&self, id: u16, path: &str) -> Result<()> {
+		self.ensure_elevated().await?;
+		let client: PluginEndpointsClient<BifConfig> =
+			PluginEndpointsClient::wrap(self.rpc.remote(Address::AgentPrivileged));
+		client
+			.load_plugin_path(id, path.to_owned())
+			.await?
+			.map_err(|e| anyhow!("privileged agent failed to load plugin: {e}"))
+	}
+	pub fn plugin_endpoints<R: RemoteEndpoints<BifConfig>>(&self, id: u16) -> R {
+		R::wrap(self.rpc.remote(Address::Plugin(id)))
+	}
 	pub async fn run0_endpoints<R: RemoteEndpoints<BifConfig>>(&self) -> Result<R> {
 		self.ensure_elevated().await?;
 		Ok(R::wrap(self.rpc.remote(Address::AgentPrivileged)))
modifiedcrates/remowt-link-shared/src/lib.rsdiffbeforeafterboth
--- a/crates/remowt-link-shared/src/lib.rs
+++ b/crates/remowt-link-shared/src/lib.rs
@@ -13,9 +13,12 @@
 	User,
 	Agent,
 	AgentPrivileged,
+	Plugin(u16),
 }
 impl AddressT for Address {}
 
+pub mod plugin;
+
 pub use remowt_fs::{Error as FsError, Fs, FsClient};
 pub use remowt_pty::{Error as PtyError, Pty, PtyClient, ShellId};
 pub use remowt_systemd::{Error as SystemdError, Systemd, SystemdClient};
addedcrates/remowt-link-shared/src/plugin.rsdiffbeforeafterboth
--- /dev/null
+++ b/crates/remowt-link-shared/src/plugin.rs
@@ -0,0 +1,39 @@
+use std::future::Future;
+
+use bifrostlink::declarative::endpoints;
+use bifrostlink::Config;
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug, thiserror::Error)]
+pub enum Error {
+	#[error("plugin name must be a bare file name")]
+	BadName,
+	#[error("spawning plugin failed: {0}")]
+	Spawn(String),
+	#[error("agent is shutting down")]
+	Gone,
+}
+
+pub trait PluginHost: Send + Sync {
+	fn load_plugin(&self, id: u16, name: String) -> impl Future<Output = Result<(), Error>> + Send;
+
+	fn load_plugin_path(
+		&self,
+		id: u16,
+		path: String,
+	) -> impl Future<Output = Result<(), Error>> + Send;
+}
+
+pub struct PluginEndpoints<H>(pub H);
+
+#[endpoints(ns = 9)]
+impl<H: PluginHost + 'static> PluginEndpoints<H> {
+	#[endpoints(id = 1)]
+	async fn load_plugin(&self, id: u16, name: String) -> Result<(), Error> {
+		self.0.load_plugin(id, name).await
+	}
+	#[endpoints(id = 2)]
+	async fn load_plugin_path(&self, id: u16, path: String) -> Result<(), Error> {
+		self.0.load_plugin_path(id, path).await
+	}
+}
modifiedcrates/remowt-nix-daemon/Cargo.tomldiffbeforeafterboth
--- a/crates/remowt-nix-daemon/Cargo.toml
+++ b/crates/remowt-nix-daemon/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
-name = "fleet-nix-daemon"
-description = "Nix daemon proxy endpoint + connection logic for fleet"
+name = "remowt-nix-daemon"
+description = "Nix daemon proxy"
 version.workspace = true
 edition = "2021"
 
addedcrates/remowt-plugin/Cargo.tomldiffbeforeafterboth
--- /dev/null
+++ b/crates/remowt-plugin/Cargo.toml
@@ -0,0 +1,22 @@
+[package]
+name = "remowt-plugin"
+version.workspace = true
+edition = "2021"
+
+[dependencies]
+anyhow.workspace = true
+bifrostlink.workspace = true
+bifrostlink-ports.workspace = true
+bytes.workspace = true
+remowt-link-shared.workspace = true
+tokio = { workspace = true, features = [
+	"rt",
+	"net",
+	"io-std",
+	"io-util",
+	"macros",
+	"time",
+	"process",
+] }
+tracing.workspace = true
+tracing-subscriber.workspace = true
addedcrates/remowt-plugin/src/host.rsdiffbeforeafterboth
--- /dev/null
+++ b/crates/remowt-plugin/src/host.rs
@@ -0,0 +1,110 @@
+use std::ffi::OsStr;
+use std::io;
+use std::process::Stdio;
+use std::sync::Mutex;
+
+use bifrostlink::{Port, Rpc, Rtt, WeakRpc};
+use bytes::{Bytes, BytesMut};
+use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
+use tokio::process::{Child, ChildStdin, ChildStdout, Command};
+
+use remowt_link_shared::plugin::{Error, PluginEndpoints, PluginHost};
+use remowt_link_shared::{Address, BifConfig};
+
+pub fn serve(rpc: &mut Rpc<BifConfig>) {
+	let host = Host {
+		rpc: rpc.clone().downgrade(),
+		children: Mutex::new(Vec::new()),
+	};
+	PluginEndpoints(host).register_endpoints(rpc);
+}
+
+struct Host {
+	rpc: WeakRpc<BifConfig>,
+	children: Mutex<Vec<Child>>,
+}
+
+impl Host {
+	fn spawn(&self, id: u16, path: impl AsRef<OsStr>) -> Result<(), Error> {
+		let rpc = self.rpc.clone().upgrade().ok_or(Error::Gone)?;
+
+		let mut child = Command::new(path)
+			.arg(id.to_string())
+			.stdin(Stdio::piped())
+			.stdout(Stdio::piped())
+			.kill_on_drop(true)
+			.spawn()
+			.map_err(|e| Error::Spawn(e.to_string()))?;
+		let stdin = child.stdin.take().expect("stdin piped");
+		let stdout = child.stdout.take().expect("stdout piped");
+
+		rpc.add_direct(Address::Plugin(id), child_port(stdout, stdin), Rtt(0));
+		self.children.lock().expect("not poisoned").push(child);
+		Ok(())
+	}
+}
+
+impl PluginHost for Host {
+	async fn load_plugin(&self, id: u16, name: String) -> Result<(), Error> {
+		// TODO: Right now loads plugin next to the binary...
+		// But with our CA addressed schema, the plugins should be located in content-addressed subdir...
+		// Maybe it should just be scrapped in favor of load_plugin_path.
+		if name.is_empty() || name == "." || name == ".." || name.contains(['/', '\0']) {
+			return Err(Error::BadName);
+		}
+		let exe = std::env::current_exe().map_err(|e| Error::Spawn(e.to_string()))?;
+		let dir = exe
+			.parent()
+			.ok_or_else(|| Error::Spawn("primary agent has no parent directory".to_owned()))?;
+		self.spawn(id, dir.join(&name))
+	}
+
+	async fn load_plugin_path(&self, id: u16, path: String) -> Result<(), Error> {
+		if path.is_empty() || path.contains('\0') {
+			return Err(Error::BadName);
+		}
+		self.spawn(id, path)
+	}
+}
+
+fn child_port(mut stdout: ChildStdout, mut stdin: ChildStdin) -> Port {
+	Port::new(|mut rx, tx| async move {
+		let reader = async move {
+			loop {
+				let len = match stdout.read_u32().await {
+					Ok(len) => len,
+					Err(e) => {
+						tracing::error!("plugin stdout read failed: {e}");
+						break;
+					}
+				};
+				let mut buf = BytesMut::zeroed(len as usize);
+				if let Err(e) = stdout.read_exact(&mut buf).await {
+					tracing::error!("plugin stdout read failed: {e}");
+					break;
+				}
+				if tx.send(buf.freeze()).is_err() {
+					break;
+				}
+			}
+		};
+		let writer = async move {
+			while let Some(msg) = rx.recv().await {
+				if let Err(e) = write_frame(&mut stdin, msg).await {
+					tracing::error!("plugin stdin write failed: {e}");
+					break;
+				}
+			}
+		};
+		tokio::join!(reader, writer);
+	})
+}
+
+async fn write_frame(stdin: &mut ChildStdin, msg: Bytes) -> io::Result<()> {
+	let len = u32::try_from(msg.len())
+		.map_err(|_| io::Error::new(io::ErrorKind::InvalidInput, "message larger than 4GB"))?;
+	stdin.write_u32(len).await?;
+	stdin.write_all(&msg).await?;
+	stdin.flush().await?;
+	Ok(())
+}
addedcrates/remowt-plugin/src/lib.rsdiffbeforeafterboth
--- /dev/null
+++ b/crates/remowt-plugin/src/lib.rs
@@ -0,0 +1,38 @@
+use std::future::pending;
+
+use anyhow::Result;
+use bifrostlink::{Rpc, Rtt};
+use bifrostlink_ports::stdio::from_stdio;
+use tokio::runtime::Builder;
+
+pub mod host;
+
+pub use bifrostlink;
+pub use remowt_link_shared::{self, Address, BifConfig, Fs, Pty, Systemd};
+
+pub fn plugin_index() -> Result<u16> {
+	let arg = std::env::args()
+		.nth(1)
+		.ok_or_else(|| anyhow::anyhow!("missing plugin index argument"))?;
+	arg.parse()
+		.map_err(|e| anyhow::anyhow!("invalid plugin index {arg:?}: {e}"))
+}
+
+pub fn run<F>(register: F) -> Result<()>
+where
+	F: FnOnce(&mut Rpc<BifConfig>),
+{
+	tracing_subscriber::fmt()
+		.with_writer(std::io::stderr)
+		.init();
+
+	let index = plugin_index()?;
+	let runtime = Builder::new_current_thread().enable_all().build()?;
+	runtime.block_on(async move {
+		let mut rpc = Rpc::<BifConfig>::new(Address::Plugin(index));
+		rpc.add_direct(Address::Agent, from_stdio(), Rtt(0));
+		register(&mut rpc);
+		let _rpc = rpc;
+		pending::<Result<()>>().await
+	})
+}