diff --git a/doc/languages-frameworks/astal.section.md b/doc/languages-frameworks/astal.section.md
new file mode 100644
index 000000000000..34022b9c5850
--- /dev/null
+++ b/doc/languages-frameworks/astal.section.md
@@ -0,0 +1,39 @@
+# Astal {#astal}
+
+Astal is a collection of building blocks for creating custom desktop shells.
+
+## Bundling {#astal-bundling}
+
+Bundling Astal application is done using `ags` tool, you can use it like this:
+
+```nix
+ags.bundle {
+  pname = "hyprpanel";
+  version = "1.0.0";
+
+  src = fetchFromGitHub { ... };
+
+  # change your entry file (default is `app.ts`)
+  entry = "app.ts";
+
+  dependencies = [
+    # list here astal modules, that your package depends on
+    # `astal3`, `astal4` and `astal.io` are automatically included
+    astal.apps
+    astal.battery
+    astal.bluetooth
+
+    # you can also list here other runtime dependencies
+    hypridle
+    hyprpicker
+    hyprsunset
+  ];
+
+  # GTK 4 support is opt-in
+  enableGtk4 = true;
+
+  meta = { ... };
+}
+```
+
+You can also pass all other arguments that are supported by `stdenv.mkDerivation`.
diff --git a/doc/languages-frameworks/index.md b/doc/languages-frameworks/index.md
index c3f192a1a38b..50c83ec939bc 100644
--- a/doc/languages-frameworks/index.md
+++ b/doc/languages-frameworks/index.md
@@ -53,6 +53,7 @@ Each supported language or software ecosystem has its own package set named `<la
 ```{=include=} sections
 agda.section.md
 android.section.md
+astal.section.md
 beam.section.md
 bower.section.md
 chicken.section.md
diff --git a/doc/redirects.json b/doc/redirects.json
index 5065007b0ae9..abb49fa940a7 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -2349,6 +2349,12 @@
   "using-predefined-android-package-compositions": [
     "index.html#using-predefined-android-package-compositions"
   ],
+  "astal": [
+    "index.html#astal"
+  ],
+  "astal-bundling": [
+    "index.html#astal-bundling"
+  ],
   "spawning-emulator-instances": [
     "index.html#spawning-emulator-instances"
   ],
diff --git a/nixos/doc/manual/release-notes/rl-2505.section.md b/nixos/doc/manual/release-notes/rl-2505.section.md
index 1ca298c684fd..fe1ecbd07bdc 100644
--- a/nixos/doc/manual/release-notes/rl-2505.section.md
+++ b/nixos/doc/manual/release-notes/rl-2505.section.md
@@ -277,6 +277,13 @@
   [v1.7.0](https://github.com/jtroo/kanata/releases/tag/v1.7.0)
   for more information.
 
+- `ags` was updated to v2, which is just a CLI for Astal now. Components are available as a different package set `astal.*`.
+  If you want to use v1, it is available as `ags_1` package.
+
+  See the release notes of
+  [v2.0.0](https://github.com/Aylur/ags/releases/tag/v2.0.0)
+  for more information.
+
 - `nodePackages.expo-cli` has been removed, as it was deprecated by upstream. The suggested replacement is the `npx expo` command.
 
 - DokuWiki with the Caddy webserver (`services.dokuwiki.webserver = "caddy"`) now sets up sites with Caddy's automatic HTTPS instead of HTTP-only.
diff --git a/pkgs/by-name/ag/ags/bundle.nix b/pkgs/by-name/ag/ags/bundle.nix
new file mode 100644
index 000000000000..d1aa9a91b391
--- /dev/null
+++ b/pkgs/by-name/ag/ags/bundle.nix
@@ -0,0 +1,86 @@
+{
+  lib,
+  ags,
+  astal,
+  dart-sass,
+  fzf,
+  gjs,
+  gnused,
+  gobject-introspection,
+  gtk3,
+  gtk4-layer-shell,
+  stdenvNoCC,
+  wrapGAppsHook3,
+  wrapGAppsHook4,
+}:
+{
+  entry ? "app.ts",
+  dependencies ? [ ],
+  enableGtk4 ? false,
+  ...
+}@attrs:
+stdenvNoCC.mkDerivation (
+  finalAttrs:
+  attrs
+  // {
+    nativeBuildInputs = (attrs.nativeBuildInputs or [ ]) ++ [
+      (ags.override { extraPackages = dependencies; })
+      gnused
+      gobject-introspection
+      (if enableGtk4 then wrapGAppsHook4 else wrapGAppsHook3)
+    ];
+
+    buildInputs =
+      (attrs.buildInputs or [ ])
+      ++ dependencies
+      ++ [
+        gjs
+        astal.astal4
+        astal.astal3
+        astal.io
+      ];
+
+    preFixup =
+      ''
+        gappsWrapperArgs+=(
+          --prefix PATH : ${
+            lib.makeBinPath (
+              dependencies
+              ++ [
+                dart-sass
+                fzf
+                gtk3
+              ]
+            )
+          }
+        )
+      ''
+      + lib.optionalString enableGtk4 ''
+        gappsWrapperArgs+=(
+          --set LD_PRELOAD "${gtk4-layer-shell}/lib/libgtk4-layer-shell.so"
+        )
+      ''
+      + (attrs.preFixup or "");
+
+    installPhase =
+      let
+        outBin = "$out/bin/${finalAttrs.pname}";
+      in
+      # bash
+      ''
+        runHook preInstall
+
+        mkdir -p "$out/bin" "$out/share"
+        cp -r ./* "$out/share"
+        ags bundle "${entry}" "${outBin}" -d "SRC='$out/share'"
+
+        chmod +x "${outBin}"
+
+        if ! head -n 1 "${outBin}" | grep -q "^#!"; then
+          sed -i '1i #!${gjs}/bin/gjs -m' "${outBin}"
+        fi
+
+        runHook postInstall
+      '';
+  }
+)
diff --git a/pkgs/by-name/ag/ags/package.nix b/pkgs/by-name/ag/ags/package.nix
index 09efa681b42a..7171970174b3 100644
--- a/pkgs/by-name/ag/ags/package.nix
+++ b/pkgs/by-name/ag/ags/package.nix
@@ -1,78 +1,122 @@
 {
   lib,
-  buildNpmPackage,
+  astal,
+  blueprint-compiler,
+  buildGoModule,
+  callPackage,
+  dart-sass,
+  symlinkJoin,
   fetchFromGitHub,
-  meson,
-  ninja,
-  pkg-config,
-  gobject-introspection,
+  fetchpatch2,
   gjs,
-  glib-networking,
-  gnome-bluetooth,
-  gtk-layer-shell,
-  libpulseaudio,
-  libsoup_3,
-  networkmanager,
-  upower,
-  typescript,
-  wrapGAppsHook3,
-  linux-pam,
+  glib,
+  gobject-introspection,
+  gtk4-layer-shell,
+  installShellFiles,
   nix-update-script,
-}:
+  nodejs,
+  stdenv,
+  wrapGAppsHook3,
 
-buildNpmPackage rec {
+  extraPackages ? [ ],
+}:
+buildGoModule rec {
   pname = "ags";
-  version = "1.8.2";
+  version = "2.2.1";
 
   src = fetchFromGitHub {
     owner = "Aylur";
     repo = "ags";
-    rev = "v${version}";
-    hash = "sha256-ebnkUaee/pnfmw1KmOZj+MP1g5wA+8BT/TPKmn4Dkwc=";
-    fetchSubmodules = true;
+    tag = "v${version}";
+    hash = "sha256-snHhAgcH8hACWZFaAqHr5uXH412UrAuA603OK02MxN8=";
   };
 
-  npmDepsHash = "sha256-ucWdADdMqAdLXQYKGOXHNRNM9bhjKX4vkMcQ8q/GZ20=";
+  patches = [
+    # refactor for better nix support
+    (fetchpatch2 {
+      url = "https://github.com/Aylur/ags/commit/17df94c576d0023185770f901186db427f2ec0a2.diff?full_index=1";
+      hash = "sha256-tcoifkYmXjV+ZbeAFRHuk8cVmxWMrS64syvQMGGKAVA=";
+    })
+  ];
 
-  mesonFlags = [ (lib.mesonBool "build_types" true) ];
+  vendorHash = "sha256-Pw6UNT5YkDVz4HcH7b5LfOg+K3ohrBGPGB9wYGAQ9F4=";
+  proxyVendor = true;
+
+  ldflags = [
+    "-s"
+    "-w"
+    "-X main.astalGjs=${astal.gjs}/share/astal/gjs"
+    "-X main.gtk4LayerShell=${gtk4-layer-shell}/lib/libgtk4-layer-shell.so"
+  ];
 
   nativeBuildInputs = [
-    meson
-    ninja
-    pkg-config
-    gjs
-    gobject-introspection
-    typescript
     wrapGAppsHook3
+    gobject-introspection
+    installShellFiles
   ];
 
-  # Most of the build inputs here are basically needed for their typelibs.
-  buildInputs = [
-    gjs
-    glib-networking
-    gnome-bluetooth
-    gtk-layer-shell
-    libpulseaudio
-    libsoup_3
-    linux-pam
-    networkmanager
-    upower
+  buildInputs = extraPackages ++ [
+    glib
+    astal.io
+    astal.astal3
+    astal.astal4
+    gobject-introspection # needed for type generation
   ];
 
-  postPatch = ''
-    chmod u+x ./post_install.sh && patchShebangs ./post_install.sh
-  '';
+  preFixup =
+    let
+      # git files are usually in `dev` output.
+      # `propagatedBuildInputs` are also available in the gjs runtime
+      # so we also want to generate types for these.
+      depsOf = pkg: [ (pkg.dev or pkg) ] ++ (map depsOf (pkg.propagatedBuildInputs or [ ]));
+      girDirs = symlinkJoin {
+        name = "gir-dirs";
+        paths = lib.flatten (map depsOf buildInputs);
+      };
+    in
+    ''
+      gappsWrapperArgs+=(
+        --prefix EXTRA_GIR_DIRS : "${girDirs}/share/gir-1.0"
+        --prefix PATH : "${
+          lib.makeBinPath (
+            [
+              gjs
+              nodejs
+              dart-sass
+              blueprint-compiler
+              astal.io
+            ]
+            ++ extraPackages
+          )
+        }"
+      )
+    '';
 
-  passthru.updateScript = nix-update-script { };
+  postInstall =
+    lib.optionalString (stdenv.buildPlatform.canExecute stdenv.hostPlatform)
+      # bash
+      ''
+        installShellCompletion \
+          --cmd ags \
+          --bash <($out/bin/ags completion bash) \
+          --fish <($out/bin/ags completion fish) \
+          --zsh <($out/bin/ags completion zsh)
+      '';
+
+  passthru = {
+    bundle = callPackage ./bundle.nix { };
+    updateScript = nix-update-script { };
+  };
 
   meta = {
+    description = "Scaffolding CLI for Astal widget system";
     homepage = "https://github.com/Aylur/ags";
-    description = "EWW-inspired widget system as a GJS library";
     changelog = "https://github.com/Aylur/ags/releases/tag/v${version}";
     license = lib.licenses.gpl3Plus;
     maintainers = with lib.maintainers; [
       foo-dogsquared
       johnrtitor
+      perchun
     ];
     mainProgram = "ags";
     platforms = lib.platforms.linux;
diff --git a/pkgs/by-name/ag/ags_1/package.nix b/pkgs/by-name/ag/ags_1/package.nix
new file mode 100644
index 000000000000..09efa681b42a
--- /dev/null
+++ b/pkgs/by-name/ag/ags_1/package.nix
@@ -0,0 +1,80 @@
+{
+  lib,
+  buildNpmPackage,
+  fetchFromGitHub,
+  meson,
+  ninja,
+  pkg-config,
+  gobject-introspection,
+  gjs,
+  glib-networking,
+  gnome-bluetooth,
+  gtk-layer-shell,
+  libpulseaudio,
+  libsoup_3,
+  networkmanager,
+  upower,
+  typescript,
+  wrapGAppsHook3,
+  linux-pam,
+  nix-update-script,
+}:
+
+buildNpmPackage rec {
+  pname = "ags";
+  version = "1.8.2";
+
+  src = fetchFromGitHub {
+    owner = "Aylur";
+    repo = "ags";
+    rev = "v${version}";
+    hash = "sha256-ebnkUaee/pnfmw1KmOZj+MP1g5wA+8BT/TPKmn4Dkwc=";
+    fetchSubmodules = true;
+  };
+
+  npmDepsHash = "sha256-ucWdADdMqAdLXQYKGOXHNRNM9bhjKX4vkMcQ8q/GZ20=";
+
+  mesonFlags = [ (lib.mesonBool "build_types" true) ];
+
+  nativeBuildInputs = [
+    meson
+    ninja
+    pkg-config
+    gjs
+    gobject-introspection
+    typescript
+    wrapGAppsHook3
+  ];
+
+  # Most of the build inputs here are basically needed for their typelibs.
+  buildInputs = [
+    gjs
+    glib-networking
+    gnome-bluetooth
+    gtk-layer-shell
+    libpulseaudio
+    libsoup_3
+    linux-pam
+    networkmanager
+    upower
+  ];
+
+  postPatch = ''
+    chmod u+x ./post_install.sh && patchShebangs ./post_install.sh
+  '';
+
+  passthru.updateScript = nix-update-script { };
+
+  meta = {
+    homepage = "https://github.com/Aylur/ags";
+    description = "EWW-inspired widget system as a GJS library";
+    changelog = "https://github.com/Aylur/ags/releases/tag/v${version}";
+    license = lib.licenses.gpl3Plus;
+    maintainers = with lib.maintainers; [
+      foo-dogsquared
+      johnrtitor
+    ];
+    mainProgram = "ags";
+    platforms = lib.platforms.linux;
+  };
+}
diff --git a/pkgs/development/libraries/astal/modules/io.nix b/pkgs/development/libraries/astal/modules/io.nix
index 716430bdf5a1..be3bdf2e164a 100644
--- a/pkgs/development/libraries/astal/modules/io.nix
+++ b/pkgs/development/libraries/astal/modules/io.nix
@@ -2,7 +2,13 @@
 (buildAstalModule {
   name = "io";
   sourceRoot = "lib/astal/io";
-  meta.description = "Astal core library";
+  meta = {
+    description = "Astal core library";
+    longDescription = ''
+      Astal is a collection of building blocks for creating custom desktop shells
+    '';
+    mainProgram = "astal";
+  };
 }).overrideAttrs
   {
     # add an update script only in one place,