Self-host a Cursor Agent SDK agent

Create the VM#

On your computer (pick another name if my-cursor-agent is taken):

ssh exe.dev new --name=my-cursor-agent
ssh my-cursor-agent.exe.xyz

Install Node.js and the CLI#

On the VM. The Agent SDK needs Node.js 22.13 or later; install Node.js 24 from NodeSource, and the CLI into ~/.local, so updates need no sudo:

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
npm config set prefix ~/.local
npm install --global @grok/agent-sdk@0.4
export PATH="$HOME/.local/bin:$PATH"
agent-sdk --version

Expect 0.4. and a patch version. ~/.local/bin is already on the PATH of new shells.

Create the reviewer#

Set GITHUB_REPOS to your repositories, then scaffold Cursor's security-reviewer template and put it under git:

GITHUB_REPOS=acme/api,acme/web
agent-sdk init ~/security-reviewer --template security-reviewer \
  --var repos="$GITHUB_REPOS" --json < /dev/null | grep '"ok"'
cd ~/security-reviewer
git init -q && git add -A && git commit -qm "security-reviewer from the Agent SDK template"
agent-sdk validate --dir .

Expect "ok": true and has no diagnostics. bot/lib/repos.ts now lists your repositories.

Sign in to Cursor#

agent-sdk login

It prints a https://cursor.com/loginDeepControl?... link and waits. Open the link on your computer, sign in, and approve. The CLI stores the API key it was given in ~/.config/agent-serve/credentials.json, mode 600. Check:

agent-sdk whoami

It names your Cursor account.

Run the evals#

The template's two smoke cases send a made-up diff (one with an XSS bug, one that only touches the README) and check that the reviewer flags the first and passes the second. Eval sessions skip the GitHub write.

agent-sdk eval --dir .

Expect 2 passed. These turns use your Cursor usage.

Start the service#

agent-sdk serve subscribes to pull request events for the repositories in bot/lib/repos.ts and serves the playground on port 3000. The exe.dev HTTPS proxy only lets in people signed in with access to the VM, so the server admits whoever gets that far (--allow-anonymous), including to the reviewer's GitHub access (--allow-anonymous-cursor-github). --cursor-scm-proxy sends GitHub API calls through Cursor instead of minting a GitHub token on the VM.

mkdir -p ~/agent-state
sudo tee /etc/systemd/system/security-reviewer.service > /dev/null <<'EOF'
[Unit]
Description=Cursor Agent SDK: security-reviewer
After=network-online.target
Wants=network-online.target

[Service]
User=exedev
WorkingDirectory=/home/exedev/security-reviewer
Environment=AGENT_SERVE_NO_UPDATE_CHECK=1
ExecStart=/home/exedev/.local/bin/agent-sdk serve --dir /home/exedev/security-reviewer --mode single --host 0.0.0.0 --port 3000 --state-root /home/exedev/agent-state --allow-anonymous --allow-anonymous-cursor-github --cursor-scm-proxy
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now security-reviewer
sleep 15
journalctl -u security-reviewer -n 20 --no-pager
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/playground

The log says security-reviewer listening and GitHub auth: channel API calls route through https://api.cursor.com/v0/github-proxy, and curl prints 200.

Warning

Keep port 3000 private. Anyone who can open the playground can run the reviewer with its access to your repositories. Never point share port at it or make it public.

Read the changelog first. On the VM, update the CLI and the project's copy together, check, and restart:

npm install --global @grok/agent-sdk@0.4
cd ~/security-reviewer
npm install @grok/agent-sdk@0.4
agent-sdk validate --dir . && npm run check && agent-sdk eval --dir .
sudo systemctl restart security-reviewer
git commit -am "Update the Agent SDK"

For a new minor version, replace 0.4 with it in both commands.

Start with the service log and the project's own checks:

journalctl -u security-reviewer -n 50 --no-pager
cd ~/security-reviewer && agent-sdk validate --dir . && agent-sdk whoami

• The Cursor API key was rejected, and the service restarts every ten seconds: the key was revoked or expired. Run agent-sdk login again, then sudo systemctl restart security-reviewer.
• requires a signed-in Cursor account: the VM was never signed in. Run agent-sdk login.
• No review appears on a new pull request: check that the repository is in bot/lib/repos.ts, that GitHub is connected in Cursor for it, and that the pull request isn't a draft. agent-sdk session list --url http://127.0.0.1:3000 shows whether a session started; open it in the playground to see where it stopped.
• The first turn reports [resource_exhausted]: the model is out of capacity, or GitHub rate-limited the event; wait and reopen the pull request.
• The playground shows no agents: the service isn't running. See the log above.
• 401 on API calls through the proxy: the service is missing --allow-anonymous; compare the ExecStart line with the unit above.

Cursor's troubleshooting page covers more.