XWorkmate Bridge

xworkmate-bridge is the standalone repository for the XWorkmate ACP Bridge Server and the embedded Go helper previously stored under xworkmate-app/go/go_core.

What lives here

• ACP Bridge HTTP/WebSocket server
• ACP stdio bridge entrypoint
• Go helper runtime packages used by the ACP bridge
• Unit tests for bridge routing, RPC contracts, mounts, runtime dispatch, and provider sync

ACP Forwarding Topology

This repository exposes one bridge entrypoint and forwards to four verified public targets. The full Mermaid diagram lives in docs/architecture/acp-forwarding-topology.md.

Example provider sync config: example/config.yaml

API reference: docs/api-reference.md

Compatibility

For compatibility with xworkmate-app, the built helper binary name remains xworkmate-go-core.

Commands

make test
make build
./build/bin/xworkmate-go-core serve --listen 127.0.0.1:8787

GitHub Actions

This repository includes one GitHub Actions pipeline with four stages:

• prep: Go static checks
• build: build the linux/amd64 artifact for the x86 target host and upload it
• deploy: run Ansible CD with x-evor/playbooks
• validate: verify the public endpoints after deployment

Deploy stage

The deploy stage checks out:

• this service repository into xworkmate-bridge/
• the x-evor/playbooks repository into playbooks/

Then it runs playbooks/deploy_xworkmate_bridge_vhosts.yml, which builds the service for linux/amd64 and deploys it to the target host with Ansible.

Required GitHub secrets:

• SINGLE_NODE_VPS_SSH_PRIVATE_KEY: private key used by the Actions runner to SSH into the target host
• WORKSPACE_REPO_TOKEN: token with access to checkout x-evor/playbooks

Optional GitHub secrets:

• SSH_KNOWN_HOSTS: pre-seeded known_hosts content for stricter host verification

Optional workflow input:

• internal_service_token: manual dispatch input that is forwarded to Ansible as INTERNAL_SERVICE_TOKEN

Environment

• ACP_LISTEN_ADDR: listen address for serve mode, default 127.0.0.1:8787
• OUTPUT_DIR: optional output directory for make build
• OUTPUT_PATH: optional explicit build path for make build