diff --git a/__tests__/package-library.test.ts b/__tests__/package-library.test.ts
index 00e41df322..a4013e24e1 100644
--- a/__tests__/package-library.test.ts
+++ b/__tests__/package-library.test.ts
@@ -1,4 +1,5 @@
 // @vitest-environment node
+import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { describe, expect, it } from "vitest";
@@ -104,6 +105,31 @@ describe("package library metadata", () => {
     expect(violations).toEqual([]);
   });
 
+  it("prints startup guidance only for global installs", () => {
+    const runPostinstall = (isGlobal: boolean) => {
+      const env = { ...process.env };
+      if (isGlobal) {
+        env.npm_config_global = "true";
+      } else {
+        delete env.npm_config_global;
+      }
+
+      return spawnSync(packageJson.scripts.postinstall, {
+        encoding: "utf8",
+        env,
+        shell: true,
+      });
+    };
+
+    const dependencyInstall = runPostinstall(false);
+    const globalInstall = runPostinstall(true);
+
+    expect(dependencyInstall.status).toBe(0);
+    expect(dependencyInstall.stdout).toBe("");
+    expect(globalInstall.status).toBe(0);
+    expect(globalInstall.stdout).toContain("To start Agent Canvas, run:");
+  });
+
   it("ships runtime logger dependencies for the published CLI", () => {
     expect(packageJson.dependencies).toMatchObject({
       winston: "3.19.0",
diff --git a/package.json b/package.json
index 9348691389..9986229c2f 100644
--- a/package.json
+++ b/package.json
@@ -96,6 +96,7 @@
     "prelint": "npm run make-i18n",
     "lint": "npm run typecheck && eslint src && prettier --check src/**/*.{ts,tsx}",
     "lint:fix": "eslint src --fix && prettier --write src/**/*.{ts,tsx}",
+    "postinstall": "node -e \"if (process.env.npm_config_global === 'true') { console.log('\\n\\x1b[32m\\x1b[1m\\u2713 @openhands/agent-canvas installed!\\x1b[0m\\n\\nTo start Agent Canvas, run:\\n\\n  \\x1b[36m\\x1b[1magent-canvas\\x1b[0m\\n\\nThis launches the full stack at \\x1b[36mhttp://localhost:8000\\x1b[0m.\\n\\nDocs: https://docs.openhands.dev/openhands/usage/agent-canvas/setup\\n') }\"",
     "prepare": "husky",
     "typecheck": "react-router typegen && tsc",
     "typecheck:staged": "react-router typegen && npx tsc --noEmit --skipLibCheck",