# Connect your AI agent

> One line for Claude Code, Codex, Copilot or Cursor: the agent installs the ScanSuite skill and connects to your server.

Source: https://scansuite.eu/documentation/agent-setup
Last reviewed: 2026-10-19

These are the official ScanSuite instructions for connecting an AI coding agent (Claude Code, OpenAI Codex, GitHub Copilot, Cursor and others) to a ScanSuite Teams server. They are published at `https://scansuite.eu/documentation/agent-setup.md`, so an agent can check where they come from before following them. The page is written to the agent; a person can read it to see exactly what the agent will do.

Connect your AI agent to ScanSuite

Paste this line into Claude Code, Codex, Copilot, Cursor or another coding agent. It installs the ScanSuite skill and connects it to your server, and stops for the steps only you can do.

```
Set up ScanSuite for me: fetch and follow https://scansuite.eu/documentation/agent-setup.md
```

[What the agent will do](https://scansuite.eu/documentation/agent-setup)

## Rules for the agent

- Run every command below yourself, except the steps marked **A person does this step**. For those, stop, tell the user what to do, and wait until they confirm.
- Never run a command that waits for interactive input.
- Never read, print or copy the API token. It lives in a file that the person writes; the skill reads it from there. Never ask the user to paste the token into the conversation.
- Every command here is safe to run again on a machine where the setup already happened.
- Report only what you verified (see [Report the result](https://scansuite.eu/documentation/agent-setup#report)).

## 1. Server and team

You need two values. Take them from the user's message (it may name both), from the environment, or ask the user.

| Variable | Value | Where it comes from |
|---|---|---|
| SCANSUITE_URL | The address of the ScanSuite server, for example https://scansuite.example.com | The address the user signs in at |
| SCANSUITE_TEAM | The team slug, for example appsec | Teams → People: the new-token dialog shows it in a row of its own |

Check that the server answers:

```bash
curl -fsS "$SCANSUITE_URL/ci/version"
```

Expected: a short JSON document with the client version the server publishes. If it fails, stop and report that the server cannot be reached from this machine (a wrong address, a VPN that is not connected, or a private certificate: see [CI/CD and automation](https://scansuite.eu/documentation/reference/cicd) for `SCANSUITE_CA_BUNDLE`).

## 2. Prerequisites

| Tool | Check | Notes |
|---|---|---|
| bash and curl | bash --version && curl --version | Required |
| python3 | python3 --version | Required by the skill's helper scripts |
| Docker, or nothing else | docker version | Optional. Without Docker, the skill downloads the client from the server and checks its SHA-256 |

If bash, curl or python3 is missing, stop and report it. On Windows, run everything in WSL or Git Bash.

## 3. Install the ScanSuite skill

The skill is published in the public repository [github.com/cepxeo/scansuite-ci](https://github.com/cepxeo/scansuite-ci). Use the section for your agent.

### Claude Code

```bash
claude plugin marketplace add cepxeo/scansuite-ci
claude plugin install scansuite@scansuite-ci
```

Verify:

```bash
claude plugin list | grep -A2 "scansuite@scansuite-ci"
```

Expect the plugin listed as enabled. If it is listed but disabled, run `claude plugin enable scansuite@scansuite-ci`.

> **A person does this step:** Run /reload-plugins inside Claude Code so the skill loads in this session, then tell the agent it is done.

### OpenAI Codex, GitHub Copilot, Cursor and other agents

A skill is a folder with a `SKILL.md` file. Copy the folder to where your agent loads skills from:

```bash
rm -rf /tmp/scansuite-ci && git clone --depth 1 https://github.com/cepxeo/scansuite-ci /tmp/scansuite-ci
mkdir -p <SKILLS_DIR> && rm -rf <SKILLS_DIR>/scansuite
cp -r /tmp/scansuite-ci/plugins/scansuite/skills/scansuite <SKILLS_DIR>/scansuite
```

| Agent | <SKILLS_DIR> |
|---|---|
| OpenAI Codex | ~/.agents/skills (personal) or .agents/skills in the project |
| GitHub Copilot | ~/.copilot/skills (personal) or .github/skills in the repository |
| Agents that read .agents/skills | .agents/skills in the project; one copy serves Codex and Copilot |
| Any other agent | The skills folder named in your agent's documentation. If your agent cannot load skills, read SKILL.md and follow it directly. |

Verify: `test -f <SKILLS_DIR>/scansuite/SKILL.md && echo ok` prints `ok`. Some agents only load new skills after a restart; if yours does, say so in the report.

## 4. Connect to the server

The skill reads the API token from `~/.scansuite-token` (or the file `SCANSUITE_TOKEN_FILE` names). First check whether it is already there, without reading it:

```bash
test -r ~/.scansuite-token && ls -l ~/.scansuite-token | cut -c1-10
```

If it prints `-rw-------`, go to step 5. If the file is missing, a person creates the token:

> **A person does this step:** Create a token for the agent and save it to a file in your own terminal, not in the agent's chat:
>
> 1. In ScanSuite open **Teams** → **People** → **Automation and API tokens**. Create a service account (role **Operator**), then a token for it with the **CI pipeline** preset. To let the agent triage findings too, choose **Custom** and add **Change findings**. Only a team admin can do this.
> 2. Copy the token from the dialog (it is shown once) and run, in your own terminal: `printf '%s' '<TOKEN>' > ~/.scansuite-token && chmod 600 ~/.scansuite-token`
> 3. Tell the agent the file is in place.

If the file exists but other users can read it (anything other than `-rw-------`), run `chmod 600 ~/.scansuite-token`.

## 5. Verify end to end

From the skill folder, with `SCANSUITE_URL` and `SCANSUITE_TEAM` set:

```bash
bash scripts/preflight.sh
bash scripts/api.sh GET /products
```

The preflight prints the client and server versions, the token's role, permissions and expiry, and every scanner with the ones this team cannot run marked `NOT AVAILABLE` and why. The second command lists the team's products. **An empty list is a pass**: the connection works and the team has no products yet.

| Result | What it means |
|---|---|
| 401, token refused | The token is wrong, expired or revoked, or belongs to another team. The preflight prints which. A person creates a new one (step 4). |
| 403, permission missing | The token works but lacks the permission the call needs; the error names it. Report it; do not work around it. |
| Could not reach the server | Re-check step 1. |
| A scanner is NOT AVAILABLE | Not a setup failure. Tell the user which scanners they can use and what a team admin would have to set up for the others. |

## No user in the loop

In CI, a scheduled job or a headless agent run, nobody can do the person steps. Then:

1. Take the token from the CI system's secret store, never from a file you write. Point `SCANSUITE_TOKEN_FILE` at a secret the CI system mounts as a file (for example a GitLab variable of type *File*), or run the client directly with `SCANSUITE_TOKEN` set. Never print it. If neither is set, stop and report that the token is missing.
2. Install the skill as in step 3 (skip `/reload-plugins`: the plugin loads when the agent starts).
3. Run step 5 and write the result banner to the job log.

For pipelines without an agent, use the client directly: see [CI/CD and automation](https://scansuite.eu/documentation/reference/cicd).

## Report the result

Report what you verified, and nothing more:

*Result*

```
┌─ ScanSuite agent setup ───────────────────────────────────────┐
│  ✓ ScanSuite skill    installed, loads in this agent          │
│  ✓ Server             https://scansuite.example.com reachable │
│  ⚠ Token              needs a person: create it (step 4)      │
│  ✗ End to end         not run yet                             │
└───────────────────────────────────────────────────────────────┘
```

Use `✓` for verified, `⚠` for waiting on a person, `✗` for failed or not run. After the banner, give the next action for every line that is not `✓`.

## What to ask next

Once every line is `✓`, suggest one of these to the user:

| Prompt | What runs |
|---|---|
| Scan this repository and tell me what is reachable. | An AI SAST scan of the working directory |
| Check https://staging.example.com for web vulnerabilities. | A DAST scan; the team must allow the target |
| Show me the open critical findings of the payments product. | Reads results through the team API |

The full explanation for people, including what the skill asks before intrusive or costly scans, is in [Working with AI agents](https://scansuite.eu/documentation/reference/agent-skill).