@annals/agent-bridge 0.1.2 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# @annals/agent-bridge
|
|
2
|
+
|
|
3
|
+
Connect your local AI agent to [agents.hot](https://agents.hot) — turn it into a SaaS service anyone can use.
|
|
4
|
+
|
|
5
|
+
Your agent stays on `127.0.0.1`. The bridge CLI connects **outbound** to the cloud — no ports to open, no reverse proxy needed.
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
# One-click setup (recommended)
|
|
11
|
+
npx @annals/agent-bridge connect --setup https://agents.hot/api/connect/ct_xxxxx
|
|
12
|
+
|
|
13
|
+
# Reconnect (reads saved config)
|
|
14
|
+
npx @annals/agent-bridge connect
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
1. Create an agent on [agents.hot/settings](https://agents.hot/settings)
|
|
18
|
+
2. Click **Connect** — copy the command
|
|
19
|
+
3. Paste in your terminal — done
|
|
20
|
+
|
|
21
|
+
The ticket is one-time use and expires in 15 minutes.
|
|
22
|
+
|
|
23
|
+
## Supported Agents
|
|
24
|
+
|
|
25
|
+
| Agent | Status | How it connects |
|
|
26
|
+
|-------|--------|-----------------|
|
|
27
|
+
| [OpenClaw](https://github.com/nicepkg/openclaw) | Available | WebSocket to local gateway (Protocol v3) |
|
|
28
|
+
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Available | stdio (stream-json format) |
|
|
29
|
+
| Codex CLI | Planned | — |
|
|
30
|
+
| Gemini CLI | Planned | — |
|
|
31
|
+
|
|
32
|
+
## CLI Commands
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
agent-bridge connect [type] # Connect agent to platform
|
|
36
|
+
--setup <url> # One-click setup from ticket URL
|
|
37
|
+
--agent-id <id> # Agent UUID
|
|
38
|
+
--project <path> # Project path (Claude adapter)
|
|
39
|
+
--gateway-url <url> # OpenClaw gateway URL
|
|
40
|
+
--gateway-token <token> # OpenClaw gateway token
|
|
41
|
+
--sandbox # Run inside sandbox (macOS, requires srt)
|
|
42
|
+
|
|
43
|
+
agent-bridge login # Authenticate
|
|
44
|
+
agent-bridge status # Check connection
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## How It Works
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
Your machine Cloud Users
|
|
51
|
+
┌──────────────────┐ outbound ┌─────────────────────┐ ┌──────────┐
|
|
52
|
+
│ OpenClaw │ WebSocket │ │ │ │
|
|
53
|
+
│ Claude Code ├──────────────► │ bridge.agents.hot │ ◄── │ Platform │
|
|
54
|
+
│ Codex (planned) │ (no inbound │ (Cloudflare Worker)│ │ IM bots │
|
|
55
|
+
│ Gemini (planned) │ ports) │ │ │ API │
|
|
56
|
+
└──────────────────┘ └─────────────────────┘ └──────────┘
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
1. CLI connects outbound to Bridge Worker via WebSocket
|
|
60
|
+
2. Users send messages on agents.hot
|
|
61
|
+
3. Bridge Worker relays messages to your CLI
|
|
62
|
+
4. CLI passes them to your local agent
|
|
63
|
+
5. Agent responds with streaming text back through the bridge
|
|
64
|
+
|
|
65
|
+
## Security
|
|
66
|
+
|
|
67
|
+
- No inbound ports — outbound WebSocket only
|
|
68
|
+
- Bridge token authentication (`bt_` token per agent)
|
|
69
|
+
- One-time connect tickets (15 min expiry)
|
|
70
|
+
- Optional OS-native sandbox via [srt](https://github.com/anthropic-experimental/sandbox-runtime)
|
|
71
|
+
|
|
72
|
+
## Related
|
|
73
|
+
|
|
74
|
+
- [`@annals/bridge-protocol`](https://www.npmjs.com/package/@annals/bridge-protocol) — Bridge Protocol v1 type definitions
|
|
75
|
+
- [GitHub repo](https://github.com/annals-ai/agent-bridge) — full monorepo with Worker, adapters, and docs
|
|
76
|
+
|
|
77
|
+
## License
|
|
78
|
+
|
|
79
|
+
[MIT](https://github.com/annals-ai/agent-bridge/blob/main/LICENSE)
|