> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Go Client Agent

> Install the KnoxCall Go agent next to your app to route outbound API calls through KnoxCall with zero code changes.

# Go Client Agent

The Go agent runs next to your app as an HTTP(S) forward proxy on `localhost:7742`. It intercepts outbound calls to your KnoxCall-configured routes and transparently rewrites them through the KnoxCall data plane — **no code changes, no base URL swap**.

## When to Use It

* Your app is on infrastructure where changing DNS records is awkward (serverless runtimes with cached DNS, managed platforms, BYOD-host environments).
* You can't modify the SDK's base URL (vendor SDK that hardcodes production hosts).
* You want a drop-in ZTNA-style proxy without code changes.

If you *can* change base URLs, direct routing is simpler and faster — [skip the agent](/getting-started/first-route).

## Install

Generate agent credentials under **Automation → Agents** first, then install on each host that runs your app.

<CodeGroup>
  ```bash Linux / macOS theme={"dark"}
  curl -sSfL https://knoxcall.com/agent/install.sh | bash -s -- \
    --agent-id=kc_agent_xxx \
    --agent-secret=yyy \
    --mode=intercept
  ```

  ```powershell Windows theme={"dark"}
  iwr -useb https://knoxcall.com/agent/install.ps1 | iex
  # then
  knoxcall-agent --mode=intercept --agent-id=... --agent-secret=...
  ```

  ```yaml docker-compose theme={"dark"}
  services:
    knoxcall-agent:
      image: knoxcall/agent:latest
      restart: unless-stopped
      network_mode: "host"
      environment:
        KNOXCALL_AGENT_ID: kc_agent_xxx
        KNOXCALL_AGENT_SECRET: yyy
        KNOXCALL_AGENT_MODE: intercept
  ```
</CodeGroup>

## How Interception Works

The agent generates a local CA certificate on first run and installs it in the system trust store. For every outbound HTTP(S) request:

1. The app's OS/SDK HTTP proxy setting points at `localhost:7742`.
2. The agent inspects the target host.
3. **Matched routes** (host is a registered KnoxCall route target) → MITM the TLS handshake with a locally-signed certificate, rewrite to the KnoxCall proxy URL with auth headers attached.
4. **Unmatched** → pass-through unchanged; the agent never sees non-KnoxCall traffic.

Your app code sees KnoxCall responses as if they came directly from the target API.

## Modes

The same binary runs in six modes depending on the positional argument:

| Mode        | Purpose                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `control`   | Default. Persistent WebSocket to control plane; executes commands dispatched from the admin UI |
| `proxy`     | Full proxy data plane (self-hosted / `knoxcall/proxy` container)                               |
| `intercept` | Long-running local MITM listener on `localhost:7742`                                           |
| `onboard`   | One-shot AI-powered codebase scanner for discovering API calls + secrets                       |
| `scan`      | One-shot hardcoded-credential scanner (walks filesystem, env vars, TCP connections)            |
| `doctor`    | One-shot connectivity and config sanity check                                                  |

## Database Proxying

Database proxying is a capability of the long-running `intercept` (and `control`) modes — there is no separate positional mode for it. When the session bundle includes database routes, the agent binds one TCP listener per configured route on `127.0.0.1`. Applications connect to `127.0.0.1:{port}` as if connecting to the database directly — the agent handles all authentication to the upstream database and pipes the connection through.

This is used as part of [Secret Store Migration Bucket B](/essentials/migrations/bucket-b-databases) to migrate database credentials from cloud secret stores (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager) into KnoxCall with zero credential exposure.

```bash theme={"dark"}
KNOXCALL_AGENT_ID=kc_agent_xxx \
KNOXCALL_AGENT_SECRET=yyy \
knoxcall-agent intercept
```

The agent reads its database route configuration from the KnoxCall session bundle (pushed from the control plane). Each route specifies: protocol (postgres/mysql/mongodb/redis/sqlserver), local port, upstream host/port, and credential secret reference.

See [Agent database proxy protocols](/essentials/migrations/agent-db-proxy) for wire-level details on each supported protocol.

## Tamper Seal

Every agent binary ships with a `build_sig` — an HMAC-SHA256 of the binary hash signed with a CI-only secret. The control plane validates this signature on every session fetch and refuses sessions for unknown builds in strict mode (`KNOXCALL_STRICT_TAMPER_CHECK=true`). In the default alert-only mode, unknown builds still get sessions but raise a visible warning in the admin UI.

This means a modified agent binary cannot simply reuse captured credentials — the control plane recognises it as foreign and refuses to issue the session key.

## Operational

* **Heartbeat**: every 60 seconds. Missing for >2 min = stale, >10 min = offline. Visible in Automation → Agents.
* **Session renewal**: in `intercept` mode the agent renews its bundle via `/agent/v1/session/renew` on the control plane, at the `next_renew_at` time returned in each bundle (typically before the \~1-hour session expiry). (The self-hosted `proxy` container instead re-fetches via `/agent/v1/session` on its own \~hourly cycle — see [Self-Hosted Proxy](/infrastructure/self-hosted-proxy).)
* **Credential rotation**: regenerate the agent secret from the Agents admin page and restart the agent — there is no downtime if you rotate before the old session expires.
* **Revocation**: revoking from the admin UI takes effect on the next session-renewal cycle (within \~5 minutes).

## Agent Detail Page

The **Automation → Agents → {agent}** detail page shows:

* Identity & heartbeat state
* 7-day route activity (requests intercepted per route)
* Tamper events (if any build\_sig verifications failed)
* Revoke action

## Troubleshooting

* **"Certificate trust errors"**: the local CA didn't install. Re-run `knoxcall-agent install-ca` with admin/root.
* **"Connection refused on localhost:7742"**: agent crashed or exited. Check `journalctl -u knoxcall-agent` (Linux) or the Event Viewer (Windows).
* **"Session denied, tamper detected"**: the running binary's `build_sig` isn't in `agent_versions`. Download a fresh official binary.