Confidant

Receive secrets from humans securely — no chat exposure, no copy-paste, no history leaks.

🚨 CRITICAL FLOW — Read This First

This is a human-in-the-loop process. You CANNOT retrieve the secret yourself.

1. 1. Run the script → you get a secure URL
2. SEND the URL to the user in chat ← THIS IS MANDATORY
3. WAIT for the user to open the URL in their browser and submit the secret
4. The script handles the rest (receives, saves to disk, confirms)

CODEBLOCK0

🔧 Setup (once per environment)

Run this once to install the CLI globally (avoids slow npx calls):

CODEBLOCK1

{skill} is the absolute path to the directory containing this SKILL.md file. Agents can resolve it at runtime:
CODEBLOCK2

⚡ Quick Start

You need an API key from the user? One command:

CODEBLOCK3

The script handles everything:

• - ✅ Starts server if not running (or reuses existing one)
• ✅ Creates a secure request with web form
• ✅ Detects existing tunnels (ngrok or localtunnel)
• ✅ Returns the URL to share with the user
• ✅ Polls until the secret is submitted
• ✅ Saves to ~/.config/openai/api_key (chmod 600) and exits

If the user is remote (not on the same network), add --tunnel:

CODEBLOCK4

This starts a localtunnel automatically (no account needed) and returns a public URL.

Output example:

CODEBLOCK5

Share the URL → user opens it → submits the secret → script saves to disk → done.

Without --service or --save, the script still polls and prints the secret to stdout (useful for piping or manual inspection).

Scripts

request-secret.sh — Request, receive, and save a secret (recommended)

CODEBLOCK6

Flag	Description
INLINECODE8	Description shown on the web form (required)
INLINECODE9

Auto-save to ~/.config/<name>/api_key |
| --save <path> | Auto-save to explicit file path |
| --env <varname> | Set env var (requires --service or --save) |
| --tunnel | Start localtunnel if no tunnel detected (for remote users) |
| --port <number> | Server port (default: 3000) |
| --timeout <secs> | Max wait for startup (default: 30) |
| --json | Output JSON instead of human-readable text |

check-server.sh — Server diagnostics (no side effects)

CODEBLOCK7

Reports server status, port, PID, and tunnel state (ngrok or localtunnel).

⏱ Long-Running Process — Use tmux

The request-secret.sh script blocks until the secret is submitted (it polls continuously). Most agent runtimes (including OpenClaw's exec tool) impose execution timeouts that will kill the process before the user has time to submit.

Always run Confidant inside a tmux session:

CODEBLOCK8

Why not exec? Agent runtimes typically kill processes after 30-60s. Since the script waits for human input (which can take minutes), it gets SIGKILL before completion. tmux keeps the process alive independently.

If your agent platform supports long-running background processes without timeouts, exec with request-secret.sh works fine. But when in doubt, use tmux.

Rules for Agents

1. 1. NEVER ask users to paste secrets in chat — always use this skill
2. NEVER reveal received secrets in chat — not even partially
3. NEVER curl the Confidant API directly — use the scripts
4. NEVER kill an existing server to start a new one
5. NEVER try to expose the port directly (public IP, firewall rules, etc.) — use --tunnel instead
6. ALWAYS share the URL with the user in chat — this is the entire point of the tool
7. ALWAYS wait for the script to finish — it polls automatically and saves/outputs the secret; do not try to retrieve it yourself
8. Use --tunnel when the user is remote (not on the same machine/network)
9. Prefer --service for API keys — cleanest convention
10. After receiving: confirm success, use the secret silently

Exit Codes (Scripts)

Agents can branch on exit codes for programmatic error handling:

Code	Constant	Meaning
INLINECODE29	—	Success — secret received (saved to disk or printed to stdout)
INLINECODE30

MISSING_LABEL | --label flag not provided |
| 2 | MISSING_DEPENDENCY | curl, jq, npm, or confidant not installed |
| 3 | SERVER_TIMEOUT / SERVER_CRASH | Server failed to start or died during startup |
| 4 | REQUEST_FAILED | API returned empty URL — request not created |
| ≠0 | (from CLI) | confidant request --poll failed (expired, not found, etc.) |

With --json, all errors include a "code" field for programmatic branching:

CODEBLOCK9

Example Agent Conversation

This is what the interaction should look like:

CODEBLOCK10

⚠️ Notice: the agent SENDS the URL and WAITS. It does NOT try to access the URL itself.

How It Works

1. 1. Script starts a Confidant server (or reuses existing one on port 3000)
2. Creates a request via the API with a unique ID and secure web form
3. Optionally starts a localtunnel for public access (or detects existing ngrok/localtunnel)
4. Prints the URL — agent shares it with the user in chat
5. Delegates polling to confidant request --poll which blocks until the secret is submitted
6. With --service or --save: secret is saved to disk (chmod 600), then destroyed on server
7. Without --service/--save: secret is printed to stdout, then destroyed on server

Tunnel Options

Provider	Account needed	How
localtunnel (default)	No	INLINECODE54 flag or INLINECODE55
ngrok

Yes (free tier) | Auto-detected if running on same port |

The script auto-detects both. If neither is running and --tunnel is passed, it starts localtunnel.

Advanced: Direct CLI Usage

For edge cases not covered by the scripts:

CODEBLOCK11

If confidant is not installed globally, run bash {skill}/scripts/setup.sh first, or prefix with npx @aiconnect/confidant.

⚠️ Only use direct CLI if the scripts don't cover your case.