Safeguard for Small Dev Teams: Setup, Roles, CI and Daily Habits

A small dev team can run Safeguard without a dedicated security hire. Put the Safeguard CLI on every laptop, give people scoped roles, gate each pull request in CI and share one weekly triage slot. Developers fix vulnerable dependencies from the terminal with approvals, and anyone can follow the work from the desktop or phone app.

Nobody on the team has to drop the AI tools they already use. Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply. Teammates who live in a chat window can connect Claude or ChatGPT to the Safeguard MCP server and ask about the team's projects from the chat they already use.

This guide is for teams of roughly three to ten developers who share a few repositories, ship often and do not have a security lead. Commands come from the Safeguard CLI's help output and the Safeguard docs; GitHub steps come from GitHub's own documentation.

What you will have at the end

Work through the steps below over a week, one step a day, and the team will have:

• One Safeguard organization with a team, a project per repository and roles that match what each person does.
• The CLI installed on every developer laptop, signed in and passing safeguard doctor.
• A shared rule for which permission mode to use for which kind of task.
• A habit of running safeguard review before opening a pull request.
• A GitHub Actions check on every push and pull request that fails on critical findings, required by branch protection.
• A 30 minute weekly triage slot with a rotating owner.
• Desktop and phone apps that show the same live CLI sessions, so a teammate can approve or follow work away from the keyboard.

Step 1: Set up the organization and roles

The Safeguard RBAC docs describe a simple hierarchy: Organization, then Team, then Project, then Asset. The organization is the tenant boundary, where billing, SSO, the audit log and compliance settings live. A team is a group of users with shared access, and a project is a unit of ownership inside a team. One person can belong to several teams and hold a different role in each.

For a small team, keep it flat. One organization, one team, one project per repository.

The docs list these roles. Most small teams need only four of them:

The docs also describe Security Engineer, Auditor and custom roles built from a permissions matrix. Two details matter for small teams:

• Contractors. Permissions can be limited by asset labels, so a contractor who works on one service sees only that service.
• Sensitive actions. Policy changes and service token creation can require multi-party approval under Settings, Approvals. With two admins, that is a cheap way to make sure nobody loosens a gate alone.

How users are created depends on your setup. The RBAC docs describe SCIM 2.0 provisioning from an identity provider and just-in-time creation on first SSO login with a default role you configure.

Models. A tenant admin chooses which model families people may use. Safeguard's own models are Griffin, Eagle and Lion, and you can also bring your own model on your own provider account and route jobs such as chat or summaries to it. Decide this once, centrally, rather than letting every laptop drift.

Step 2: Put the CLI on every laptop

Ask each developer to run these steps on day two. It takes about ten minutes per person.

1. Install. macOS and Linux:

curl -fsSL https://cli.safeguard.sh/install | bash

Windows, in PowerShell:

irm https://cli.safeguard.sh/install.ps1 | iex

It is a single static binary with no Node, Python or JVM to install. The download page lists binaries for macOS on Apple Silicon and Intel, Linux on x86_64 and arm64, and Windows on x86_64. The installer verifies the checksum.

2. Check the install.

safeguard --version
safeguard doctor

doctor prints anything wrong with the environment, sign-in, profile, policy or tools, in order of importance. It always exits 0 when the checks ran, so have people read the output rather than trust the exit code.

3. Sign in. Run safeguard, type /login, approve in the browser. The local runner starts polling for scan jobs. /whoami confirms the account.

4. Bring existing agent setups along. Developers who already use Claude Code or Codex can run safeguard import claude or safeguard import codex to convert that setup into Safeguard configuration. By default, safeguard other-agents is on, which means Claude Code's, Codex's and OpenCode's agents, skills, custom commands, MCP servers, hooks, permissions and instructions are read below Safeguard's own. Agree as a team whether to keep that on.

5. Run a first scan. In the repository, type /scan . in the terminal, or run safeguard scan --dir . from the shell. Results land under ./output as JSON files such as vuln.json and license.json. The first run is slower while it downloads scanner tools and the vulnerability database.

Agree on permission modes

Approval modes are the one thing a team must agree on, because they decide what the assistant does without asking. /permissions in the interactive CLI offers five:

A --yolo flag approves everything. Write down that it is for throwaway sandboxes only and never on a laptop with production credentials.

Do the work properly with the Safeguard CLI

The CLI is where each developer's daily work happens. It scans code, container images and SBOMs on the developer's own machine, sends only results to the platform, and includes an assistant that writes and fixes code, with approvals.

The developer loop

A developer picks up a finding and asks in plain language:

fix the lodash CVE in this repo

The assistant reads the finding, the files and the advisory, then asks before each command or file edit. The recorded session below, made on a Mac on 21 October 2026 against a sample project called payments-api with test data, shows the full loop. It installs with the curl command (checksum verified), runs safeguard --version, opens the interactive terminal, and handles that request. You press y or n before each command. It edits package.json to lodash 4.17.21, runs npm install and npm test with approval and prints a summary with a suggested commit message. It pushes nothing. Then it shows /permissions, /model and /scan ..

Click through it at your own pace, or open it full screen.

"Pushes nothing" is what makes this work in a team. The fix becomes a normal branch and a normal pull request, reviewed by a human like any other change.

Habits worth sharing: @ attaches a file from the folder you started in, /resume continues the last session in that folder, esc interrupts a running task, and /model shows or switches the model.

Review before you open a pull request

Make this a team rule: before opening a pull request, run

safeguard review --base origin/main

review checks the working tree changes for correctness and security, and --base diffs against a git ref. It is the same check whether a person or an AI agent wrote the code. See reviewing AI-generated code before merge and checking coding agent changes with the Safeguard CLI for longer walkthroughs.

To make it hard to forget, commit a shared hook. Git runs pre-push before anything is sent, and core.hooksPath lets the team keep hooks in version control:

#!/bin/sh
# .githooks/pre-push (informational: prints the review, never blocks)
safeguard review --base origin/main >&2
exit 0

chmod +x .githooks/pre-push
git config core.hooksPath .githooks

Each developer runs the git config line once per clone. Git ignores hooks that are not executable, so commit the file with its executable bit set. Let CI do the blocking; local hooks should inform.

Batch fixes as pull requests

For a backlog of dependency updates, safeguard fix can open the pull request for you:

safeguard fix --dry-run --severity high
safeguard fix --severity high --create-pr --draft --reviewers alice,bob

--dry-run previews without touching files. --create-pr opens a pull request (as a draft with --draft), labelled security and dependencies by default, with the reviewers you name. It reads an SCM token from --scm-token or the GITHUB_TOKEN or GITLAB_TOKEN environment variable. By default it only upgrades, allows minor upgrades and skips major ones unless you pass --major-upgrades.

Using your Claude, ChatGPT or Codex plan

Each developer can bring their own Claude, ChatGPT or Codex plan into the Safeguard CLI, and Safeguard adds no extra charge for that usage; each plan's own limits and terms still apply. Use /model or the CLI docs to connect a model.

Undo is built in

Every file the assistant writes or edits is snapshotted first. Inside a session, /rewind goes back. From the shell:

safeguard checkpoints list --session <id>
safeguard checkpoints restore <checkpoint> --session <id> --dry-run

A restore can itself be undone. Files written by shell commands are not snapshotted, so git still covers lockfiles and build output.

Step 3: Gate every pull request in CI

1. Create a key. In Safeguard, under Settings, Developer, create a secret key with the scans:trigger and scans:read scopes.
2. Store it in GitHub. In the repository, open Settings, then Secrets and variables, then Actions, and add a new repository secret named SAFEGUARD_API_KEY. With the GitHub CLI: gh secret set SAFEGUARD_API_KEY.
3. Add the workflow. This is adapted from the GitHub Actions template in the Safeguard CI/CD docs; treat the docs as the source of truth:

name: safeguard
on:
  push:
  pull_request:
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - name: Safeguard scan
        env:
          SAFEGUARD_API_KEY: ${{ secrets.SAFEGUARD_API_KEY }}
          SAFEGUARD_INSTALL_DIR: ${{ runner.temp }}/safeguard
        run: |
          curl -fsSL https://cli.safeguard.sh/install | bash
          "$SAFEGUARD_INSTALL_DIR/safeguard" ci scan --wait --fail-on critical

No checkout step is needed in this mode; the docs say the scan clones the repository on Safeguard. Each push is recorded as a new version of the project. Pin the CLI version in CI with SAFEGUARD_VERSION so a release does not change your pipeline mid-sprint.

4. Make it required. In GitHub, add a branch protection rule for main that requires status checks to pass and pick the Safeguard job. GitHub's docs say all required status checks must pass before collaborators can merge into the protected branch. Turn on required pull request reviews too. Admins are exempt by default unless you enable "Do not allow bypassing the above settings", which is worth doing on a team where everyone is an admin.

Severity threshold or gate?

Two ways to fail a build:

• --fail-on critical (or high, medium, low) fails the step when the scan has a vulnerability at or above that severity. Simple and a good start.
• --fail-on-gate Release waits for a named gate's policies to be evaluated against this scan and fails the step when the gate is Failed, Error or Not evaluated. Warning and Passed let it through. Policies and gates are evaluated in the platform, not by the CLI, and this needs the gate outcomes feature on your tenant.

Start with --fail-on critical. Move to a gate once the team has agreed what should block a release and a Security Lead owns those policies.

Private code on the runner

If you do not want Safeguard to clone the repository, use local mode. It scans the checkout on the CI runner and uploads only results, with no integration needed:

safeguard ci scan --local --wait --fail-on high

Local mode needs a checkout step before it and covers dependencies (SBOM and vulnerabilities); SAST runs only in the platform mode.

A plain-language summary on each run

safeguard exec runs one assistant turn with no prompts, defaulting to strict permissions. For a read-only summary, add --restricted, which gives it a read-only tool set: no writes, no shell, no network.

safeguard exec --restricted "summarise the critical findings in this repository"

It refuses to run outside a git repository. The full CI setup, including authentication, is in running safeguard exec in CI.

Share work across desktop and phone

On a small team, the person who can approve a fix is often not at their desk. Safeguard's surfaces are built for that.

A CLI session is live: it shows in the web app, the desktop app and the phone app, and other devices can send work to it. From the desktop or phone app you can send work to a computer running the CLI. Pick the computer and folder, then approve each command and file edit.

The recorded desktop session below shows a CLI session appearing in the desktop app's conversation list. A "2 connected" indicator shows what is connected (the computer, the browser and Safeguard cloud). You ask for work on your computer, it asks which computer and folder, you pick the folder, then Approve or Deny each command and file edit. It ends with the upgrade done and tests passing.

Click through it at your own pace, or open it full screen.

Practical setup for the team:

• Desktop app 3.2.2. Windows 10 and 11 (x64 and ARM in one per-user installer, no admin rights; not yet code-signed, so verify the SHA-256 and then choose More info, Run anyway if SmartScreen warns), macOS 12 and later (Apple Silicon with an Intel build linked, signed and notarized) and Linux as an x86_64 AppImage that needs the CLI on the PATH.
• Phones. Android from Google Play, or a direct APK (1.0.2) with a SHA-256 to check for phones without Google Play or company-managed rollout. iPhone and iPad from the App Store. On the phone, a command waits for Allow once, Allow for turn or Deny.
• Keep build machines reachable. On a shared machine that should accept work from other devices, safeguard runner install keeps it reachable and starts at login. For a headless box, safeguard runner start --workspace <path>, with safeguard runner status and safeguard runner stop to check and drain it.

A weekly rhythm for a team of three to ten

Monday: 30 minute triage, rotating owner

Rotate the owner weekly. That person opens the session and asks:

which critical and high findings across our projects have a fix available?

Reachability analysis helps here: it shows whether vulnerable code is actually reachable from your application, so the team can put reachable findings first. Agree on the top three, assign each to one person, and stop. Three fixed findings a week adds up.

During the week: fix in small pull requests

Each assignee uses the developer loop above, one finding per pull request.

If the team wants the platform to open fix pull requests on its own, Safeguard offers autonomous remediation with fix PRs. It is off by default. Turn it on deliberately, for one repository first, and keep required reviews in place so a person still merges every change.

Friday: housekeeping

1. safeguard self-update --check on each laptop, then safeguard self-update. It verifies a signed manifest, keeps the previous binary as safeguard.previous and refuses to cross a major version without --allow-major. In CI, bump SAFEGUARD_VERSION on purpose instead.
2. If you ship containers, scan the release image: safeguard container-scan --image payments-api:1.8.0.
3. If a customer asks for an SBOM, generate and check it: safeguard sbom --dir . --output payments-api-sbom.json, then safeguard validate payments-api-sbom.json. validate handles CycloneDX, SPDX and VEX.

Troubleshooting

The CI step fails on pull requests from forks. GitHub does not pass secrets to workflows triggered from a forked repository, so SAFEGUARD_API_KEY is empty there. Decide how your team handles outside contributions before making the check required.

safeguard scan exits with code 2 in CI. Results were written but the vulnerability scan did not run. The CI docs say safeguard scan needs syft and grype on the PATH, or TOOLS_DIR pointing to them. safeguard ci scan in platform mode avoids this.

--fail-on-gate always fails. Check the gate name, and check that the gate's policies were evaluated. Not evaluated counts as a failure. Gate outcomes need the policies outcomes feature on your tenant.

A teammate's runner never picks up work. The runner uses outbound HTTPS and long polling. On networks that drop held connections, start it with --poll-wait 0 and set SAFEGUARD_POLL_INTERVAL (default 10 seconds).

safeguard exec will not start. It refuses outside a git repository. Run it from the checkout, or pass --skip-git-repo-check knowingly.

Results differ between two laptops. Run safeguard doctor on both and compare. Then check safeguard other-agents: if it is on for one person and off for another, they are loading different instructions and MCP servers.

Common mistakes

• Everyone is an Owner. Give Owner to one or two people and Developer to the rest. Use Viewer for non-engineers.
• No agreed permission mode. One person in Accept edits and another in Ask will produce very different sessions. Write the table above into your contributing guide.
• Using --yolo to save time. It approves everything. Sandboxes only.
• A required check that admins bypass. If every developer is a GitHub admin, enable "Do not allow bypassing the above settings" or the gate is advisory.
• Expecting the CLI to enforce policy. Policies and gates are evaluated in the platform. The CLI reports; CI flags such as --fail-on and --fail-on-gate stop the build.
• Unpinned CLI in CI. Pin with SAFEGUARD_VERSION so upgrades happen when you choose.
• Trusting checkpoints for everything. They cover files the assistant writes or edits, not what npm install or other commands write.

FAQ

Do we need a security person to run this?

No. The setup above needs one person to own CI and gates for a quarter, which the Security Lead role covers. Everyone else works as a Developer and fixes findings from their own terminal with approvals.

Can each developer keep the AI plan they already pay for?

Yes. Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply. Admins still choose which model families the tenant allows.

Does our source code leave developer laptops?

When the local runner runs platform scan jobs, source stays on the machine and only SBOMs and findings are uploaded. In CI, safeguard ci scan --local scans on the runner and uploads only results.

Can teammates use Safeguard from Claude or ChatGPT?

Yes. Connect Claude or ChatGPT to the Safeguard MCP server, and teammates can ask about findings and projects from the chat they already use. See connecting Claude to the Safeguard MCP server for the steps.

How do we stop a risky change from merging?

Make the Safeguard CI job a required status check on main, require pull request reviews, and fail the job with --fail-on critical or --fail-on-gate <name>. Then make sure admins cannot bypass the rule.

Can a contractor see only one service?

Yes. The RBAC docs say permissions can be limited by asset labels, which suits contractors who need access to one service.

What happens to a person's access when they leave?

The RBAC docs say deprovisioning revokes their sessions and user API keys. Service tokens, workload identities and organization secret keys are not affected, so rotate any of those the person handled.

Can we try it before rolling it out to everyone?

Yes. The download page lists a cloud sandbox: an isolated tenant against a seeded demo repo, free for seven days with no card. Have two developers try the full loop there before you change CI.

Try it yourself

Each teammate's first setup looks like this walkthrough: set up the runner on your own machine, pick the platform, start it, approve it with its device code, then use the same CLI to scan from the terminal.

Click through it at your own pace, or open it full screen.

Share safeguard.sh/download and the CLI docs in your team channel, and pick Monday's triage owner.

Quick check

Sources

• Safeguard CLI documentation
• Safeguard CLI interactive terminal
• Safeguard RBAC, Teams and Organizations
• Safeguard CI/CD integration
• Safeguard local runner
• Safeguard download page
• GitHub Docs: about protected branches
• GitHub Docs: using secrets in GitHub Actions
• Git hooks documentation

Last reviewed: 21 October 2026.