Quickstart

Prerequisites

• One of the supported agent harnesses installed and working — Claude Code, Cursor, GitHub Copilot CLI, Codex, or opencode. Install detects which you have and wires the right hooks for each.
• Your tenant ID (a UUID handed to you at onboarding) — required for telemetry, recovery sync, and any cloud-side feature.
• An API key generated in the PointFive app — get it before you start. The install-mdm-template.sh / -win.ps1 installers abort without it, and equally on a user key or a truncated paste; the Ansible path never enrolls, so there put it in the enrollment.json you drop yourself.

Install

One script does everything: places the binary, enables telemetry, enrolls it to your tenant, wires the agent hooks, verifies the wire is live, and self-updates. The same script works two ways — run it yourself on one machine, or have your MDM push it fleet-wide.

Download install-mdm-template.sh (macOS, Linux) or install-mdm-template-win.ps1 (Windows) from the PointFive app — it’s generated per-tenant, with your tenant ID already baked in. Your API key is deliberately not baked in: generate one in the console and paste it into the block at the top of the script.

On a single machine

Open the script and replace PASTE-YOUR-API-KEY-HERE on the line inside the marked block, keeping the quotes:

######## PASTE YOUR API KEY FROM THE TOKENSHIFT CONSOLE HERE ########
export TOKENSHIFT_BEARER_TOKEN="${TOKENSHIFT_BEARER_TOKEN:-PASTE-YOUR-API-KEY-HERE}"
#####################################################################

Then run it:

sudo bash install-mdm-template.sh

That’s the whole configuration — the key lives in the script, and the same edited copy works for a single machine and for an MDM push. If the placeholder is left unedited the script stops before installing anything, so a machine never enrolls without the key it will need once the token is enforced.

Needs root exactly once, to place the binary and wire your shell profile. The binary itself ends up user-owned under ~/.tokenshift/bin afterward — everything it does from then on (self-update, hooks) runs as you, never root again.

On Windows

Same shape, a different script. Open install-mdm-template-win.ps1 and set your API key in the marked block:

######## PASTE YOUR API KEY FROM THE TOKENSHIFT CONSOLE HERE ########
$env:TOKENSHIFT_BEARER_TOKEN = 'p5ts_...'
#####################################################################

Then run it as yourself:

powershell -NoProfile -ExecutionPolicy Bypass -File install-mdm-template-win.ps1

Note

Windows needs no admin at all and installs per-user: the account that runs the script is the account that gets TokenShift, under %USERPROFILE%\.tokenshift. amd64 only — the script relaunches itself 64-bit if it starts under a 32-bit PowerShell host. Remove it with tokenshift uninstall --purge; deleting the directory by hand leaves the agent hooks pointing at a binary that is gone.

Across the organization, via MDM

Every MDM method ends up at the same result — a user-owned binary, enrolled to your tenant, hooks wired — but each uses whichever push mechanism is most native to that tool:

MDM	Mechanism
JumpCloud	Runs the same per-tenant install-mdm-template.sh directly as a Command — no different from the single-machine copy above.
Jamf	Pushes install-mdm-template.sh as a script payload, then drops the enrollment manifest as a second policy.
Intune	macOS: pushes install-mdm-template.sh as a shell script assigned to a device group. Windows: pushes install-mdm-template-win.ps1 as a platform script assigned in user context.
Ansible	A playbook that performs the same steps natively (download, unpack into the user-owned store, wire PATH, drop the manifest) — no script invocation needed.

Full policy/task detail per tool, verifying a fleet-wide rollout, updating an already-deployed manifest, and decommissioning are in MDM rollout.

Either way — single machine or MDM-pushed — every step is logged to a file under ~/.tokenshift/ (%USERPROFILE%\.tokenshift on Windows) you can hand to support if something goes wrong.

Tip

tokenshift doctor is the first thing to run any time something feels off — it reports pinning, manifest, telemetry, and hook state in one block. tokenshift doctor --verify also ships one synthetic record through the live ingest path to confirm the wire is actually live.

What just happened

• The agent’s Bash commands now run through TokenShift: it recognizes the command, runs the real thing, and hands back a shorter version of the output the model sees.
• Some commands are replaced before they run, not just compressed. Those print [tokenshift: ran:<command>] as their first line, so no output is ever attributed to a command that did not produce it.
• Full output is preserved in a local recovery cache, on harnesses where the proxy runs unsandboxed (Claude Code, Copilot CLI, opencode). The model gets a hint like [Full output: tokenshift recover a1b2c3d4] and can fetch the original whenever it needs it. Cursor and Codex sandbox the proxy, so there’s nothing for recover to replay on those two — see Recovery cache scope.
• Telemetry ships hybrid-encrypted records straight to the ingest endpoint. No control plane, no broker.

Troubleshooting

Windows: tokenshift isn’t recognized right after installing

The installer adds %USERPROFILE%\.tokenshift\bin to your user PATH and broadcasts the change. But Windows hands each process a copy of the environment when that process starts, and never re-reads it. So:

• a terminal opened from the Start menu or taskbar after the install sees it
• a terminal that was already open never will — and nor will a new tab or split inside it, because those inherit the same stale copy from the terminal itself

Open a fresh terminal, or paste the one-liner the installer prints to fix just the current shell:

$env:Path = "$env:USERPROFILE\.tokenshift\bin;$env:Path"

Note

This is ordinary Windows behaviour — every installer that edits PATH works this way, and it says nothing about whether TokenShift is working. Your agent is unaffected: the hooks the installer wires invoke the binary by full path, so compression and telemetry keep running even in an agent that was already open. PATH only matters for typing tokenshift yourself.

Next

• How it works — the architectural overview.
• Core commands — doctor, recover, and the other handful you might run by hand.
• MDM rollout — full per-tool detail.
• Security overview — what stays local, what goes off-device.