Skip to main content

​
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.

​
Install

Generate agent credentials under Automation → Agents first, then install on each host that runs your app. 
curl -sSfL https://knoxcall.com/agent/install.sh | bash -s -- \
  --agent-id=kc_agent_xxx \
  --agent-secret=yyy \
  --mode=intercept

​
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 four modes depending on the flag:
ModePurpose
interceptProduction MITM proxy on localhost:7742 — the most common mode
onboardAI-powered codebase scanner for discovering API calls + secrets
monitorWatches env vars and TCP connections to surface onboarding opportunities
serverThe self-hosted knoxcall/proxy container — see Self-hosted

​
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: bundle refreshed every ~55 minutes via /agent/v1/session/renew on the control plane.
  • 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 → 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.