https://github.com/ai-workspace-lab/xworkmate-bridge
Unified ACP bridge for XWorkmate. Exposes one APP-facing endpoint and routes requests to Codex, OpenCode, Gemini, and gateway providers.
https://github.com/ai-workspace-lab/xworkmate-bridge
acp agentproxy bridge json-rpc
Last synced: about 1 month ago
JSON representation
Unified ACP bridge for XWorkmate. Exposes one APP-facing endpoint and routes requests to Codex, OpenCode, Gemini, and gateway providers.
- Host: GitHub
- URL: https://github.com/ai-workspace-lab/xworkmate-bridge
- Owner: ai-workspace-lab
- Created: 2026-04-09T01:51:15.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-06-26T22:45:07.000Z (about 1 month ago)
- Last Synced: 2026-06-27T00:32:17.705Z (about 1 month ago)
- Topics: acp, agentproxy, bridge, json-rpc
- Language: Go
- Homepage:
- Size: 18.3 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 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 APP-facing bridge entrypoint and proxies traffic
to four independent upstream production services. The APP-facing canonical ACP
path is WebSocket `/acp`; HTTP `/acp/rpc` remains available for CI, scripts,
debugging, and compatibility fallback under
`https://xworkmate-bridge.svc.plus`.
OpenClaw task submission is the only dedicated HTTP task route:
`POST /gateway/openclaw` for `session.start` and follow-up `session.message`.
It is not a global ACP base endpoint.
Architecture topology: [docs/architecture/acp-forwarding-topology.md](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/acp-forwarding-topology.md)
ADR for the unified APP-facing bridge contract: [docs/architecture/adr-unified-bridge-entrypoints.md](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/architecture/adr-unified-bridge-entrypoints.md)
Example provider sync config: [example/config.yaml](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/example/config.yaml)
API reference: [docs/api-reference.md](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/api-reference.md)
Backend API design: [docs/backend-api-design.md](/Users/shenlan/workspaces/cloud-neutral-toolkit/xworkmate-bridge/docs/backend-api-design.md)
## Compatibility
For compatibility with `xworkmate-app`, the built helper binary name remains `xworkmate-go-core`.
## Commands
```bash
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
GitHub Releases are published only after `deploy` and `validate` both succeed.
In this repository, a published Release means the built image has been deployed
to `xworkmate-bridge.svc.plus` and passed post-deploy validation there.
### Deploy stage
The deploy stage checks out:
- this service repository into `xworkmate-bridge/`
- the `x-evor/playbooks` repository into `playbooks/`
Then it installs the native `linux/amd64` bridge binary with
`scripts/github-actions/deploy-native-binary.sh`. The native bridge runs as the
`ubuntu` user's systemd user service:
- binary: `/home/ubuntu/.local/bin/xworkmate-go-core`
- unit: `/home/ubuntu/.config/systemd/user/xworkmate-bridge.service`
- restart: `systemctl --user restart xworkmate-bridge.service`
During migration the script performs a one-time stop/disable of the old system
unit, then deploys and restarts through `ubuntu@`.
### Validate stage
The validate stage proves production alignment against the bridge public
contract:
- bridge root and `/api/ping`
- strict image / tag / commit / version match against the built image ref
- upstream ACP capability probes for `codex`, `opencode`, and `gemini`
- minimal `session.start` smoke tests through the bridge JSON-RPC contract
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:
- `ai_workspace_auth_token`: manual dispatch input that is forwarded as `AI_WORKSPACE_AUTH_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`