Get started with one agent

Create a workspace, connect your AI coding tool, and review its activity, rules, and signed records. Start with one agent on Free. New workspaces include a no-card 14-day Team trial; afterward, keep one agent on Free or choose a paid plan.

Commands are shown for Windows first, then macOS and Linux. On Windows, type them exactly as shown, with .cmd: PowerShell's default script policy blocks plain npx, npm and scopebond-agent, and the .cmd forms work in PowerShell and Command Prompt without changing any policy.

1. Create the workspace and add an agent

Open https://cloud.scopebond.com/app and sign in with Google, Microsoft, or GitHub. Use the account your team invited, if you have an invitation. Open Agents → Add an agent, choose your coding tool, and name it. One tool used by one person counts as one agent. (You can also add the agent on the approval page in step 2.)

2. Connect this computer

You need Node.js 22.13 or later. Check with node --version; if it is missing or older, install the current LTS (on Windows: winget install --id OpenJS.NodeJS.LTS -e, or the installer from nodejs.org), then open a new terminal window.

Open your own terminal, outside your AI tool, and run the sign-in. Run it from your home folder (cd ~): it sets Scopebond up for your user across every project.

Windows PowerShell (in Command Prompt, use cd /d %USERPROFILE% instead of cd ~):

cd ~
npx.cmd -y @scopebond/hook@latest login https://cloud.scopebond.com

macOS or Linux:

cd ~
npx -y @scopebond/hook@latest login https://cloud.scopebond.com

Add --cursor for Cursor or --codex for Codex. Open the link printed in your terminal, check the code matches, choose your workspace agent (or add it there), and approve within 10 minutes. The page then follows the computer until its first action arrives. Existing agent settings are preserved. For Codex, run /hooks in Codex and choose Trust for Scopebond.

3. Keep the computer connected

Start the Scopebond Agent with your sign-in; it is part of the standard install. It runs in the background, sends waiting records, keeps rules, the connection and the Scopebond version current, and checks once a day that everything works. On Windows it shows a tray icon; on macOS and Linux it notifies you when something needs attention. The hook checks supported actions even when the agent is not running.

Windows (PowerShell or Command Prompt):

npm.cmd install -g @scopebond/agent@latest
scopebond-agent.cmd autostart on
scopebond-agent.cmd status

macOS or Linux:

npm install -g @scopebond/agent@latest
scopebond-agent autostart on
scopebond-agent status

To let your AI tool run these steps for you, use the prompt under Prompt to use for your AI agent to install on https://scopebond.com/get-started; you still approve the connection yourself.

4. Review your first action

Start a new AI-tool session and ask it to list project files. Check Agents for the connection and Activity for the action. In Rules, every rule starts on Monitor: it records what it would have blocked. Choose Block for the rules you want enforced; recording alone does not prevent an action. Scopebond's own protection is always on: the agent cannot change Scopebond's settings or remove it. Cursor file edits are recorded for review, rather than prevented. A required GitHub check can stop an out-of-policy edit from merging. Local Codex actions are supported; Codex cloud tasks need a required GitHub check at merge.

Windows:

npx.cmd -y @scopebond/hook@latest status
npx.cmd -y @scopebond/hook@latest doctor

macOS or Linux:

npx -y @scopebond/hook@latest status
npx -y @scopebond/hook@latest doctor

The workspace receives activity records, never prompts, file contents, or secrets. If unreachable, records wait locally for delivery later. More setup detail: Connect an agent.

When something goes wrong

Each command is the Windows form; on macOS and Linux drop .cmd.

What you see	Why	The one fix
`npx : File …\npx.ps1 cannot be loaded because running scripts is disabled on this system` (or the same for `npm` or `scopebond-agent`)	PowerShell's default script policy blocks the `.ps1` shim	Type the same command with `.cmd`: `npx.cmd`, `npm.cmd`, `scopebond-agent.cmd`. No policy change is needed
`Scopebond needs Node.js 22.13 or later; this is Node 22.x`	Node is too old, or an older Node comes first on PATH	`winget install --id OpenJS.NodeJS.LTS -e`, open a new window; if `node --version` is still old, `where.exe node` lists every Node in PATH order
`scopebond-agent.cmd` is not recognized right after installing it	npm's global folder is not on PATH (common on a standard Windows account)	Start it once by its full path: `& "$env:APPDATA\npm\scopebond-agent.cmd" autostart on` (its autostart entry remembers where it is). To use the short name, `npm.cmd prefix -g` prints the folder; add it for your user with `[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";<that folder>", "User")` and open a new window
`The code expired before it was approved`, or the approval page says the code is not waiting	Codes last 10 minutes and work once	Run the sign-in again for a new code: `npx.cmd -y @scopebond/hook@latest login https://cloud.scopebond.com`
`status` says NOT DELIVERING, or `doctor` says the connection is refused	The workspace no longer accepts this computer (revoked, replaced or removed)	Sign in again with the same command; waiting records are delivered afterwards
Activity stays empty after approving	The AI tool's session started before setup, or its settings were not changed	Start a new session; then `npx.cmd -y @scopebond/hook@latest doctor` names what is missing
`status` shows records waiting and the agent "not running"	The Scopebond Agent is not started	`scopebond-agent.cmd autostart on`
Other projects report nothing, and `status` names a project's `.scopebond` folder as the active configuration	An earlier sign-in ran inside that project folder	`cd ~` (Command Prompt: `cd /d %USERPROFILE%`), then run the sign-in again from your home folder

Local-only installation

Without a workspace, run npx.cmd -y @scopebond/hook@latest init in your project root (npx on macOS and Linux); add --cursor or --codex for your tool. To set up your user across projects, use npx.cmd -y @scopebond/hook@latest install. Codex requires the same /hooks trust step. Use npx.cmd -y @scopebond/hook@latest log to see local signed records and npx.cmd -y @scopebond/hook@latest verify to check them offline.