diff --git a/include/ghostty.h b/include/ghostty.h
index b6ad3295c39..a067d3fe1cb 100644
--- a/include/ghostty.h
+++ b/include/ghostty.h
@@ -1115,6 +1115,7 @@ GHOSTTY_API ghostty_surface_t ghostty_surface_new(ghostty_app_t,
                                                      const ghostty_surface_config_s*);
 GHOSTTY_API void ghostty_surface_free(ghostty_surface_t);
 GHOSTTY_API void* ghostty_surface_userdata(ghostty_surface_t);
+GHOSTTY_API void ghostty_surface_set_userdata(ghostty_surface_t, void*);
 GHOSTTY_API ghostty_app_t ghostty_surface_app(ghostty_surface_t);
 GHOSTTY_API ghostty_surface_config_s ghostty_surface_inherited_config(ghostty_surface_t, ghostty_surface_context_e);
 GHOSTTY_API void ghostty_surface_update_config(ghostty_surface_t, ghostty_config_t);
diff --git a/src/apprt/embedded.zig b/src/apprt/embedded.zig
index ac13e0165ad..9a3001d1a1c 100644
--- a/src/apprt/embedded.zig
+++ b/src/apprt/embedded.zig
@@ -1616,6 +1616,17 @@ pub const CAPI = struct {
         return surface.userdata;
     }
 
+    /// Sets the userdata associated with the surface.
+    ///
+    /// Hosts that retain a heap object as the surface userdata must be able to
+    /// clear it before that object is freed: the surface can outlive the
+    /// userdata (e.g. a queued mailbox action drains after the host released
+    /// its callback context), and callbacks would otherwise hand back a
+    /// dangling pointer. Passing null detaches the userdata.
+    export fn ghostty_surface_set_userdata(surface: *Surface, userdata: ?*anyopaque) void {
+        surface.userdata = userdata;
+    }
+
     /// Returns the app associated with a surface.
     export fn ghostty_surface_app(surface: *Surface) *App {
         return surface.app;