diff --git a/Cargo.lock b/Cargo.lock
index f2b02dbc03..5bec426311 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2957,7 +2957,7 @@ dependencies = [
 
 [[package]]
 name = "iroh-net"
-version = "0.28.1"
+version = "0.28.2"
 dependencies = [
  "anyhow",
  "axum",
diff --git a/iroh-dns-server/examples/convert.rs b/iroh-dns-server/examples/convert.rs
index 3015726adf..cbb363e072 100644
--- a/iroh-dns-server/examples/convert.rs
+++ b/iroh-dns-server/examples/convert.rs
@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 use std::str::FromStr;
 
 use clap::Parser;
diff --git a/iroh-dns-server/examples/publish.rs b/iroh-dns-server/examples/publish.rs
index ba059a35ef..cf18ae4493 100644
--- a/iroh-dns-server/examples/publish.rs
+++ b/iroh-dns-server/examples/publish.rs
@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 use std::str::FromStr;
 
 use anyhow::{bail, Result};
diff --git a/iroh-dns-server/examples/resolve.rs b/iroh-dns-server/examples/resolve.rs
index b89f514185..8d33fba25b 100644
--- a/iroh-dns-server/examples/resolve.rs
+++ b/iroh-dns-server/examples/resolve.rs
@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 use std::net::SocketAddr;
 
 use clap::{Parser, ValueEnum};
diff --git a/iroh-dns-server/src/lib.rs b/iroh-dns-server/src/lib.rs
index 09180131a7..22019aa107 100644
--- a/iroh-dns-server/src/lib.rs
+++ b/iroh-dns-server/src/lib.rs
@@ -1,5 +1,6 @@
 //! A DNS server and pkarr relay
 
+#![allow(deprecated)]
 #![deny(missing_docs, rustdoc::broken_intra_doc_links)]
 
 pub mod config;
diff --git a/iroh-net/Cargo.toml b/iroh-net/Cargo.toml
index ce40bc7b77..b438f62044 100644
--- a/iroh-net/Cargo.toml
+++ b/iroh-net/Cargo.toml
@@ -1,9 +1,9 @@
 [package]
 name = "iroh-net"
-version = "0.28.1"
+version = "0.28.2"
 edition = "2021"
 readme = "README.md"
-description = "networking support for iroh"
+description = "networking support for iroh (deprecated, use the iroh crate)"
 license = "MIT OR Apache-2.0"
 authors = ["dignifiedquire <me@dignifiedquire.com>", "n0 team"]
 repository = "https://github.com/n0-computer/iroh"
diff --git a/iroh-net/README.md b/iroh-net/README.md
index 2d6faa6f64..f76bf4113d 100644
--- a/iroh-net/README.md
+++ b/iroh-net/README.md
@@ -1,5 +1,12 @@
 # iroh-net
 
+<div class="warning">
+
+The `iroh-net` crate has been renamed to `iroh`.  Please use the
+`iroh` crate instead.
+
+</div>
+
 This crate contains the networking support for iroh. Iroh networking is built on direct peer-to-peer [QUIC](https://en.wikipedia.org/wiki/QUIC) connections that use relays and holepunching. The main structure for connection is the `Endpoint` entrypoint.
 
 Peer to peer connectivity is established with the help of a _relay server_. The relay server provides Session Traversal Utilities for NAT [(STUN)](https://en.wikipedia.org/wiki/STUN) for the peers and connection coordination using the [DERP protocol](https://pkg.go.dev/tailscale.com/derp) (Designated Relay for Encrypted Packets protocol). If no direct connection can be established, the connection is relayed via the server.
diff --git a/iroh-net/bench/src/bin/bulk.rs b/iroh-net/bench/src/bin/bulk.rs
index e5280198b2..a8d107f4e5 100644
--- a/iroh-net/bench/src/bin/bulk.rs
+++ b/iroh-net/bench/src/bin/bulk.rs
@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 use std::collections::BTreeMap;
 
 use anyhow::Result;
diff --git a/iroh-net/bench/src/lib.rs b/iroh-net/bench/src/lib.rs
index a591581d26..0adb9ee51a 100644
--- a/iroh-net/bench/src/lib.rs
+++ b/iroh-net/bench/src/lib.rs
@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 use std::{
     num::ParseIntError,
     str::FromStr,
diff --git a/iroh-net/examples/connect-unreliable.rs b/iroh-net/examples/connect-unreliable.rs
index aa352dbbb3..97d682bd4a 100644
--- a/iroh-net/examples/connect-unreliable.rs
+++ b/iroh-net/examples/connect-unreliable.rs
@@ -5,6 +5,9 @@
 //! This example uses the default relay servers to attempt to holepunch, and will use that relay server to relay packets if the two devices cannot establish a direct UDP connection.
 //!
 //! Run the `listen-unreliable` example first (`iroh-net/examples/listen-unreliable.rs`), which will give you instructions on how to run this example to watch two nodes connect and exchange bytes.
+
+#![allow(deprecated)]
+
 use std::net::SocketAddr;
 
 use anyhow::Context;
diff --git a/iroh-net/examples/connect.rs b/iroh-net/examples/connect.rs
index 2693825a14..6ba7d7cd97 100644
--- a/iroh-net/examples/connect.rs
+++ b/iroh-net/examples/connect.rs
@@ -5,6 +5,9 @@
 //! This example uses the default relay servers to attempt to holepunch, and will use that relay server to relay packets if the two devices cannot establish a direct UDP connection.
 //!
 //! Run the `listen` example first (`iroh-net/examples/listen.rs`), which will give you instructions on how to run this example to watch two nodes connect and exchange bytes.
+
+#![allow(deprecated)]
+
 use std::net::SocketAddr;
 
 use anyhow::Context;
diff --git a/iroh-net/examples/dht_discovery.rs b/iroh-net/examples/dht_discovery.rs
index bb7eecfdb7..b3318c47d8 100644
--- a/iroh-net/examples/dht_discovery.rs
+++ b/iroh-net/examples/dht_discovery.rs
@@ -8,6 +8,9 @@
 //! You can look at the published pkarr DNS record using <https://app.pkarr.org/>.
 //!
 //! To see what is going on, run with `RUST_LOG=iroh_pkarr_node_discovery=debug`.
+
+#![allow(deprecated)]
+
 use std::str::FromStr;
 
 use clap::Parser;
diff --git a/iroh-net/examples/listen-unreliable.rs b/iroh-net/examples/listen-unreliable.rs
index f54a5c8862..6eb8f023bb 100644
--- a/iroh-net/examples/listen-unreliable.rs
+++ b/iroh-net/examples/listen-unreliable.rs
@@ -3,6 +3,9 @@
 //! This example uses the default relay servers to attempt to holepunch, and will use that relay server to relay packets if the two devices cannot establish a direct UDP connection.
 //! run this example from the project root:
 //!     $ cargo run --example listen-unreliable
+
+#![allow(deprecated)]
+
 use anyhow::Context;
 use futures_lite::StreamExt;
 use iroh_net::{key::SecretKey, relay::RelayMode, Endpoint};
diff --git a/iroh-net/examples/listen.rs b/iroh-net/examples/listen.rs
index 1a3828c6e4..b9ac82886b 100644
--- a/iroh-net/examples/listen.rs
+++ b/iroh-net/examples/listen.rs
@@ -3,6 +3,9 @@
 //! This example uses the default relay servers to attempt to holepunch, and will use that relay server to relay packets if the two devices cannot establish a direct UDP connection.
 //! run this example from the project root:
 //!     $ cargo run --example listen
+
+#![allow(deprecated)]
+
 use std::time::Duration;
 
 use anyhow::Context;
diff --git a/iroh-net/examples/locally-discovered-nodes.rs b/iroh-net/examples/locally-discovered-nodes.rs
index a2217adfe8..d475c89344 100644
--- a/iroh-net/examples/locally-discovered-nodes.rs
+++ b/iroh-net/examples/locally-discovered-nodes.rs
@@ -3,6 +3,9 @@
 //! This example creates an iroh endpoint, a few additional iroh endpoints to discover, waits a few seconds, and reports all of the iroh NodeIds (also called `[iroh_net::key::PublicKey]`s) it has discovered.
 //!
 //! This is an async, non-determinate process, so the number of NodeIDs discovered each time may be different. If you have other iroh endpoints or iroh nodes with [`LocalSwarmDiscovery`] enabled, it may discover those nodes as well.
+
+#![allow(deprecated)]
+
 use std::time::Duration;
 
 use iroh_net::{
diff --git a/iroh-net/src/bin/iroh-relay.rs b/iroh-net/src/bin/iroh-relay.rs
index 5de6e04963..079d2718fa 100644
--- a/iroh-net/src/bin/iroh-relay.rs
+++ b/iroh-net/src/bin/iroh-relay.rs
@@ -3,6 +3,8 @@
 //! This handles only the CLI and config file loading, the server implementation lives in
 //! [`iroh_net::relay::server`].
 
+#![allow(deprecated)]
+
 use std::{
     net::{Ipv6Addr, SocketAddr},
     path::{Path, PathBuf},
diff --git a/iroh-net/src/lib.rs b/iroh-net/src/lib.rs
index dc41b45cef..93ba09050a 100644
--- a/iroh-net/src/lib.rs
+++ b/iroh-net/src/lib.rs
@@ -1,5 +1,12 @@
 //! Peer-to-peer QUIC connections.
 //!
+//! <div class="warning">
+//!
+//! The `iroh-net` crate has been renamed to `iroh`.  Please use the
+//! `iroh` crate instead.
+//!
+//! </div>
+//!
 //! iroh-net is a library to establish direct connectivity between peers.  It exposes an
 //! interface to [QUIC] connections and streams to the user, while implementing direct
 //! connectivity using [hole punching] complemented by relay servers under the hood.
@@ -230,6 +237,10 @@
 //! [`Connection::open_bi`]: crate::endpoint::Connection::open_bi
 //! [`Connection::accept_bi`]: crate::endpoint::Connection::accept_bi
 
+#![deprecated(
+    note = "This crate has been renamed from 'iroh-net' to 'iroh', please use the new crate"
+)]
+#![allow(deprecated)]
 #![recursion_limit = "256"]
 #![deny(missing_docs, rustdoc::broken_intra_doc_links)]
 #![cfg_attr(iroh_docsrs, feature(doc_cfg))]
diff --git a/iroh-router/examples/custom-protocol.rs b/iroh-router/examples/custom-protocol.rs
index b4bd6e8b23..d2709f33d6 100644
--- a/iroh-router/examples/custom-protocol.rs
+++ b/iroh-router/examples/custom-protocol.rs
@@ -29,6 +29,8 @@
 //!
 //! That's it! Follow along in the code below, we added a bunch of comments to explain things.
 
+#![allow(deprecated)]
+
 use std::{collections::BTreeSet, sync::Arc};
 
 use anyhow::Result;
diff --git a/iroh-router/src/lib.rs b/iroh-router/src/lib.rs
index 6bdd6cd565..5db2abdec3 100644
--- a/iroh-router/src/lib.rs
+++ b/iroh-router/src/lib.rs
@@ -1,3 +1,5 @@
+#![allow(deprecated)]
+
 mod protocol;
 mod router;