Admin and deployment guide
Rolling Cusp out to a team. Organization setup, managed settings, installs and updates, network requirements, telemetry, platform support, and where data lives.
This guide is for the people who roll Cusp out and keep it in policy. Items marked Not yet don't exist today. We list them so you can plan around them.
Set up the organization
-
Create the organization and invite people under Account → Organization. Roles are owner, admin and member; see Organizations.
-
Choose a plan under Account → Plan & billing. Enterprise is a contract; write to sales@cusp.run.
-
Set spend limits:
- the monthly cap on usage beyond the plan;
- a default monthly budget per member, with per-member overrides.
You can also export usage as CSV for chargeback. See Plans and billing.
-
Decide data handling. Under Plan & billing → Cusp models and your data, Team and Enterprise can require zero data retention for Cusp models. Prompts to Cusp models never go to providers that may train on them. See Your data.
-
Read the activity log under Account → Organization → Activity, or export it as JSON lines for a SIEM.
Not yet:
- single sign-on (SAML or OIDC), SCIM provisioning, domain verification and auto-join;
- custom roles;
- policy pushed from the cloud to devices.
Managed settings
Cusp reads a managed settings file that users can't override. Deploy it with your usual tooling: MDM file payloads, Group Policy file copy, or configuration management.
| OS | Managed settings | Managed MCP servers |
|---|---|---|
| macOS | /Library/Application Support/Cusp/managed-settings.json | managed-mcp.json in the same folder |
| Windows | C:\Program Files\Cusp\managed-settings.json | managed-mcp.json in the same folder |
| Linux | /etc/cusp/managed-settings.json | managed-mcp.json in the same folder |
Managed files already deployed for other agents in the same format (…/ClaudeCode/…, /etc/claude-code/…) are also read, at lower precedence than
Cusp's. A managed CUSP.md in the same folder adds organization-wide instructions to every session.
Precedence, highest first: managed, then command-line --settings, then the project's local settings, then the
project's settings, then the user's settings.
- Single values come from the highest level that sets them.
- Lists are combined.
Some keys work differently:
| Key | Effect |
|---|---|
permissions.disableBypassPermissionsMode, permissions.disableAutoMode | Users can't switch sessions to bypass or auto mode. These win from any level |
permissions.blockReadsOutsideWorkingDirectories | The agent can't read outside the project folders |
sandbox.allowUnsandboxedCommands: false | No command may run outside the OS sandbox, even with approval |
availableModels | Only these models can be used. The highest level's list replaces all others |
allowedMcpServers, deniedMcpServers | Which MCP servers may connect, matched by name, URL or command |
strictKnownMarketplaces, allowedExtensions | Which Hub marketplaces and extensions may be installed. An empty list blocks installs |
sandbox.network.allowedDomains | The hosts sandboxed commands may reach. A managed list replaces the user's |
allowManagedHooksOnly, allowManagedPermissionRulesOnly, disableAllHooks | Only your hooks and permission rules apply (managed file only) |
A project's own settings can't:
- switch on auto or bypass mode;
- widen the sandbox;
- set protected environment variables;
- add hooks or allow rules before the person trusts the folder.
If a managed file isn't valid JSON, it's skipped with a warning. Validate it before you roll it out.
Not yet:
- native MDM formats (configuration profiles, ADMX);
- managed keys for telemetry, sync, turning the Hub off, or updates;
- a provider allowlist.
Install and update
Desktop app. Bundle id run.cusp.desktop, published by Wex Labs Limited. Downloads are at
cusp.run/download.
| OS | Packages | Notes |
|---|---|---|
| macOS 12+ | Universal .dmg | Signed and notarized. No .pkg yet. Deploy the .app with your MDM |
| Windows 10/11 x64 | .exe (NSIS, per-user) and .msi | Not code-signed yet, so SmartScreen warns. The WebView2 runtime downloads during install |
| Linux x64 | .AppImage, .deb, .rpm | Install bubblewrap for the shell sandbox |
Silent installs use the standard installer switches (NSIS /S, msiexec /qn). We haven't tested them across
versions yet.
Updates.
- The desktop app checks for updates at launch and once a day, and asks before installing. The stable channel is the default, and people can switch to beta in the app.
- Update files come from GitHub releases (§ Network).
- Not yet: turning updates off, pinning a version, or setting the channel by policy.
CLI.
Available with the first public release.
- For CI,
cusp setup-tokenregisters a device token.
Network
Cusp needs outbound HTTPS to:
| Host | What for | When |
|---|---|---|
api.cusp.run | Account, sync, Cusp models, telemetry you opted into | Signed in |
app.cusp.run | The web app | Using it in a browser |
hub.cusp.run | Extensions and the Hub | Browsing or installing extensions |
github.com, objects.githubusercontent.com | App and CLI updates, downloads | Updating |
models.dev | The model catalogue (names, limits, prices) | Periodically |
| Your model providers' APIs | Calls with your own provider keys, e.g. api.anthropic.com, api.openai.com, openrouter.ai | Using your own keys |
api.github.com, or your GitHub Enterprise Server | GitHub features | When connected |
Sync and remote control use a WebSocket to api.cusp.run.
On the computer:
- The daemon listens on
127.0.0.1only, on a random port. - It refuses other addresses unless started with
--allow-remote. - Its sandbox proxy and preview server also bind to loopback.
Proxies and custom CAs:
- The CLI and the daemon follow the standard
HTTPS_PROXY,NO_PROXYandNODE_EXTRA_CA_CERTSvariables. Test them in your environment before you roll out. - Not yet: reading the system proxy or PAC files in the desktop app, and client certificates (mTLS).
Telemetry
Telemetry is off until a person opts in during setup:
- crash reports are scrubbed of paths, tokens and code;
- usage metrics are counts and timings, labelled by model.
To keep it off on a machine, set CUSP_TELEMETRY=off or DO_NOT_TRACK=1 in the environment. The CLI and the daemon
honour it. Not yet: a managed setting that turns it off fleet-wide in the desktop app.
Platform support
| macOS | Linux | Windows | |
|---|---|---|---|
| Shell sandbox | Yes (Seatbelt) | Yes (bubblewrap, which must be installed) | No: shell commands are refused unless a person approves running without the sandbox |
| Sandbox network allowlist | Enforced | Through the proxy only (not a hard block) | — |
| Secret storage, desktop | Keychain | Secret Service | Credential Manager |
| Secret storage, CLI | Keychain | Secret Service (secret-tool) | Environment variables |
Where data lives on the computer
| What | Where |
|---|---|
| Daemon data (sessions database, blobs, worktrees, artifacts) | ~/.cusp for the CLI (CUSP_DATA_DIR to change it). The desktop app uses its app data folder, for example ~/Library/Application Support/run.cusp.desktop/daemon on macOS |
| Settings | ~/.cusp/settings.json; projects use .cusp/settings.json |
| Logs | cusp-daemon.log in the app's log folder, or ~/.cusp/logs. Rotated at 5 × 5 MB; CUSP_LOG_LEVEL sets the level |
| Local audit trail | harness/audit/<session>.jsonl in the data folder: permission decisions and proxied connections, kept 90 days (CUSP_AUDIT_RETENTION_DAYS) |
The cloud keeps data for the periods in Your data.