TokenShift Enterprise — Installation, Distribution, and Update
- Signed artifacts (
.pkg,.msi,.deb,.rpm, tarball) deployed by the customer’s MDM or fetched from the PointFive installation page. - One-time enrollment manifest — a few fields of plain JSON, deployed by MDM.
- All data is hybrid-encrypted on the device against PointFive’s public key (pinned in the binary); only PointFive’s KMS holds the matching private key.
- PointFive can control which release version is offered to a given client. PointFive cannot push configuration, rules, or behaviour changes to running clients.
1. What PointFive can and can’t push remotely
Section titled “1. What PointFive can and can’t push remotely”PointFive controls release availability — which version is offered, when, to which fraction of clients. PointFive does not control rules, configuration, opt-out, or any per-fleet behaviour at runtime — those are baked into the binary and the enrollment manifest at install time.
- No remote policy push. All config is install-time.
- No remote rule update. Rules ship in the binary.
- No remote opt-out. A user opts out by changing local config; an admin opts out by redeploying the manifest or uninstalling via MDM.
- No audit-event stream. “Who changed what” lives in the customer’s MDM audit log.
2. Distribution channels
Section titled “2. Distribution channels”| Platform | Primary channel | MDM integration |
|---|---|---|
| macOS | Signed .pkg from the PointFive installation page | Jamf, Mosyle, Kandji, JumpCloud |
| Linux (Debian/Ubuntu) | apt repository (.deb packages) | Ansible, Salt, Chef, JumpCloud, SCCM |
| Linux (RHEL/Fedora/Amazon) | yum repository (.rpm packages) | same |
| Windows | MSI installer | Group Policy, Intune, Configuration Manager |
Cross-compiled artifacts for linux/darwin/windows × amd64/arm64.
3. Code signing
Section titled “3. Code signing”| Platform | Signing |
|---|---|
| macOS | Apple Developer ID + notarization. Gatekeeper blocks unsigned binaries. |
| Windows | EV Code Signing certificate. Required for SmartScreen and Intune. |
| Linux | Repository GPG signing for apt and yum. |
Auto-update artifacts carry an additional signature; the client verifies it against a key pinned in the binary before swapping. A signature mismatch aborts the update.
4. Enrollment
Section titled “4. Enrollment”The customer admin logs into the PointFive app via SSO, picks install-time configuration (tier cap, project hash mode, recovery cache, sample allowlist, sample rate, retention extensions), and clicks Generate manifest. The app returns enrollment.json — field-by-field meaning is in Enrollment → Field reference.
The admin deploys it via MDM as root to the system path so it covers every user on the machine. A per-user variant (tokenshift enroll <path> writing under ~/.tokenshift/) is available for self-serve installs.
No signature, no expiration, no user roster, no public key in the manifest, no ingest URL in the manifest. The public key and ingest URL are pinned in the binary at build time, so manifest tampering grants no decryption capability and no exfiltration path — at worst an attacker can DoS telemetry. Regenerating and redeploying the manifest invalidates a compromised copy.
CLI surface for self-serve installs: Enrollment.
Agent harness hooks
Section titled “Agent harness hooks”The tokenshift binary supports four PreToolUse-style protocols: Claude Code, Cursor, GitHub Copilot CLI, and Codex. tokenshift install installs and updates the hook entries idempotently; tokenshift uninstall removes them. Prefix any shell command with tokenshift: to skip the rewrite for that command. Hooks always exit 0; the IDE is never blocked.
Two of the four — Cursor and Codex — run the compressing proxy inside a sandbox that can’t write outside the workspace. Compression and telemetry are unaffected, but the local recovery cache isn’t reachable from either, so tokenshift recover has nothing to replay for sessions on those two harnesses. See Data contract → Recovery cache scope.
Local intent classifier
Section titled “Local intent classifier”A second small footprint on the endpoint, separate from the tokenshift binary itself, worth calling out explicitly for anyone inventorying what gets installed:
- What it is: a compact on-device embedding model (
bge-small-en-v1.5) used to classify what a submitted prompt is about (debugging, feature work, research, and so on). Falls back to a plain keyword-based scorer if the model isn’t available — never blocks, never errors. - Process lifecycle: not a persistent system service. A small helper process starts on demand the first time a harness session needs it, and shuts itself down after about an hour of inactivity — it only exists while you’re actively using the harness.
- Disk: the model bundle downloads once and is cached under
~/.tokenshift/classifier/, verified the same way (signed, checksummed) as the binary’s own auto-update artifacts. - Network: one check per day, at most, against the same pinned control-plane host the binary already talks to for its own updates — not a new destination to allowlist, and not a per-prompt call.
- Data: prompt text is read locally to produce the classification label; the prompt itself is never transmitted anywhere, including to produce that label. Only the label ships in telemetry (Tier 2+,
enrichment.intent) — see Data contract → Enrichment.
5. Encryption
Section titled “5. Encryption”HTTPS protects in transit only. TokenShift adds per-record hybrid encryption against PointFive’s public key, pinned in the binary at build time. The client never holds anything but the public key, so a compromised laptop or manifest yields no decryption capability. The matching private key lives only in PointFive’s key-management system, with audited access and no plaintext extraction. Key rotation ships a new binary version with both current and next keys pinned. A single PointFive-wide keypair is the default; per-tenant keypairs are available on request for regulated customers.
6. Updates
Section titled “6. Updates”Auto-update is opt-in on the client side: the developer (or the admin’s deploy script) runs tokenshift update, and the binary verifies the artifact’s signature against its pinned key before atomically swapping itself. PointFive never push-applies an update — but PointFive does control which version a given client is offered, ramping rollouts by client bucket and with a kill switch that stops all auto-updates at once.
MDM-managed fleets typically continue to upgrade via MDM at the admin’s pace; auto-update is the path for developer machines that aren’t tightly MDM-managed. The client_state signal reports the running binary version so admins can see staleness.
7. Version skew
Section titled “7. Version skew”Customers will routinely run multiple versions in their fleet. The backend supports the last several minor versions of each signal’s schema; older versions are rejected at ingest and admins see data dry up via stalled client_state rows. Sunset is the customer’s lever, not PointFive’s — PointFive refuses old versions, the admin pushes the upgrade.
8. Threat model
Section titled “8. Threat model”| Threat | Mitigation |
|---|---|
| Malicious tampered binary substituted for the legitimate one | Code signing on every platform; MDM enforces signature verification before install. |
| Auto-update artifact tampering | Artifact signature verified against a key pinned in the binary before swap; mismatched signature aborts the update with a sticky failure state, so the same bad version isn’t re-attempted. |
| Malicious enrollment manifest substituted | Maximum impact: attacker changes config (DoS of telemetry), redirects records (which they can’t decrypt), or invalidates tokens. Public key and ingest URL are pinned in the binary, so manifest tampering grants no decryption capability and no exfiltration path. |
| Stolen laptop’s enrollment manifest exfiltrated | Attacker has the tenant credentials and HMAC key. They can send fake records as that tenant (DoS / poisoning dashboards) and compute user_id for guessed emails — but they had to compromise a customer machine first. Mitigation: regenerate the manifest and redeploy. |
| Network MITM | TLS to pinned PointFive root certificates; ingest URL is pinned in the binary. Hybrid encryption means even a successful MITM gets ciphertext only. |
| PointFive ingest breach | Per-record ciphertext; an attacker without access to the private key gets no decryption capability. The ingest service is stateless. |
| PointFive key-management breach | Worst case — private key extracted means in-flight data decryptable until rotation. Compensated by the key-management posture (no plaintext extraction, audited access). |
| PointFive release-signing key compromise | Attacker can sign malicious binaries. Mitigated by OS-level code-signing chains (Apple Developer ID, EV cert) — independent of PointFive’s keys. An attacker would need to compromise both. |
| Stale binary running known-vulnerable code | client_state reports version; admins see staleness and drive upgrades. |
Attacker tries to reverse user_id from leaked PointFive data | Without the per-tenant HMAC key (which lives in customer manifests, not on PointFive’s side), unreversible. |
9. Design boundaries
Section titled “9. Design boundaries”Things we deliberately don’t do:
- Remote configuration push. No behaviour-changing control plane.
- Manifest signing. Public key and ingest URL are pinned in the binary; tampering grants no decryption capability.
- Manifest expiration. Regenerating and redeploying the manifest handles compromise, without the operational burden of expiry.
- User roster in manifest. Replaced by local resolution from
git config user.email. - Per-tenant encryption keypairs. Available on request, not the default.
- In-binary crash reporting.
client_statecarries a self-check boolean, nothing more.
Glossary
Section titled “Glossary”- Enrollment manifest — JSON file generated by the PointFive app, deployed via MDM.
- MDM — Mobile Device Management / endpoint management system (Jamf, JumpCloud, Intune, Ansible, etc.).
- Pinned public key — PointFive’s ingest public key, compiled into the binary at build time. Not in the manifest.
- Tenant — A single customer organization.
- Local intent classifier — an on-device model (plus a keyword-based fallback) that labels what a prompt is about. Runs in a short-lived helper process, not a persistent service; never transmits prompt text.