Starting and Stopping the Proxy

The AgentSecrets Credential Proxy runs locally on your machine, acting as a secure gateway between your AI agents or application code and third-party APIs. It resolves credentials from the OS Keychain and injects them at the HTTP network layer so your code never holds raw secrets.

Starting the Proxy

To start the proxy, execute proxy start from a directory linked to an active AgentSecrets project:

agentsecrets proxy start

Lifecycle Initialization Sequence

When you start the proxy, the Go runtime executes the following sequence:

1. Project Context Resolution: Reads .agentsecrets/project.json in the current working directory (or uses AGENTSECRETS_PROJECT_ID).
2. Attestation & Keychain Binding: Connects to the local OS Keychain via the keychain-auth daemon to enable hardware-backed decryption.
3. Session Token Generation: Generates an ephemeral cryptographically random session token, writes it to the local keychain, and binds it to X-AS-Session-Token for local caller validation.
4. PID Tracking: Writes the process ID to .agentsecrets/proxy.pid to support proxy status and proxy stop.
5. Foreground Execution & Stream Binding: Starts the HTTP server on http://localhost:8765/proxy, running directly in your terminal to display real-time events and handle interactive approval prompts.

agentsecrets proxy start runs as an active foreground process. Press Ctrl+C at any time to initiate a clean, graceful shutdown.

Specifying a Custom Port

By default, the proxy listens on port 8765. If port 8765 is occupied, you can specify a custom port.

Option 1: Using the --port Flag

agentsecrets proxy start --port 9000

Option 2: Using the AGENTSECRETS_PORT Environment Variable

export AGENTSECRETS_PORT=9000
agentsecrets proxy start

When using a custom port, configure your client or SDK to route requests through the new address:

import agentsecrets
client = agentsecrets.Client(port=9000)

Checking Proxy Status

To inspect whether the proxy is currently running, verify its port, and inspect synchronization health, run:

agentsecrets proxy status

Output:

Project:             payments-service (proj_02abc...)
Port:                8765
Proxy status:        running (PID 49821)
Last sync:           2m 14s ago
Revoked IDs:         0
Audit DB:            ~/.agentsecrets/audit.db
Size:                40960 bytes
Last modified:       2026-09-02T22:15:00Z

What proxy status Verifies

1. PID File Liveness: Reads .agentsecrets/proxy.pid and verifies that the process is actively executing using operating system kernel signals.
2. Health Endpoint Probe: Queries http://localhost:<port>/health to check uptime, last sync timestamp, and active revocation lists.
3. Audit Log Integrity: Verifies the location and byte size of the local SQLite audit trail.

Stopping the Proxy

To shut down a running proxy daemon from another terminal window or automation script, run:

agentsecrets proxy stop

Graceful Teardown Sequence

1. SIGTERM Signal: Sends SIGTERM to the PID recorded in .agentsecrets/proxy.pid.
2. Drain Timeout: Waits up to 5 seconds for in-flight HTTP requests and tamper-proof audit events to flush cleanly to disk.
3. Emergency Escalation: If the process fails to terminate within 5 seconds, issues SIGKILL to force termination.
4. PID File Cleanup: Removes the PID lock file.

Running as a Background System Service

Because agentsecrets proxy start runs natively as a managed foreground process, it integrates cleanly with production service managers (systemd, launchd, PM2, Docker).

A background service must either specifyWorkingDirectory pointing to a directory with .agentsecrets/project.json, or export AGENTSECRETS_PROJECT_ID.

1Linux (systemd)

[Unit]
Description=AgentSecrets Credential Proxy Daemon
After=network.target

[Service]
Type=simple
User=developer
WorkingDirectory=/home/developer/my-project
Environment=AGENTSECRETS_PROJECT_ID=proj_abc123
Environment=AGENTSECRETS_PORT=8765
ExecStart=/usr/local/bin/agentsecrets proxy start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable agentsecrets
sudo systemctl start agentsecrets

2macOS (launchd)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.agentsecrets.proxy</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/agentsecrets</string>
        <string>proxy</string>
        <string>start</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/developer/my-project</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>EnvironmentVariables</key>
    <dict>
        <key>AGENTSECRETS_PORT</key>
        <string>8765</string>
    </dict>
</dict>
</plist>

launchctl load -w ~/Library/LaunchAgents/com.agentsecrets.proxy.plist

3Process Managers (Node.js PM2)

module.exports = {
  apps: [
    {
      name: "agentsecrets-proxy",
      script: "agentsecrets",
      args: "proxy start",
      cwd: "/path/to/my-project",
      autorestart: true,
      env: {
        AGENTSECRETS_PORT: "8765",
        AGENTSECRETS_PROJECT_ID: "proj_abc123"
      }
    }
  ]
};

pm2 start ecosystem.config.js