# AGENTS.md

This file tells humans and AI coding agents how to use AgentSecure in this repository.

Agents may read this file before taking action. Do not paste real credentials, tokens, raw `.env` contents, private
keys, customer data, prompts, or request bodies into this file.

## Start

Run the local setup flow:

```bash
agentsecure start
```

This imports real `.env` values into the local AgentSecure vault, writes a restorable `.env` backup, rewrites `.env`
with safe placeholders, and prepares MCP guidance for supported agents.

## What Agents Can See

Agents should expect placeholders in repo files:

```dotenv
OPENAI_API_KEY=${OPENAI_API_KEY}
STRIPE_SECRET_KEY=${STRIPE_SECRET_KEY}
GITHUB_TOKEN=${GITHUB_TOKEN}
```

The placeholder names are safe to read. The real values stay in the local vault.

## Codex MCP Setup

When Codex needs secret-backed API calls, add the AgentSecure MCP server:

```bash
codex mcp add agentsecure -- agentsecure --config ./agentsecure.json mcp serve
```

Use the MCP broker instead of asking the human to paste real secrets into the prompt.

## Main MCP Tool

Use `agentsecure.http.request` for approved API calls that require a secret:

```yaml
tool: agentsecure.http.request
url: https://api.example.com/v1/resource
auth: ${API_KEY}
purpose: short reason for the request
```

AgentSecure resolves `${API_KEY}` from the local vault only for approved destinations.

## Approved Destinations

Only send placeholders to destinations approved by the developer or team policy.

```yaml
approved_destinations:
  api.openai.com:
    secrets:
      - OPENAI_API_KEY
  api.stripe.com:
    secrets:
      - STRIPE_SECRET_KEY
```

If a destination is not approved, ask the human for approval. Include the exact URL, placeholder name, and reason for
the request.

## Restore

If a human needs the original local `.env`, use the AgentSecure restore flow:

```bash
agentsecure env restore
```

## Audit

Audit records may include:

- placeholder name
- approved destination
- MCP tool name
- timestamp and repo context
- whether the request was sent

Audit records must not include real secret values, raw `.env` files, prompts, request bodies, private keys, or customer
data.