instabox 0.5.4 → 0.6.0

package/bin/instabox.mjs

@@ -25,6 +25,7 @@ import { checkCli, findCli, installCli, installCommand, isOnboarding, real, runC
 import { browserCommand, callbackHandler } from '../lib/login.mjs';
 import { makeDirPrivate, sessionArgs } from '../lib/ssh.mjs';
 import { loadCredentials, saveCredentials } from '../lib/credentials.mjs';
+import { agentName, track } from '../lib/telemetry.mjs';
 
 // Same variables, same order as the instabox CLI, so both talk to one server.
 const API = (
@@ -61,11 +62,22 @@ function usage() {
       --no-cli                      do not install or update the instabox CLI
       --no-skills                   do not install the instabox agent skills
   npx instabox@latest <command>     run an instabox CLI command (instabox help lists them)
+
+  Usage data (steps and outcomes, never names or arguments) goes to the instabox team;
+  INSTABOX_NO_TELEMETRY=1 or DO_NOT_TRACK=1 turns it off.
 `);
 }
 
 // ---- instabox API ------------------------------------------------------------------------------
-const client = createClient(API);
+const VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+  } catch {
+    return 'unknown';
+  }
+})();
+const client = createClient(API, { userAgent: `instabox-npm/${VERSION}` });
+let freshSignIn = false;
 
 function openBrowser(url) {
   const cmd = browserCommand(url);
@@ -210,6 +222,7 @@ async function signedIn() {
     } catch {}
   }
   const t = await signInWithInvite();
+  freshSignIn = true;
   saveCredentials(API, t);
   return t;
 }
@@ -396,8 +409,31 @@ function nextSteps(rows) {
 async function onboard(wantBox) {
   console.log(`\n  ${bold('instabox')} ${dim('· a cloud box in seconds')}\n`);
 
+  const started = Date.now();
   client.use(await signedIn());
   const me = await client.call('GET', '/v1/me').catch((e) => die(`instabox did not accept the sign-in: ${e.message}`));
+  // outcome: ready, or quota_full; never names, paths or messages.
+  const report = (outcome, extra = {}) =>
+    track(
+      'npx_onboard',
+      me.userId,
+      {
+        outcome,
+        want_box: wantBox,
+        fresh_sign_in: freshSignIn,
+        duration_ms: Date.now() - started,
+        no_cli: process.argv.includes('--no-cli'),
+        no_skills: process.argv.includes('--no-skills'),
+        tty: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        agent: agentName(),
+        os: process.platform,
+        arch: process.arch,
+        node_version: process.versions.node,
+        npm_version: VERSION,
+        ...extra,
+      },
+      { server: API },
+    );
   console.log(
     `  ${dim('signed in as')} ${bold(me.name || me.login)}${me.login && me.name ? dim(` (${me.login})`) : ''} ${dim('· not you?')} npx instabox@latest logout`,
   );
@@ -405,6 +441,7 @@ async function onboard(wantBox) {
   const cli = ensureCli();
   if (!wantBox) {
     await reportInstalls(cli);
+    await report('ready');
     return nextSteps([
       ['npx instabox@latest sh', 'start a new box and SSH into it'],
       ['instabox ls', 'list your boxes'],
@@ -426,15 +463,18 @@ async function onboard(wantBox) {
     // The way out of the limit is `instabox rm`, so the CLI and the skills land before the exit.
     console.log();
     await reportInstalls(cli);
+    await report('quota_full');
     return quotaFull(e);
   });
-  const ready = `ready in ${((Date.now() - t0) / 1000).toFixed(1)}s`;
+  const boxMs = Date.now() - t0;
+  const ready = `ready in ${(boxMs / 1000).toFixed(1)}s`;
   if (!tty) {
     console.log(`\n  ${green('✓')} box ${bold(box.name)} ${ready}`);
     const got = await client.call('GET', '/v1/machines/' + enc(box.id)).catch(() => null);
     const note = guestUserNote(box.user, box.name, got?.guestUser);
     if (note) console.log(dim(`  ${note}`));
     await reportInstalls(cli);
+    await report('ready', { box_ready_ms: boxMs });
     return nextSteps([
       [`instabox ssh ${box.name} -- <command>`, 'run a command in it'],
       [`instabox ssh ${box.name}`, 'open a shell in it, from a terminal'],
@@ -472,6 +512,7 @@ async function onboard(wantBox) {
   const note = guestUserNote(box.user, m.name, m.guestUser);
   if (note) console.log(dim(`  ${note}`));
   await reportInstalls(cli);
+  await report('ready', { box_ready_ms: boxMs, ssh: true });
   console.log(dim(`  type ${'exit'} to leave · stuck? press Enter, then ~.`));
   // The box's prompt is ~37 columns; narrower terminals make bash scroll the input line sideways.
   if (process.stdout.isTTY && process.stdout.columns > 0 && process.stdout.columns < 60)

package/lib/api.mjs

@@ -12,12 +12,19 @@ export class ApiError extends Error {
 
 export function createClient(
   server,
-  { fetch = globalThis.fetch, load = () => loadCredentials(server), save = (t) => saveCredentials(server, t) } = {},
+  {
+    fetch = globalThis.fetch,
+    load = () => loadCredentials(server),
+    save = (t) => saveCredentials(server, t),
+    userAgent = '',
+  } = {},
 ) {
   let session = null;
 
   const send = (token, method, path, body, key) => {
     const headers = { Accept: 'application/json' };
+    // instabox-npm/<version>: the server attributes the requests to this package.
+    if (userAgent) headers['User-Agent'] = userAgent;
     if (token) headers.Authorization = `Bearer ${token}`;
     if (body !== undefined) headers['Content-Type'] = 'application/json';
     if (key) headers['Idempotency-Key'] = key;

package/lib/telemetry.mjs

@@ -0,0 +1,97 @@
+// Usage telemetry (docs/analytics.md); telemetry.json is shared with cmd/instabox/telemetry.go.
+import { randomUUID } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { configDir } from './credentials.mjs';
+
+// A write-only capture key, not a secret.
+export const TELEMETRY_KEY = 'phc_nPznuUD5U36v4aSQVHaV4mbKwGTpjjR8Xt9Ukb5mATfY';
+export const TELEMETRY_HOST = 'https://us.i.posthog.com';
+export const DEFAULT_SERVER = 'https://api.instabox.sh';
+// The instabox CLI prints the same when it creates telemetry.json (cmd/instabox/telemetry.go).
+const NOTICE =
+  'instabox sends usage data (command names and outcomes, never arguments) to help improve it;\n' +
+  'set INSTABOX_NO_TELEMETRY=1 or DO_NOT_TRACK=1 to turn it off.\n';
+
+export function telemetryDisabled(env = process.env) {
+  const on = (k) =>
+    !['', '0', 'false'].includes(
+      String(env[k] ?? '')
+        .trim()
+        .toLowerCase(),
+    );
+  return on('DO_NOT_TRACK') || on('INSTABOX_NO_TELEMETRY');
+}
+
+export function agentName(env = process.env) {
+  if (env.CLAUDECODE) return 'claude-code';
+  if (env.CURSOR_TRACE_ID) return 'cursor';
+  if (env.CODEX_SANDBOX) return 'codex';
+  return '';
+}
+
+function readState(env) {
+  try {
+    const st = JSON.parse(readFileSync(join(configDir(env), 'telemetry.json'), 'utf8'));
+    return st?.anonymousId ? st : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeState(env, st) {
+  const dir = configDir(env);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  const tmp = join(dir, `.telemetry.${randomUUID()}.tmp`);
+  writeFileSync(tmp, JSON.stringify(st) + '\n', { mode: 0o600 });
+  renameSync(tmp, join(dir, 'telemetry.json'));
+}
+
+// Sends event for the account userId. Never throws; waits at most 1.5 s.
+export async function track(
+  event,
+  userId,
+  properties,
+  {
+    server,
+    env = process.env,
+    fetch = globalThis.fetch,
+    key = TELEMETRY_KEY,
+    host = TELEMETRY_HOST,
+    stderr = process.stderr,
+  } = {},
+) {
+  if (!key || !userId || String(server).replace(/\/+$/, '') !== DEFAULT_SERVER || telemetryDisabled(env)) return;
+  try {
+    let st = readState(env);
+    if (!st) {
+      st = { anonymousId: randomUUID() };
+      writeState(env, st);
+      if (stderr.isTTY) stderr.write(NOTICE);
+    }
+    // Another account than the last one: a fresh anonymous ID to link.
+    if (st.userId && st.userId !== userId) st = { anonymousId: randomUUID() };
+    const id = String(userId);
+    const lib = { $lib: 'instabox-npm' };
+    const batch = [
+      {
+        event,
+        distinct_id: id,
+        uuid: randomUUID(),
+        timestamp: new Date().toISOString(),
+        properties: { ...properties, ...lib },
+      },
+    ];
+    const merge = st.userId !== userId || !st.merged;
+    if (merge)
+      batch.push({ event: '$identify', distinct_id: id, properties: { $anon_distinct_id: st.anonymousId, ...lib } });
+    const res = await fetch(host + '/batch/', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ api_key: key, batch }),
+      signal: AbortSignal.timeout(1500),
+    });
+    if (res.ok && merge) writeState(env, { anonymousId: st.anonymousId, userId, merged: true });
+  } catch {}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instabox",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "A cloud box for your coding agent, the instabox CLI and its agent skills in one command: npx instabox@latest",
   "type": "module",
   "bin": {