Forkit Connect

Forkit Connect is the local engine for discovering AI runtimes, reviewing what is running on-device, and preparing metadata-only Passport and lifecycle handoff into Forkit.dev.

Naming convention:

• Product name: Forkit Connect
• Command name: forkit-connect
• Published package name: forkit-connect
• Workspace dependency alias: @forkit/connect

Install Surface

• Package name: forkit-connect
• Public binary: forkit-connect
• Published bootstrap: npx forkit-connect ...
• Global install: npm install -g forkit-connect
• Current Ubuntu shortcut: pnpm run install:ubuntu installs into user space without sudo

Ubuntu Install

Requirements:

• Node.js 20+
• npm
• pnpm for local packaging from this repo
• On Linux, libsecret-tools is recommended so Forkit Connect can store login credentials in Secret Service

Published npm install:

npx forkit-connect --help
npm install -g forkit-connect
forkit-connect login
forkit-connect scan
forkit-connect inbox

From integrations/connect:

pnpm run install:ubuntu
export PATH="$HOME/.local/bin:$PATH"
forkit-connect --help
forkit-connect status

The installer:

• builds and packs the current Connect package
• installs it into ~/.local/share/forkit-connect
• links forkit-connect into ~/.local/bin
• offers to install libsecret-tools on apt-based Linux so login persistence works without a separate manual step
• avoids sudo and does not require the full monorepo at runtime after install

If libsecret-tools is not present, read-only commands still work, but stored login persistence on Linux will stay limited until Secret Service tooling is installed.

If ~/.local/bin is already on your PATH, the command is immediately accessible.

Public Commands

• forkit-connect login — link this device to Forkit.dev with the device flow
• forkit-connect init — optional advanced local identity and privacy posture setup
• forkit-connect scan — discover local runtimes and AI models
• forkit-connect inbox — review the Smart Registration Inbox
• forkit-connect connect <modelNameOrDiscoveryHash> — prepare or sync a passport draft for a detected model
• forkit-connect runtime register — register or reuse the current repo/worktree as a governed runtime
• forkit-connect runtime observe --gaid <gaid> — emit a repo-scoped runtime journal for the current runtime target
• forkit-connect status — show public Connect readiness status
• forkit-connect changes — view collected local evidence, runtime signal history, and pending sync items
• forkit-connect doctor — run local environment, secure-storage, backend-session, and account checks
• forkit-connect update-check — inspect release metadata without enabling auto-update
• forkit-connect start — start the local daemon loop
• forkit-connect stop — stop the background daemon without deleting local state
• forkit-connect uninstall — preview a cautious uninstall plan and write local backup logs
• forkit-connect uninstall --confirm — stop the daemon, clear stale notification waiters, and preserve state
• forkit-connect uninstall --confirm --purge-state — additionally remove local state after writing a backup

Advanced Commands

Advanced flows remain available under the same binary, including review, daemon, config, pulse, c2, train, agent, notification utilities, and runtime target management.

Runtime registration notes:

forkit-connect runtime register --workspace <workspaceId> --project <projectId>
forkit-connect runtime register --dry-run --json

The command infers the current repo/worktree, records safe runtime identity metadata, and reuses the same governed runtime on repeat runs instead of creating duplicates.

Useful notification diagnostics:

forkit-connect notify logs
forkit-connect notify cleanup --dry-run
forkit-connect notify cleanup

notify cleanup only targets stale Forkit Connect desktop notification waiter processes. It does not delete local state or credentials.

Privacy and Security Posture

• Session credentials are stored outside state.v1.json.
• Backend-bound endpoint metadata is sanitized before upload.
• Connect does not require normal users to manage backend API keys.
• Local runtime telemetry is best-effort health data, not billing or exact cost accounting.
• Website and backend governance remain authoritative for registration and C2 decisions.
• Auto-update is not enabled as a package-install workflow.

Local Tarball Flow

From integrations/connect:

pnpm run prepack
npm pack

Then install the generated tarball into a clean directory:

mkdir -p /tmp/forkit-connect-smoke
cd /tmp/forkit-connect-smoke
npm init -y
npm install /absolute/path/to/forkit-connect-<version>.tgz
npx forkit-connect --help
npx forkit-connect status
npx forkit-connect inbox
npx forkit-connect login

For a user-space Ubuntu install that creates a stable command path, prefer pnpm run install:ubuntu.

Development Notes

• Build config: tsconfig.build.json
• Package smoke script: pnpm run smoke:package
• Dist pruning removes compiled tests and source maps before packaging

See QUICKSTART.md for the recommended onboarding sequence.