Safeguard for Agencies and Consultancies: Client Work, Step by Step

Agencies and consultancies can use Safeguard to run security work for many clients from one toolkit. Keep one folder per client, scan and fix dependencies with the Safeguard CLI on your own machine, approve every command, and hand each client a validated SBOM and findings report. Only results go to the platform; client source stays local.

If you build or maintain software for other people, you already juggle several stacks, several CI systems and several sets of rules about what may leave the building. You also get asked, near the end of a project, "can you send us an SBOM?" or "were there any critical vulnerabilities at handover?" This guide shows a routine that answers both questions without a separate tool per client.

Before the steps, the point agency leads ask about first. 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. Your team can also connect Claude or ChatGPT to the Safeguard MCP server and ask about findings from the chat they already use.

What you will have at the end

After working through this guide once, you will have:

1. The Safeguard CLI on every engineer's machine, signed in, with a shared understanding of which permission mode to use when.
2. A folder layout that keeps each client's code, sessions and scan output apart.
3. A fix routine: the assistant reads a finding, edits the manifest, asks before running install and tests, and leaves the commit to your engineer.
4. A handover pack per client: SPDX SBOM, vulnerability and licence results as JSON, a validation report, and container and infrastructure checks where the client ships them.
5. A CI step you can drop into a client's pipeline that scans on their runner and uploads results only, never source.
6. The desktop and phone apps set up so a lead can approve work on an engineer's machine, or their own, from wherever they are.

Do the work properly with the Safeguard CLI

The Safeguard CLI scans code, container images and SBOMs on your own machine, sends only the results to the platform, and includes an assistant that can fix what it finds. It writes code, not only scans. For an agency, that matters for one reason above the rest: the engineer doing the client's feature work and the tool checking the client's dependencies are in the same terminal, looking at the same files.

Install

The CLI is a single static binary with no Node, Python or JVM to install. That is useful when one engineer moves between a Java client in the morning and a Node client in the afternoon. It runs on macOS, Linux and Windows, x86_64 or arm64 (Windows is x86_64 only).

# macOS and Linux
curl -fsSL https://cli.safeguard.sh/install | bash
safeguard --version

# Windows PowerShell
irm https://cli.safeguard.sh/install.ps1 | iex
safeguard --version

Both scripts verify the checksum. If a client's policy requires you to check binaries by hand, the download page publishes SHA256SUMS for each direct archive. safeguard doctor checks an installation and prints what is wrong without changing anything; ask new starters to run it on day one.

First session in a client folder

The CLI keeps context per folder, so start it from the client's project:

cd ~/clients/acme/web
safeguard

Type /login to sign in through the browser and /scan . to scan the folder. Then ask in plain language: "how many critical vulns do we have", "which findings come from packages we added this quarter". @ attaches a file from the folder you started in, and /resume picks up the last session in that folder. Because sessions are tied to the folder, Monday's work on Acme does not bleed into Tuesday's work on another client.

Writing and fixing code

Ask "fix the lodash CVE in this repo" and the assistant reads the finding, the files and the advisory, edits package.json to lodash 4.17.21, then asks before running npm install and npm test (press y or n). It finishes with a summary and a suggested commit message, and pushes nothing. Your engineer reviews the diff and commits on the client's branch under the client's rules.

It works the same way for everyday client tasks, with approval for anything that changes files or runs commands: "add input validation to the signup handler and a test for it", "find where we read the payment provider's webhook secret from config", "run the integration tests for the orders module". If an edit goes wrong, /rewind restores the files the agent changed, and safeguard checkpoints lists checkpoints and previews a restore with --dry-run. Files written by shell commands are not snapshotted, so commit before large changes.

Using your Claude or ChatGPT plan

/model shows or switches the AI model. Engineers who already have a Claude, ChatGPT or Codex plan can use it inside the CLI with no extra Safeguard charge for that usage; their plan's own limits and terms still apply. Check the CLI docs or /model for connecting a model. If a client's contract restricts which AI services may see their code, /model is also where you confirm what a session is using before you start.

Teams moving over from other agents can run safeguard import claude or safeguard import codex to convert an existing setup into Safeguard configuration. safeguard other-agents, on by default, also reads Claude Code, Codex and OpenCode configuration below Safeguard's own, so a client repository's existing agent instructions are picked up.

Approvals

/permissions sets the approval mode for the session. Agree a default as a team:

The --yolo flag approves everything. Keep it for throwaway sandboxes only, never for a client checkout.

CI with safeguard exec

safeguard exec "summarise the critical findings in this repository" runs one assistant turn without prompting and exits. The default mode is strict, so nothing is asked and anything the policy file has not pre-approved is denied. It refuses to run outside a git repository unless you pass --skip-git-repo-check. Our guide to safeguard exec in CI has full pipeline examples.

This is the recorded CLI session, end to end, on a sample project.

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

Keep each client separate, step by step

Most agency mistakes with security tooling are mix-ups: the wrong client's report in the wrong email, a scan output overwritten, a session carrying context from one codebase into another. A boring folder layout prevents nearly all of it.

Step 1: one folder per client, one per deliverable

~/clients/
  acme/
    web/            client repository
    api/            client repository
  northwind/
    mobile-backend/
~/deliverables/
  acme/2026-10/
  northwind/2026-10/

Start every session from inside the client repository. Never start it from ~/clients, because @ and the assistant's file tools work from the folder you started in.

Step 2: scan with an explicit output folder

safeguard scan --dir ~/clients/acme/web --output ~/deliverables/acme/2026-10/web

safeguard scan builds an SBOM and matches it against vulnerability databases. Without --output, results go to ./output in the current folder, which is how reports end up in the wrong place. Pass it every time.

If the client publishes internal packages under its own scope, tell the scanner so they are treated as the client's own code rather than third party packages:

safeguard scan --dir ~/clients/acme/web --org-namespace @acme --output ~/deliverables/acme/2026-10/web

Step 3: local-only checks when nothing may leave the machine

Some clients will not allow even results to be uploaded until a contract is signed. safeguard findings runs one scanner on your machine and prints a normalized list. Nothing is uploaded and no project is registered, even when the CLI is signed in:

safeguard findings sca --dir . --json > ~/deliverables/acme/2026-10/web-sca.jsonl
safeguard findings iac --dir ./infra
safeguard findings container --image acme-web:rc --json

--artifacts keeps the scanner's output, including the SBOM, in a folder you choose.

Step 4: read-only audits with exec

For a pre-sales audit or a due diligence review, you often want the assistant's reading of a codebase without any chance of it changing something. safeguard exec has flags for exactly that:

cd ~/clients/northwind/mobile-backend
safeguard exec --restricted --private "summarise the critical findings in this repository"

--restricted gives the run a read-only tool set: no writes, no shell, no network. --private keeps the run out of the session store. -C runs in another directory, and --output-format json gives you machine readable output for your own reporting templates.

Step 5: name projects after the client in CI

When you add a scan to a client pipeline, name the Safeguard project explicitly so it never lands on the wrong one:

safeguard ci scan --local --wait --fail-on high --project acme-web

More on that pipeline in the handover section below.

Build the handover pack

Clients increasingly ask for evidence, not just a working app. Here is a pack you can produce in a few minutes at each milestone.

Step 1: SBOM

cd ~/clients/acme/web
safeguard sbom --dir . --output ~/deliverables/acme/2026-10/acme-web-sbom.spdx.json

safeguard sbom writes SPDX JSON. SPDX is an open standard for software bill of materials information, hosted by the Linux Foundation and recognised as ISO/IEC 5962:2021, so the client's own tools can read it.

Step 2: vulnerability and licence results

The scan from the previous section already wrote vuln.json, license.json and other files to the output folder. Put them in the pack as they are; they are the raw evidence.

Step 3: container image, if the client ships one

docker build -t acme-web:rc .
safeguard container-scan --image acme-web:rc --output ~/deliverables/acme/2026-10/image

docker build is an alias of docker buildx build, and -t names the image. safeguard container-scan generates an SBOM for the image and runs the vulnerability scan; its output is identical to safeguard scan --image. For a quick look without upload, use safeguard findings container --image acme-web:rc. For an SBOM of the image alone, run safeguard sbom --image acme-web:rc.

Step 4: infrastructure code, if you wrote it

safeguard iac-scan --target ./infra

safeguard iac-scan looks for misconfigurations in Terraform, CloudFormation, Helm, Kubernetes manifests, Dockerfiles and ARM or Bicep templates. For a check that uploads nothing, use safeguard findings iac --dir ./infra instead.

Step 5: validate before you send

safeguard validate ~/deliverables/acme/2026-10 --recursive --strict -o ~/deliverables/acme/2026-10/validate-report.json

safeguard validate checks CycloneDX, SPDX and VEX documents (CSAF and OpenVEX). --strict treats warnings as errors. If the client sent you SBOMs from their other suppliers, validate those too before you rely on them.

Step 6: review the final diff

Before the release branch goes to the client, review what changed since the last handover:

safeguard review --base release-2026-09

safeguard review reviews changes for correctness and security, and --base diffs against a git ref. This is also the step that catches what any coding agent changed, whichever one your engineers used. Our post on reviewing AI generated code before merge goes deeper.

Step 7: automate it in the client's pipeline

For GitHub Actions, create a Safeguard secret key under Settings, Secret Keys, with the scans:trigger scope (plus scans:read for --wait). In the client's repository, go to Settings, Secrets and variables, Actions and add it as SAFEGUARD_API_KEY. If the client uses deployment environments, an environment secret works too; in an organisation repository that needs admin access.

name: safeguard
on:
  push:
    branches: [main]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install the Safeguard CLI
        run: curl -fsSL https://cli.safeguard.sh/install | bash
      - name: Scan this commit
        env:
          SAFEGUARD_API_KEY: ${{ secrets.SAFEGUARD_API_KEY }}
        run: |
          safeguard ci scan --local --wait --fail-on high --project acme-web
          safeguard sbom --dir . --output acme-web-sbom.spdx.json
      - name: Keep the SBOM with the run
        uses: actions/upload-artifact@v4
        with:
          name: acme-web-sbom
          path: acme-web-sbom.spdx.json

With --local, the scan runs on the CI runner and only results are uploaded, never source. It needs no integration and works for private and self-hosted repositories, which is often the only option when you work inside a client's GitHub organisation. In that mode it covers dependencies (SBOM and vulnerabilities). If the step cannot find safeguard, add the folder the install script reports to PATH. ci scan also supports Jenkins, GitLab CI, Bitbucket Pipelines, Azure Pipelines, CircleCI and anything else that can run a command.

--fail-on-gate can fail the step on a named gate. Policies and gates are evaluated in the platform, not by the CLI, so agree them with the client before you switch that on.

Work across desktop and phone

Leads in an agency are rarely at the keyboard where the work is happening. A Safeguard CLI session is live: it shows in the web app, the desktop app and the phone app, and those devices can send work to it. Start in the terminal, continue on the desktop, check findings on your phone.

The desktop app

The desktop app (3.2.2 on the download page) runs on Windows 10 and 11 (one installer for x64 and ARM, per user, no admin rights), macOS 12 and later (Apple Silicon build, signed and notarized, with an Intel build linked) and Linux as an x86_64 AppImage. The Windows build is not yet code-signed, so SmartScreen may warn: verify the SHA-256 first, then choose More info, Run anyway. Many client laptops are locked down, so the no-admin installer helps. The Linux AppImage needs the CLI installed and on PATH.

In the desktop app, CLI sessions appear in the conversation list. When you ask for work on your computer, it asks which computer and which folder; pick the client folder, then Approve or Deny each command and file edit. Our desktop app guide covers setup.

Here is a recorded desktop session that ends with the upgrade done and the tests passing.

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

The phone

The iOS app is on the App Store for iPhone and iPad; the Android app is on Google Play, with a direct APK for phones without Google Play or for company-managed rollout. The same conversations appear on the phone. "Work on my computer" picks a machine running the CLI and a folder, and each command waits for Allow once, Allow for turn or Deny. For a lead, that means a release fix can go ahead from a client meeting without anyone sharing a screen.

You can also send things between devices from the terminal: safeguard devices lists your signed-in devices, safeguard send --to my-phone --link https://example.com/acme/pull/91 sends a link, and safeguard inbox shows what your other devices sent to the CLI.

Clients who already use Claude or ChatGPT

Some clients live in Claude or ChatGPT. Connect either one to the Safeguard MCP server and they can ask about their own findings from the chat they already use. Claude adds it from the connector directory with OAuth or by URL; ChatGPT installs it from the plugin directory or imports the OpenAPI schema. Any MCP client can use https://mcp.safeguard.sh/mcp. See our guides for Claude and ChatGPT.

Troubleshooting and common mistakes

Troubleshooting

A report has another client's packages in it. The scan ran from the wrong folder or wrote to a shared ./output. Rerun with --dir and --output pointing at the client's folders.

safeguard exec will not start in a client's export. Zipped exports have no git history, and exec refuses to run outside a git repository. Run git init and commit the export first, or accept the risk with --skip-git-repo-check for a read-only --restricted run.

The CI scan fails with an authentication error. Check the secret name, the key's scopes, and whether the run came from a fork; GitHub does not pass secrets to workflows triggered from forked repositories.

The desktop app does not show the engineer's machine. The CLI must be running and signed in on that machine. Run safeguard doctor there.

npm ci fails after a fix. npm ci requires package-lock.json to match package.json and exits with an error rather than updating the lock. Run the install the assistant proposes, commit the updated lockfile, then rerun CI.

Common mistakes

1. One long session across clients. Start from each client's folder so /resume and @ stay scoped to that client.
2. Leaving --output off. Every report then lands in ./output and the next scan overwrites it.
3. Using --yolo on a client checkout. It approves everything. Sandboxes only.
4. Letting the assistant push to a client's repository. It does not push in the recorded session. Keep the commit and push with a named engineer.
5. Sending an SBOM you did not validate. Run safeguard validate --strict on the pack first.
6. Promising a gate result from the CLI alone. Policies and gates are evaluated in the platform. Agree the gate with the client, then use --fail-on-gate.

FAQ

Can engineers use the Claude or ChatGPT plans they already have?

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. See the CLI docs or /model for connecting a model. Your team and your clients can also connect Claude or ChatGPT to the Safeguard MCP server and use Safeguard from the chat.

Does client source code leave our machines?

The CLI scans locally and sends only results to the platform. When the local runner runs platform scan jobs, only SBOMs and findings are uploaded, never source. safeguard findings uploads nothing at all, and ci scan --local uploads results only.

Can we use it for a read-only audit before a contract is signed?

Yes. Use safeguard findings for local-only scanner results and safeguard exec --restricted --private for a read-only assistant summary. Plan mode in the interactive terminal also reads and plans only.

Which stacks does it cover?

The scan builds an SBOM from the folder or image and matches it against vulnerability databases, so it is not tied to one language. The assistant runs the project's own commands, such as npm test, mvn test, gradle test, pytest or go test ./..., asking first.

What format is the SBOM?

safeguard sbom writes SPDX JSON. safeguard validate checks SPDX, CycloneDX and VEX documents, so you can also check files a client receives from other suppliers.

Can it open fix pull requests on a client repository?

safeguard fix --create-pr --draft opens a draft PR with dependency fixes; preview first with safeguard fix --dry-run. On the platform, autonomous remediation with fix PRs is available and off by default.

Where do we install it?

Install the CLI from safeguard.sh/download on macOS, Linux or Windows. The same page has the desktop app, the iOS and Android apps, IDE extensions for VS Code, JetBrains and Open VSX editors, a Chrome browser extension, and cloud options with nothing to install, including a cloud sandbox tenant on a seeded demo repo, free for seven days with no card.

Try it yourself

This walkthrough sets 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.

Install from safeguard.sh/download, and keep the CLI docs open for the first client folder you set up.

Quick check

Sources

• Safeguard CLI documentation
• Safeguard downloads
• GitHub Docs: Using secrets in GitHub Actions
• GitHub Docs: Using secrets in a workflow step
• GitHub Docs: Storing and sharing data from a workflow
• GitHub Docs: Events that trigger workflows
• Docker Docs: docker buildx build
• npm Docs: npm ci
• SPDX overview
• CycloneDX specification overview

Last reviewed: 21 October 2026.