← Tools Proxy | Process Pool →

Docs: Getting Started · Tutorial · Configuration · Agents · API Reference · Pipelines · Async Jobs · Webhooks · Client Usage · Tools Proxy · Security · Process Pool · Testing · Troubleshooting

Before you expose this to the internet, read this entire page.

Agents run as full subprocesses of the Bridge host, with the Bridge user's permissions. Most agents can execute shell commands, read/write files, and reach any network the host can reach.

• Token compromise ≈ shell compromise. Anyone with ACP_TOKEN can tell an agent to rm -rf, exfiltrate ~/.ssh, or hit internal services. Rotate tokens, never commit them, and scope allowed_ips tightly.
• --trust-all-tools auto-approves every tool call. Kiro's default config includes this flag — remove it in untrusted networks.
• session/request_permission is auto-answered with proceed_always so Claude doesn't hang. Same implication: anything the agent wants to do, it gets to do.
• Prompt injection is a real vector. Untrusted content fed to an agent (web pages, user input, log files) can hijack it into running unintended commands.

Bridge uses dual authentication:

1. Bearer Token — Authorization: Bearer <token> header on every request
2. IP Allowlist — only requests from security.allowed_ips are accepted

Both must pass. /health and /ui are unauthenticated (for load balancer probes and browser access).

Token supports ${ENV_VAR} references in config — keep actual values in .env or environment only.

• Don't pipe arbitrary web/user content directly into /runs without framing
• Keep working_dir pinned to a workspace directory, not $HOME
• Review agent transcripts for unexpected tool calls before trusting output
• Use Harness Factory's sandboxed presets (reader, reviewer) for untrusted input — they have restricted tool permissions

• Webhook token is configured separately from Bridge auth token
• OpenClaw format includes auth headers; generic format sends plain JSON
• Messages are auto-chunked at 1800 chars to avoid Discord API limits

The heartbeat system (heartbeat.enabled: true) periodically pings agents with environment snapshots — who's online, who's busy, recent activity. This enables inter-agent collaboration.

• Path leakage: heartbeat prompts include a client script command for inter-agent communication. As of v0.18.0, only the script basename is shown (e.g. acp-client.sh), never the absolute path. Previously, the full path (e.g. /home/user/projects/acp-bridge/skill/scripts/acp-client.sh) was exposed, revealing the project location to all agents.
• Agent visibility: only agents with heartbeat: true in their config appear in heartbeat prompts. Agents without this flag (e.g. kiro) are invisible to other agents during heartbeat, preventing unwanted cross-agent interactions.
• --trust-all-tools + auto-permission: agents with --trust-all-tools (like kiro) combined with Bridge's auto-reply to session/request_permission can execute any shell command. Even with working_dir set to /tmp/ko, agents can cd or use absolute paths to access any file the Bridge user can access. working_dir is a starting directory, not a sandbox.
• True isolation requires running agents in Docker containers or Linux namespaces.

Contributions welcome:

• Per-user tokens with scoped permissions
• Rate limiting per token/IP → basic per-agent RPM/TPM rate limiting added in v0.18.0 (see Configuration)
• Audit logging (who called what, when)
• mTLS helper / reverse proxy config examples

Since v0.21.3, every prompt actually sent to an agent is persisted in the local SQLite (data/jobs.db, table prompt_log) for post-mortem and replay (see API Reference → Prompt Log).

What is stored: the user-supplied template, the post-{{var}} rendered version, the fully decorated final string (including shared_workspace*.txt hint and get_prompt_suffix()), plus metadata (agent, session id, cwd, decorations applied, timestamp).

What is not stored: the agent's response, intermediate tool-call payloads, or any data outside the prompt itself.

• prompt_log.redact_secrets: true — values matching the patterns in OPERATIONS.md ("Sensitive Patterns" section) are masked with ***REDACTED*** before write. Covers token=, api_key=, password=, secret=, ACP_BRIDGE_TOKEN=, OPENCLAW_TOKEN=, LITELLM_API_KEY=, ANTHROPIC_API_KEY=, AWS_SECRET_ACCESS_KEY=, Bearer <jwt>, and AKIA... AWS access key ids.
• prompt_log.max_size: 1048576 — per-field cap (1 MB); longer prompts get truncated with a marker.
• API responses default to summary-only — final/template/rendered are returned only when ?include=final is passed.
• All endpoints require Authorization: Bearer <token> (existing middleware).

Treat data/jobs.db as containing potentially sensitive user input even with redaction on (heuristic regexes are not exhaustive). Apply filesystem permissions accordingly; do not commit the file to source control (already in .gitignore).

• Configuration — token and IP allowlist setup
• Process Pool — subprocess isolation details
• Troubleshooting — auth error fixes