# Set up SecMan access for an AI agent

Follow this guide in the terminal of the machine or runtime that will use
SecMan. The user only needs to ask their AI to follow
[llms.txt](https://secman-agent.loweandfletcher.com/llms.txt). This page contains no password, API token
or permission to read secrets.

Agent service URL: `https://secman-agent.loweandfletcher.com`

## 1. Check the runtime and download the helper

Use the agent's local terminal. A web-reading tool may reject a URL or be
unable to download a script even when normal HTTPS access works. Try the
commands below through the terminal with normal certificate verification.
If the AI has no terminal or filesystem access on the target machine, explain
that it needs a local coding-agent session or help from the user.

Use the actual runtime: Windows PowerShell uses a non-exportable Windows CNG
key; Bash, WSL and Git Bash use a protected PEM file. These are separate
identities. Check existing configuration before choosing a different runtime.

### Windows: PowerShell 5.1 or PowerShell 7

Download first and inspect the script before running it. The download is
public and needs no browser login, token or special request headers.

```powershell
$env:SECRETS_MANAGER_URL = 'https://secman-agent.loweandfletcher.com'
$smDirectory = Join-Path $env:LOCALAPPDATA 'SecMan\bin'
$smPath = Join-Path $smDirectory 'sm.ps1'
$response = Invoke-WebRequest -UseBasicParsing -Uri "$env:SECRETS_MANAGER_URL/agent-tools/sm.ps1" -MaximumRedirection 0 -TimeoutSec 30
if ($response.StatusCode -ne 200 -or [string]$response.Headers['Content-Type'] -notlike 'text/plain*') {
    throw 'Expected the public PowerShell helper; inspect the HTTP response before continuing.'
}
New-Item -ItemType Directory -Path $smDirectory -Force | Out-Null
[IO.File]::WriteAllText($smPath, ([string]$response.Content).TrimStart([char]0xFEFF), [Text.UTF8Encoding]::new($true))
```

The helper is served as UTF-8 with BOM; the save above also preserves the
correct encoding. Windows PowerShell 5.1 can misread non-ASCII characters in
a UTF-8 file without BOM and report syntax errors. Do not change execution
policy or use bypass flags to fix an encoding error.

Use `& $smPath <command>` below. An explicit path also works in shells started
with `-NoProfile`; no pre-existing `sm` command or profile function is required.

### Linux, macOS, WSL or Git Bash

Bash, OpenSSL, Python 3 and curl are required. Check dependencies before
continuing, and download without executing the response as shell code.

```bash
export SECRETS_MANAGER_URL='https://secman-agent.loweandfletcher.com'
command -v bash openssl python3 curl
sm_path="$HOME/.local/bin/sm"
mkdir -p "$HOME/.local/bin"
curl --fail --show-error --silent --max-time 30 "$SECRETS_MANAGER_URL/agent-tools/sm.sh" --output "$sm_path"
bash -n "$sm_path"
chmod 700 "$sm_path"
```

Inspect the downloaded script. Use `bash "$sm_path" <command>` below.
Keep shell scripts as UTF-8 without BOM and with LF line endings.

## 2. Reuse an identity or choose its scope

Check the agent's existing service URL, helper path and scope settings first.
With the correct settings, try `& $smPath me` (PowerShell) or
`bash "$sm_path" me` (Bash). A missing `sm` command is not evidence that its
key is missing. If an existing identity works, proceed to step 4.

Before creating an identity, ask the user to choose:

- **Machine-wide:** one identity and grant set shared by tools and projects
  running as this OS user. Use the helper's default key and configuration
  locations. Do not clear existing project settings without checking them.
- **Project-scoped:** a separate identity and grant set for this project.
  Set `SECRETS_MANAGER_HOME` to the project's absolute `.secman` directory;
  on Windows also set a unique `SECRETS_MANAGER_KEY_NAME` for this project.
  Add `.secman/` to the project's `.gitignore`.

Keep the same scope settings for every later helper invocation. Windows
project keys still remain in CNG; the directory holds local configuration.
Use a descriptive name such as `<ai>-<device>-<project-or-global>`.

## 3. Request human approval

After the scope choice, run one of these commands with the chosen name:

- PowerShell: `& $smPath enroll -Name 'chosen-agent-name'`
- Bash: `bash "$sm_path" enroll --name 'chosen-agent-name'`

The official helper generates or reuses a key locally and prints a public
enrolment code and fingerprint. Show those two items to the user.

[Open the human portal](https://secman.loweandfletcher.com/web/agents).

An authorised person opens **Agents > Enroll agent**, pastes the code,
compares the fingerprint exactly, and approves the minimum required scopes.
They must also grant access to the individual secrets the agent needs.
Wait for their confirmation. Never copy a private key between machines or
ask the user for a Cloudflare service token.

## 4. Verify and make the setup available next time

Run `me`, then `skill`, through the same helper and runtime:

```powershell
& $smPath me
& $smPath skill
```

For Bash use `bash "$sm_path" me` and `bash "$sm_path" skill`.
Read the complete instructions returned by `skill` before using credentials.

Persist the non-secret service URL in the agent's launch configuration. On
Windows, set it in the current process and at user scope for future processes:

```powershell
[Environment]::SetEnvironmentVariable('SECRETS_MANAGER_URL', $env:SECRETS_MANAGER_URL, 'User')
```

Restart an already-running agent if it has not inherited the setting. Windows
user environment variables do not automatically configure WSL or containers;
configure their own runtime. Keep project scope settings in that project's
launcher or instructions rather than imposing them on every project.

Record the helper's absolute path and the selected scope in the agent's
instructions, plus a pointer to [llms.txt](https://secman-agent.loweandfletcher.com/llms.txt).
See [ongoing use](https://secman-agent.loweandfletcher.com/skill-installation.md). Do not install a
permanent copy of the full skill: `sm skill` is authoritative. At the start
of credential work, compare `sm me`'s `skill_version` with the instructions
in use and retrieve `sm skill` if their version differs or is unknown.

Setup is verified when `me` identifies the approved agent and `skill`
returns its current instructions. No secret reveal is needed to test setup.

## If a step fails

Report the failed URL or command, HTTP status where available, OS, shell
version and exact error, with credentials and private keys removed. Identify
whether the failure was downloading, saving, parsing, executing or authenticating.

| Symptom | Check and next action |
|---|---|
| AI web reader refuses the URL | Try an ordinary local terminal download. If local access also fails, report both errors. |
| DNS, timeout, proxy, certificate or download block | Confirm the exact agent hostname. Record the error for IT; retain TLS verification and organisational network controls. |
| HTML login page or redirect | The human portal URL may have been used. Use the agent service URL above; public downloads need no login. |
| 404 downloading a file | Use the exact links in `llms.txt`. Full `/skill.md` is intentionally unavailable on the public agent host; use `skill` after approval. |
| Cannot save the file | Check the target directory and write permissions; report a managed-device or antivirus block rather than disabling it. |
| PowerShell syntax error | Check `$PSVersionTable.PSVersion` and UTF-8-with-BOM encoding. Refresh an old helper from this website. |
| Scripts disabled, signature required or application-control error | Read `Get-ExecutionPolicy -List` and `$ExecutionContext.SessionState.LanguageMode`. Ask IT about the specific restriction; do not change machine policy, disable protection or use an execution-policy bypass. |
| `sm` not recognised or service URL missing | Use the helper's explicit path and set the URL in the actual runtime; a profile or user setting may not be inherited. |
| No local key or unknown/revoked agent | Confirm the original runtime and scope. Complete enrolment/approval as appropriate; do not delete or replace an existing key as a troubleshooting step. |
| Invalid or expired signature | Check the system clock and that the helper is current; retry once. |
| Approved identity but no secrets listed | An administrator must grant the required individual secrets. Enrolment alone grants no secret access. |

Never print, log, commit or place revealed secret values in prompts, URLs or
persistent environment files. Private keys stay on the machine where they
were created.