Skip to content

πŸ™Œ OpenHands: AI-Driven Development

fix: configure agent-server telemetry in Canvas launchers (#16348)

Rohit Malhotra68de5c58872a
diff --git a/__tests__/scripts/dev-safe.test.ts b/__tests__/scripts/dev-safe.test.ts
index fc7a86a467..1f44b675b4 100644
--- a/__tests__/scripts/dev-safe.test.ts
+++ b/__tests__/scripts/dev-safe.test.ts
@@ -20,6 +20,8 @@ import {
buildSafeDevConfigAsync,
buildNpmScriptCommand,
buildAgentServerCommand,
+ buildAgentServerEnv,
+ buildAgentServerTelemetryEnv,
buildRuntimeServicesInfo,
formatMissingUvxGuidance,
formatMissingFrontendDependenciesGuidance,
@@ -381,6 +383,76 @@ describe("formatMissingUvxGuidance", () => {
});
});
+describe("buildAgentServerTelemetryEnv", () => {
+ it("configures PostHog telemetry by default without seeding consent", () => {
+ expect(buildAgentServerTelemetryEnv({})).toEqual({
+ OH_TELEMETRY_EXPORTER: "posthog",
+ OH_TELEMETRY_POSTHOG_API_KEY:
+ "phc_kBtz5nKmxVRRQ7HtPwr2QX9eMC5j65zE86QKocVNwb4U",
+ OH_TELEMETRY_POSTHOG_HOST: "https://us.i.posthog.com",
+ });
+ });
+
+ it("prefers explicit agent-server telemetry settings", () => {
+ expect(
+ buildAgentServerTelemetryEnv({
+ OH_TELEMETRY_EXPORTER: "http",
+ OH_TELEMETRY_CONSENT: "denied",
+ OH_TELEMETRY_POSTHOG_API_KEY: "phc_agent",
+ OH_TELEMETRY_POSTHOG_HOST: "https://agent.example",
+ VITE_POSTHOG_API_KEY: "phc_frontend",
+ VITE_POSTHOG_HOST: "https://frontend.example",
+ }),
+ ).toEqual({
+ OH_TELEMETRY_EXPORTER: "http",
+ OH_TELEMETRY_CONSENT: "denied",
+ OH_TELEMETRY_POSTHOG_API_KEY: "phc_agent",
+ OH_TELEMETRY_POSTHOG_HOST: "https://agent.example",
+ });
+ });
+
+ it("uses frontend telemetry settings when agent-server settings are absent", () => {
+ expect(
+ buildAgentServerTelemetryEnv({
+ VITE_POSTHOG_API_KEY: "phc_frontend",
+ VITE_POSTHOG_HOST: "https://frontend.example",
+ }),
+ ).toEqual({
+ OH_TELEMETRY_EXPORTER: "posthog",
+ OH_TELEMETRY_POSTHOG_API_KEY: "phc_frontend",
+ OH_TELEMETRY_POSTHOG_HOST: "https://frontend.example",
+ });
+ });
+
+ it("maps frontend do-not-track to the agent-server kill switch", () => {
+ expect(buildAgentServerTelemetryEnv({ VITE_DO_NOT_TRACK: "1" })).toEqual({
+ DO_NOT_TRACK: "1",
+ });
+ });
+
+ it("includes telemetry defaults in the full agent-server environment", () => {
+ const env = buildAgentServerEnv(
+ {
+ tmuxTmpDir: "/tmp/tmux",
+ stateDir: "/tmp/state",
+ conversationsPath: "/tmp/conversations",
+ bashEventsDir: "/tmp/bash-events",
+ vscodePort: 19000,
+ secretKey: "secret",
+ sessionApiKey: "session",
+ backendBaseUrl: "http://127.0.0.1:18000",
+ canvasToolsDir: "/tmp/tools",
+ },
+ {},
+ );
+
+ expect(env).toMatchObject({
+ OH_TELEMETRY_EXPORTER: "posthog",
+ OH_SESSION_API_KEYS_0: "session",
+ });
+ });
+});
+
describe("buildAgentServerCommand", () => {
it("uses released PyPI version by default with all packages pinned", () => {
const cmd = buildAgentServerCommand({});
@@ -398,6 +470,8 @@ describe("buildAgentServerCommand", () => {
"openhands-workspace==1.40.1",
"--with",
"agent-client-protocol<0.11",
+ "--with",
+ "posthog>=6,<7",
"agent-server",
]);
expect(cmd.source).toBe("PyPI (1.40.1, default)");
@@ -420,6 +494,8 @@ describe("buildAgentServerCommand", () => {
"openhands-workspace==1.18.0",
"--with",
"agent-client-protocol<0.11",
+ "--with",
+ "posthog>=6,<7",
"agent-server",
]);
expect(cmd.source).toBe("PyPI (1.18.0)");
@@ -441,6 +517,8 @@ describe("buildAgentServerCommand", () => {
"git+https://github.com/OpenHands/software-agent-sdk@feature-branch#subdirectory=openhands-tools",
"--with",
"git+https://github.com/OpenHands/software-agent-sdk@feature-branch#subdirectory=openhands-workspace",
+ "--with",
+ "posthog>=6,<7",
"agent-server",
]);
expect(cmd.source).toBe("git (feature-branch)");
@@ -460,6 +538,8 @@ describe("buildAgentServerCommand", () => {
"git+https://github.com/OpenHands/software-agent-sdk@abc1234#subdirectory=openhands-tools",
"--with",
"git+https://github.com/OpenHands/software-agent-sdk@abc1234#subdirectory=openhands-workspace",
+ "--with",
+ "posthog>=6,<7",
"agent-server",
]);
expect(cmd.source).toBe("git (abc1234)");
@@ -494,6 +574,8 @@ describe("buildAgentServerCommand", () => {
path.join(sdk, "openhands-tools"),
"--with-editable",
path.join(sdk, "openhands-workspace"),
+ "--with",
+ "posthog>=6,<7",
"agent-server",
]);
expect(cmd.source).toBe(`local (${sdk})`);
diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
index 6e45167705..84e23fcfbe 100644
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@@ -125,6 +125,30 @@ if [ -n "${AUTOMATION_POSTHOG_API_KEY:-}" ]; then
export AUTOMATION_POSTHOG_HOST="${AUTOMATION_POSTHOG_HOST:-${VITE_POSTHOG_HOST:-${CONFIG_POSTHOG_HOST:-}}}"
fi
+# Configure product analytics for the agent-server. The SDK uses its own
+# OH_TELEMETRY_* variables, so mirror the same Canvas/PostHog defaults used by
+# the frontend and automation backend while preserving explicit operator
+# overrides. Consent stays in persisted settings, where the backend/UI owns it.
+if [ "${VITE_DO_NOT_TRACK:-}" = "1" ]; then
+ export DO_NOT_TRACK="${DO_NOT_TRACK:-1}"
+fi
+
+if [ -z "${OH_TELEMETRY_POSTHOG_API_KEY:-}" ]; then
+ if [ -n "${VITE_POSTHOG_API_KEY:-}" ]; then
+ export OH_TELEMETRY_POSTHOG_API_KEY="$VITE_POSTHOG_API_KEY"
+ elif [ "${DO_NOT_TRACK:-}" != "1" ]; then
+ export OH_TELEMETRY_POSTHOG_API_KEY="${CONFIG_POSTHOG_API_KEY:-}"
+ fi
+fi
+
+if [ -z "${OH_TELEMETRY_EXPORTER:-}" ] && [ -n "${OH_TELEMETRY_POSTHOG_API_KEY:-}" ]; then
+ export OH_TELEMETRY_EXPORTER="posthog"
+fi
+
+if [ "${OH_TELEMETRY_EXPORTER:-}" = "posthog" ] && [ -n "${OH_TELEMETRY_POSTHOG_API_KEY:-}" ]; then
+ export OH_TELEMETRY_POSTHOG_HOST="${OH_TELEMETRY_POSTHOG_HOST:-${VITE_POSTHOG_HOST:-${CONFIG_POSTHOG_HOST:-}}}"
+fi
+
# AGENT_SERVER_URL β€” needed by automation sandbox callbacks.
export AGENT_SERVER_URL="${AGENT_SERVER_URL:-http://127.0.0.1:${AGENT_SERVER_PORT}}"
diff --git a/scripts/dev-safe.mjs b/scripts/dev-safe.mjs
index 8d788cb33a..55e2ed2320 100644
--- a/scripts/dev-safe.mjs
+++ b/scripts/dev-safe.mjs
@@ -53,6 +53,11 @@ const DEFAULT_AGENT_SERVER_VERSION = SHARED_DEFAULTS.versions.agentServer;
// the SDK's ACP client. Hold acp <0.11 until a fixed SDK ships. See config/defaults.json.
const AGENT_CLIENT_PROTOCOL_CONSTRAINT =
SHARED_DEFAULTS.constraints?.agentClientProtocol;
+const DEFAULT_AGENT_SERVER_TELEMETRY_POSTHOG_API_KEY =
+ SHARED_DEFAULTS.telemetry.posthogApiKey;
+const DEFAULT_AGENT_SERVER_TELEMETRY_POSTHOG_HOST =
+ SHARED_DEFAULTS.telemetry.posthogHost;
+const AGENT_SERVER_POSTHOG_CONSTRAINT = "posthog>=6,<7";
const FRONTEND_REQUIRED_BINS = ["cross-env", "react-router"];
/**
@@ -434,6 +439,8 @@ export function buildAgentServerCommand(env = process.env) {
path.join(localPath, "openhands-tools"),
"--with-editable",
path.join(localPath, "openhands-workspace"),
+ "--with",
+ AGENT_SERVER_POSTHOG_CONSTRAINT,
"agent-server",
);
source = `local (${localPath})`;
@@ -458,6 +465,8 @@ export function buildAgentServerCommand(env = process.env) {
`${baseGitUrl}#subdirectory=openhands-tools`,
"--with",
`${baseGitUrl}#subdirectory=openhands-workspace`,
+ "--with",
+ AGENT_SERVER_POSTHOG_CONSTRAINT,
"agent-server",
);
source = `git (${gitRef})`;
@@ -478,6 +487,7 @@ export function buildAgentServerCommand(env = process.env) {
if (AGENT_CLIENT_PROTOCOL_CONSTRAINT) {
uvxArgs.push("--with", AGENT_CLIENT_PROTOCOL_CONSTRAINT);
}
+ uvxArgs.push("--with", AGENT_SERVER_POSTHOG_CONSTRAINT);
uvxArgs.push("agent-server");
source = `PyPI (${version})`;
} else {
@@ -496,6 +506,7 @@ export function buildAgentServerCommand(env = process.env) {
if (AGENT_CLIENT_PROTOCOL_CONSTRAINT) {
uvxArgs.push("--with", AGENT_CLIENT_PROTOCOL_CONSTRAINT);
}
+ uvxArgs.push("--with", AGENT_SERVER_POSTHOG_CONSTRAINT);
uvxArgs.push("agent-server");
source = `PyPI (${DEFAULT_AGENT_SERVER_VERSION}, default)`;
}
@@ -685,8 +696,52 @@ function buildConfigFromPorts(ports, cwd, env) {
* @param {ReturnType<typeof buildSafeDevConfig>} config - Config from buildSafeDevConfig
* @returns {Record<string, string>} Environment variables for agent-server
*/
-export function buildAgentServerEnv(config) {
+export function buildAgentServerTelemetryEnv(env = process.env) {
+ const telemetryDisabled =
+ env.VITE_DO_NOT_TRACK === "1" || env.DO_NOT_TRACK === "1";
+ const result = {};
+
+ for (const key of [
+ "OH_TELEMETRY_EXPORTER",
+ "OH_TELEMETRY_POSTHOG_API_KEY",
+ "OH_TELEMETRY_POSTHOG_HOST",
+ "OH_TELEMETRY_HTTP_ENDPOINT",
+ "OH_TELEMETRY_HTTP_TOKEN",
+ "OH_TELEMETRY_CONSENT",
+ "OH_TELEMETRY_CONSENT_MODE",
+ "OH_TELEMETRY_SALT",
+ ]) {
+ if (env[key]) result[key] = env[key];
+ }
+
+ if (telemetryDisabled) {
+ result.DO_NOT_TRACK = "1";
+ }
+
+ const apiKey =
+ env.OH_TELEMETRY_POSTHOG_API_KEY ||
+ env.VITE_POSTHOG_API_KEY ||
+ (telemetryDisabled ? "" : DEFAULT_AGENT_SERVER_TELEMETRY_POSTHOG_API_KEY);
+ const exporter = env.OH_TELEMETRY_EXPORTER || (apiKey ? "posthog" : "");
+
+ if (exporter) {
+ result.OH_TELEMETRY_EXPORTER = exporter;
+ }
+
+ if (exporter === "posthog" && apiKey) {
+ result.OH_TELEMETRY_POSTHOG_API_KEY = apiKey;
+ result.OH_TELEMETRY_POSTHOG_HOST =
+ env.OH_TELEMETRY_POSTHOG_HOST ||
+ env.VITE_POSTHOG_HOST ||
+ DEFAULT_AGENT_SERVER_TELEMETRY_POSTHOG_HOST;
+ }
+
+ return result;
+}
+
+export function buildAgentServerEnv(config, env = process.env) {
return {
+ ...buildAgentServerTelemetryEnv(env),
// Force Python to use UTF-8 for all file I/O and streams.
//
// On Windows, Python defaults to the system ANSI codepage (e.g. cp1252).