@n1creator/openacp-cli 2026.712.10 → 2026.712.12
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 +126 -326
- package/dist/cli.js +123 -41
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.js +95 -21
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,423 +1,223 @@
|
|
|
1
|
-
OpenACP — self-hosted bridge that connects 28+ AI coding agents (Claude Code, Codex, Gemini, Cursor) to chat, REST, and SSE, with native bridge-agnostic speech-to-text. Your machine, your keys, your data.
|
|
2
|
-
|
|
3
1
|
<div align="center">
|
|
4
2
|
|
|
5
3
|
# OpenACP
|
|
6
4
|
|
|
7
|
-
**
|
|
5
|
+
**Run AI coding agents from chat, automation, or your own integration.**
|
|
8
6
|
|
|
9
|
-
|
|
7
|
+
Self-hosted sessions for Codex, Cursor, Claude Code, Gemini, and other ACP agents — with native speech-to-text, scoped proxy routing, and real-time control from Telegram, Discord, Slack, REST, or SSE.
|
|
10
8
|
|
|
11
9
|
[](LICENSE)
|
|
12
10
|
[](https://nodejs.org/)
|
|
13
11
|
[](https://agentclientprotocol.org/)
|
|
14
12
|
[](https://www.npmjs.com/package/@n1creator/openacp-cli)
|
|
15
|
-
[](https://x.com/openacp_ai)
|
|
16
13
|
|
|
17
|
-
[
|
|
14
|
+
[Quick Start](#quick-start) · [Capabilities](#capabilities) · [Agents](#agents) · [Documentation](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook) · [Contributing](CONTRIBUTING.md)
|
|
18
15
|
|
|
19
|
-
<img src="docs/images/banner.jpg" alt="OpenACP —
|
|
16
|
+
<img src="docs/images/banner.jpg" alt="OpenACP — control AI coding agents from messaging and automation clients" width="100%" />
|
|
20
17
|
|
|
21
18
|
</div>
|
|
22
19
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
> **N1 Creator distribution.** This repository publishes the maintained fork as
|
|
26
|
-
> `@n1creator/openacp-cli` and `@n1creator/openacp-plugin-sdk`. Existing OpenACP
|
|
27
|
-
> workspaces remain compatible; migrate by replacing the global CLI package and
|
|
28
|
-
> restarting the same instance. The maintained CLI includes native local
|
|
29
|
-
> faster-whisper STT and keeps the speech pipeline independent from any one
|
|
30
|
-
> messaging adapter.
|
|
31
|
-
|
|
32
|
-
## What is OpenACP?
|
|
20
|
+
OpenACP runs on your machine and connects messaging or API clients to local ACP agent processes. It owns session lifecycle, permissions, streaming, files, speech, and routing; the selected agent works in your configured workspace with its own provider credentials.
|
|
33
21
|
|
|
34
|
-
|
|
22
|
+
> **N1 Creator distribution.** This repository is the maintained
|
|
23
|
+
> [`an1creator/OpenACP`](https://github.com/an1creator/OpenACP) fork. Its public
|
|
24
|
+
> packages are [`@n1creator/openacp-cli`](https://www.npmjs.com/package/@n1creator/openacp-cli)
|
|
25
|
+
> and [`@n1creator/openacp-plugin-sdk`](https://www.npmjs.com/package/@n1creator/openacp-plugin-sdk).
|
|
35
26
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
27
|
+
```text
|
|
28
|
+
Telegram / Discord / Slack / REST / SSE
|
|
29
|
+
↓
|
|
30
|
+
OpenACP session bridge
|
|
31
|
+
├─ permissions and streaming
|
|
32
|
+
├─ speech and file handling
|
|
33
|
+
└─ scoped network routing
|
|
34
|
+
↓
|
|
35
|
+
Codex / Cursor / Claude / Gemini / ACP agent
|
|
36
|
+
↓
|
|
37
|
+
Your workspace
|
|
46
38
|
```
|
|
47
39
|
|
|
48
|
-
## Why OpenACP?
|
|
49
|
-
|
|
50
|
-
| Without OpenACP | With OpenACP |
|
|
51
|
-
|----------------|-------------|
|
|
52
|
-
| *"Its usage is currently focused on its dedicated terminal REPL and specific IDE integrations"* | Control from Telegram, Discord, or Slack — any device, anywhere |
|
|
53
|
-
| *"Codex Desktop App only works with local projects. It does not support development on remote hosts"* | Full remote development support — run agents on your server, manage from your phone |
|
|
54
|
-
| *"There's no way to trigger Claude Code sessions from external issue trackers"* | REST API for CI/CD integration and external triggers |
|
|
55
|
-
| *"Being able to use a proper mobile app UI would be much better than having to access sessions through ssh + tmux"* | Native Telegram/Discord UI — no SSH, no terminal on mobile |
|
|
56
|
-
| *"Cline is really burning up OpenRouter tokens and my wallet"* | Built-in usage tracking and monthly budget limits per session |
|
|
57
|
-
|
|
58
|
-
## Use Cases
|
|
59
|
-
|
|
60
|
-
- **Remote coding** — Tired of being chained to your desk to run Claude Code? Review PRs, fix bugs, and deploy from your phone via Telegram while away from your desk.
|
|
61
|
-
- **Team visibility** — Share a Discord channel where everyone sees what the AI agent is doing in real time — no more black-box coding sessions.
|
|
62
|
-
- **Multi-agent workflows** — Start with Claude Code for planning, switch to Codex for implementation, use Gemini for review — all in one chat thread, no reconfiguration.
|
|
63
|
-
- **CI/CD integration** — Trigger agent sessions from GitHub Actions or any issue tracker via the REST API.
|
|
64
|
-
- **Voice-driven workflows** — Send audio from any compatible bridge; OpenACP transcribes it locally before the agent receives the prompt.
|
|
65
|
-
- **Self-hosted AI gateway** — Keep API keys and code on your own infrastructure. No third-party cloud, no vendor lock-in.
|
|
66
|
-
- **Local LLM support** — Run agents against self-hosted models (Ollama, LM Studio) via ACP-compatible adapters. Your models, your data.
|
|
67
|
-
|
|
68
40
|
<div align="center">
|
|
69
41
|
<table>
|
|
70
42
|
<tr>
|
|
71
|
-
<td align="center"><img src="docs/images/menu.png" width="250" alt="OpenACP control panel
|
|
72
|
-
<td align="center"><img src="docs/images/agent-working.png" width="250" alt="AI coding agent
|
|
43
|
+
<td align="center"><img src="docs/images/menu.png" width="250" alt="OpenACP control panel in Telegram" /><br /><b>Control Panel</b><br />Sessions, agents, and settings</td>
|
|
44
|
+
<td align="center"><img src="docs/images/agent-working.png" width="250" alt="An AI coding agent working through OpenACP" /><br /><b>Agent at Work</b><br />Plans, tools, and output in real time</td>
|
|
73
45
|
</tr>
|
|
74
46
|
<tr>
|
|
75
|
-
<td align="center"><img src="docs/images/tool-calls.png" width="250" alt="Real-time tool
|
|
76
|
-
<td align="center"><img src="docs/images/skills.png" width="250" alt="
|
|
47
|
+
<td align="center"><img src="docs/images/tool-calls.png" width="250" alt="Real-time tool calls in OpenACP" /><br /><b>Tool Calls</b><br />Review actions as they happen</td>
|
|
48
|
+
<td align="center"><img src="docs/images/skills.png" width="250" alt="Agent skills in OpenACP" /><br /><b>Agent Skills</b><br />Reusable coding workflows</td>
|
|
77
49
|
</tr>
|
|
78
50
|
</table>
|
|
79
51
|
</div>
|
|
80
52
|
|
|
81
|
-
##
|
|
82
|
-
|
|
83
|
-
**Requirements:** Node.js 20+ (the installer handles this for you)
|
|
53
|
+
## Quick Start
|
|
84
54
|
|
|
85
|
-
|
|
55
|
+
**Requirement:** Node.js 20 or newer.
|
|
86
56
|
|
|
87
57
|
```bash
|
|
88
|
-
|
|
58
|
+
npm install -g @n1creator/openacp-cli
|
|
59
|
+
openacp
|
|
89
60
|
```
|
|
90
61
|
|
|
91
|
-
|
|
62
|
+
The first run opens an interactive setup wizard. Choose one or more connectors, provide their credentials, select a workspace and default agent, then choose foreground or daemon mode.
|
|
92
63
|
|
|
93
64
|
```bash
|
|
94
|
-
|
|
65
|
+
openacp doctor # validate the installation
|
|
66
|
+
openacp status # inspect the running instance
|
|
67
|
+
openacp logs # follow daemon logs
|
|
95
68
|
```
|
|
96
69
|
|
|
97
|
-
|
|
70
|
+
Platform-specific setup is in the maintained [Telegram](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/platform-setup/telegram.md), [Discord](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/platform-setup/discord.md), and [Slack](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/platform-setup/slack.md) guides.
|
|
98
71
|
|
|
99
|
-
|
|
72
|
+
## Capabilities
|
|
100
73
|
|
|
101
|
-
|
|
74
|
+
### Agents and sessions
|
|
102
75
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
76
|
+
- Run modern Codex and Cursor ACP processes alongside Claude Code, Gemini CLI, and other ACP-compatible agents.
|
|
77
|
+
- Read model, mode, and reasoning choices from each agent at runtime instead of maintaining a hard-coded model list.
|
|
78
|
+
- Keep one persistent session per topic, thread, or API session; resume it after process restarts.
|
|
79
|
+
- Switch agents with `/switch`, transfer work between terminal and chat with `/handoff`, and cancel safely with `/cancel`.
|
|
80
|
+
- Review permission requests through connector controls or configure narrowly scoped approval behavior.
|
|
106
81
|
|
|
107
|
-
|
|
82
|
+
### Connectors and automation
|
|
108
83
|
|
|
109
|
-
|
|
84
|
+
| Interface | Session mapping | Highlights |
|
|
85
|
+
|-----------|-----------------|------------|
|
|
86
|
+
| Telegram | Forum topics | Commands, buttons, streaming, files, voice |
|
|
87
|
+
| Discord | Threads | Commands, interactions, files, streaming |
|
|
88
|
+
| Slack | Channels and threads | Socket Mode, commands, files, streaming |
|
|
89
|
+
| REST + SSE | API session IDs | Automation, attachments, live event streams |
|
|
110
90
|
|
|
111
|
-
|
|
91
|
+
The core session pipeline is connector-neutral. An external adapter gets the same session, attachment, speech, permission, and agent-routing behavior when it implements the standard adapter contract.
|
|
112
92
|
|
|
113
|
-
|
|
114
|
-
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
|
|
115
|
-
export NVM_DIR="$HOME/.nvm"
|
|
116
|
-
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
|
|
117
|
-
nvm install --lts
|
|
118
|
-
nvm use --lts
|
|
119
|
-
```
|
|
93
|
+
### Native speech-to-text
|
|
120
94
|
|
|
121
|
-
|
|
95
|
+
STT is a built-in OpenACP service, not Telegram-specific glue. Any compatible bridge can submit a standard `audio` attachment:
|
|
122
96
|
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
# → ? Choose your platform: Telegram / Discord / Slack
|
|
128
|
-
# → ? Enter your bot token: ********
|
|
129
|
-
# → ? Select workspace directory: ~/projects
|
|
130
|
-
# → ? Choose default AI agent: Claude Code
|
|
131
|
-
# → ✓ Configuration saved. Starting OpenACP...
|
|
132
|
-
# → 🚀 OpenACP is running. Send a message to your bot!
|
|
97
|
+
```text
|
|
98
|
+
audio attachment
|
|
99
|
+
├─ agent supports native audio → pass the original attachment
|
|
100
|
+
└─ otherwise → local faster-whisper or Groq STT → append transcript to prompt
|
|
133
101
|
```
|
|
134
102
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
1. Choose your platform (Telegram, Discord, Slack, or multiple)
|
|
140
|
-
2. Connect your bot (token validation + auto-detection)
|
|
141
|
-
3. Pick a workspace directory
|
|
142
|
-
4. Select your default AI agent
|
|
143
|
-
5. Choose run mode (foreground or daemon)
|
|
144
|
-
|
|
145
|
-
That's it. Send a message to your bot and start coding.
|
|
146
|
-
|
|
147
|
-
> **Need detailed setup for a specific platform?** See the [Platform Setup guides](https://openacp.gitbook.io/docs/platform-setup).
|
|
148
|
-
|
|
149
|
-
## Features
|
|
150
|
-
|
|
151
|
-
### Channels and Bridges
|
|
103
|
+
- `local-whisper` runs on the OpenACP host without an API key and reuses its environment and model cache.
|
|
104
|
+
- Groq provides an optional hosted STT path.
|
|
105
|
+
- Failed transcription preserves the original audio instead of silently dropping it.
|
|
106
|
+
- Providers and local model settings are available through plugin settings and the API.
|
|
152
107
|
|
|
153
|
-
|
|
154
|
-
|----------|--------|------------|
|
|
155
|
-
| **Telegram** | Stable | Forum topics per session, streaming, permission buttons, voice |
|
|
156
|
-
| **Discord** | Stable | Thread-based sessions, slash commands, button interactions |
|
|
157
|
-
| **Slack** | Stable | Socket Mode, channel-based sessions, thread organization |
|
|
158
|
-
| **REST API / SSE** | Stable | Session automation, base64 file/audio attachments, streamed events |
|
|
108
|
+
Local Whisper requires Python 3 and either `uv` or `python3-venv`; its runtime is prepared on first use. See [Voice and Speech](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/using-openacp/voice-and-speech.md).
|
|
159
109
|
|
|
160
|
-
###
|
|
110
|
+
### Scoped proxy routing
|
|
161
111
|
|
|
162
|
-
|
|
163
|
-
- **Session management** — Each conversation gets its own thread/topic with auto-naming
|
|
164
|
-
- **Session persistence** — Sessions survive restarts, with configurable TTL
|
|
165
|
-
- **Permission control** — Approve or deny agent actions via buttons, with optional auto-approve
|
|
166
|
-
- **Real-time streaming** — See agent thinking, tool calls, and output as they happen
|
|
167
|
-
- **Agent switching** — Switch agents mid-conversation with `/switch`; history carries over automatically
|
|
168
|
-
- **Dynamic model options** — Model, mode, and reasoning choices come from each ACP agent at runtime instead of a hard-coded model list
|
|
169
|
-
- **Agent-aware audio routing** — Pass audio directly to agents that support it; otherwise transcribe it through the shared STT service
|
|
170
|
-
- **Scoped proxy routing** — Route Telegram, individual ACP agents, services, or plugin flows independently through HTTP, HTTPS, SOCKS5, or SOCKS5H profiles
|
|
171
|
-
|
|
172
|
-
### Developer Tools
|
|
173
|
-
|
|
174
|
-
- **Tunnel & port forwarding** — Expose local ports to the internet (Cloudflare, ngrok, bore, Tailscale)
|
|
175
|
-
- **Built-in file viewer** — Monaco Editor with syntax highlighting, diffs, and markdown preview
|
|
176
|
-
- **Session transfer** — Move sessions between terminal and chat (`/handoff`)
|
|
177
|
-
- **Agent switch** — Change which AI agent handles your session mid-conversation (`/switch`)
|
|
178
|
-
- **Voice & speech** — Bundled local faster-whisper or Groq STT for every compatible bridge, plus optional Edge TTS
|
|
179
|
-
- **Usage tracking** — Token counts, cost reports, optional monthly budget limits
|
|
180
|
-
- **Context resume** — Resume sessions with full conversation history
|
|
181
|
-
|
|
182
|
-
### Native Speech-to-Text Across Bridges
|
|
183
|
-
|
|
184
|
-
The maintained package includes the `local-whisper` provider in the built-in
|
|
185
|
-
`@openacp/speech` service. STT runs in the shared session pipeline rather than
|
|
186
|
-
inside Telegram, so the same behavior applies to Telegram voice messages,
|
|
187
|
-
REST/SSE audio attachments, and external adapters that submit a standard
|
|
188
|
-
attachment with `type: "audio"`.
|
|
112
|
+
Proxy profiles describe endpoints; routes decide which traffic uses them. OpenACP supports **HTTP, HTTPS, SOCKS5, and SOCKS5H**, with independent scopes for channels, agents, services, and plugins.
|
|
189
113
|
|
|
190
114
|
```text
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
115
|
+
global: direct
|
|
116
|
+
channels.telegram: profile:primary
|
|
117
|
+
agents.codex: profile:primary
|
|
118
|
+
agents.cursor: direct
|
|
119
|
+
services.default: direct
|
|
195
120
|
```
|
|
196
121
|
|
|
197
|
-
- **
|
|
198
|
-
-
|
|
199
|
-
-
|
|
200
|
-
-
|
|
201
|
-
-
|
|
122
|
+
- In Telegram, open **Settings → Proxy Management** or use `/proxy`; other connectors can expose the same connector-neutral command model.
|
|
123
|
+
- CLI and REST automation are available through `openacp proxy` and `/api/v1/proxy`.
|
|
124
|
+
- `direct` removes inherited proxy environment variables from the selected ACP process; `inherit` follows the parent scope.
|
|
125
|
+
- Credentials are write-only, stored separately in a mode-0600 secret store, and never returned in route or status data.
|
|
126
|
+
- Protected JSON imports accept a write-only **Quick URL** in `proxyUrl`; it requires an explicit port and is mutually exclusive with separate endpoint or credential fields.
|
|
127
|
+
- Telegram deletes credential replies before use; environments without that guarantee use protected CLI/API input files.
|
|
202
128
|
|
|
203
|
-
|
|
204
|
-
selected model are prepared on the first transcription. Configure it through
|
|
205
|
-
`/settings`, the plugin settings API, or `openacp config`. See
|
|
206
|
-
[Voice and Speech](docs/gitbook/using-openacp/voice-and-speech.md) for settings,
|
|
207
|
-
formats, providers, and troubleshooting.
|
|
129
|
+
See [Scoped Proxy Routing](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/features/proxy-routing.md) for route precedence, secure inputs, testing, and recovery.
|
|
208
130
|
|
|
209
|
-
###
|
|
131
|
+
### Operations and extension
|
|
210
132
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
133
|
+
- Managed foreground or daemon lifecycle on Linux and macOS.
|
|
134
|
+
- REST API, SSE event stream, and JSON-capable CLI for automation.
|
|
135
|
+
- Health checks, structured logging, usage tracking, tunnels, and `openacp doctor` diagnostics.
|
|
136
|
+
- Plugin SDK and lifecycle for custom adapters, services, commands, and middleware.
|
|
214
137
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
agents.codex: profile:usa
|
|
219
|
-
agents.cursor: direct
|
|
220
|
-
services.default: direct
|
|
221
|
-
```
|
|
138
|
+
## Agents
|
|
139
|
+
|
|
140
|
+
OpenACP uses ACP-compatible agent definitions and the public [ACP agent registry](https://agentclientprotocol.com/get-started/registry).
|
|
222
141
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
Manage routes from any connector with `/proxy`, from the CLI with
|
|
231
|
-
`openacp proxy`, or through `/api/v1/proxy`. Channel changes are tested before
|
|
232
|
-
they are saved. See [Scoped Proxy Routing](docs/gitbook/features/proxy-routing.md).
|
|
233
|
-
|
|
234
|
-
### Operations
|
|
235
|
-
|
|
236
|
-
- **Daemon mode** — Run as a background service with auto-start on boot
|
|
237
|
-
- **CLI API** — Full REST API for automation (`openacp api ...`)
|
|
238
|
-
- **Fast first session** — A liveness-checked warm pool keeps the default agent ready, avoiding a full subprocess spawn on the first API session
|
|
239
|
-
- **Consistent health reporting** — `/api/health` merges persisted and live-only sessions so active and total counts describe the same population
|
|
240
|
-
- **Secret-safe agent inspection** — Agent list, reload, and detail API responses redact environment values while preserving variable names
|
|
241
|
-
- **Plugin system** — Install adapters as npm packages
|
|
242
|
-
- **Doctor diagnostics** — `openacp doctor` checks everything and suggests fixes
|
|
243
|
-
- **Structured logging** — Pino with rotation, per-session log files
|
|
244
|
-
|
|
245
|
-
> **Full feature documentation** — [Documentation](https://openacp.gitbook.io/docs)
|
|
246
|
-
|
|
247
|
-
## Supported Agents
|
|
248
|
-
|
|
249
|
-
OpenACP uses the [ACP Registry](https://agentclientprotocol.com/get-started/registry) — new agents are available as soon as they're registered.
|
|
250
|
-
|
|
251
|
-
| Agent | Type | Description |
|
|
252
|
-
|-------|------|-------------|
|
|
253
|
-
| [Claude Code](https://github.com/anthropics/claude-code) | npx | Anthropic's Claude coding agent |
|
|
254
|
-
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | npx | Google's Gemini CLI |
|
|
255
|
-
| [Codex CLI](https://github.com/openai/codex) | npx | OpenAI's coding assistant |
|
|
256
|
-
| [GitHub Copilot](https://github.com/github/copilot-cli) | npx | GitHub's AI pair programmer |
|
|
257
|
-
| [Cursor](https://www.cursor.com/) | binary | Cursor's coding agent |
|
|
258
|
-
| [Cline](https://github.com/cline/cline) | npx | Autonomous coding agent |
|
|
259
|
-
| [goose](https://github.com/block/goose) | binary | Open source AI agent by Block |
|
|
260
|
-
| Amp | binary | The frontier coding agent |
|
|
261
|
-
| [Auggie CLI](https://www.augmentcode.com/) | npx | Augment Code's context engine |
|
|
262
|
-
| [Junie](https://www.jetbrains.com/) | binary | AI coding agent by JetBrains |
|
|
263
|
-
| [Kilo](https://github.com/kilocode/kilo) | npx | Open source coding agent |
|
|
264
|
-
| [Qwen Code](https://github.com/QwenLM/qwen-code) | npx | Alibaba's Qwen assistant |
|
|
265
|
-
| ...and more | | [Full registry →](https://agentclientprotocol.com/get-started/registry) |
|
|
142
|
+
| Agent | Integration |
|
|
143
|
+
|-------|-------------|
|
|
144
|
+
| [Codex CLI](https://github.com/openai/codex) | ACP process with runtime model, mode, and reasoning options |
|
|
145
|
+
| [Cursor](https://www.cursor.com/) | Local Cursor ACP process |
|
|
146
|
+
| [Claude Code](https://github.com/anthropics/claude-code) | ACP-compatible package process |
|
|
147
|
+
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | ACP-compatible package process |
|
|
148
|
+
| Other agents | Install or define another ACP-compatible process |
|
|
266
149
|
|
|
267
150
|
```bash
|
|
268
|
-
openacp agents
|
|
269
|
-
openacp agents install <name>
|
|
151
|
+
openacp agents
|
|
152
|
+
openacp agents install <name>
|
|
270
153
|
```
|
|
271
154
|
|
|
272
|
-
|
|
155
|
+
Agent CLIs may require their own installation, account, or provider credentials.
|
|
156
|
+
|
|
157
|
+
## CLI Reference
|
|
273
158
|
|
|
274
159
|
```bash
|
|
275
|
-
#
|
|
276
|
-
openacp
|
|
277
|
-
openacp start
|
|
278
|
-
openacp status
|
|
279
|
-
openacp
|
|
280
|
-
|
|
281
|
-
#
|
|
282
|
-
openacp config # Interactive config editor
|
|
283
|
-
openacp reset # Re-run setup wizard
|
|
284
|
-
openacp doctor # System diagnostics
|
|
285
|
-
|
|
286
|
-
# Sessions & API (requires running daemon)
|
|
160
|
+
# Lifecycle
|
|
161
|
+
openacp
|
|
162
|
+
openacp start | stop | restart
|
|
163
|
+
openacp status
|
|
164
|
+
openacp doctor
|
|
165
|
+
|
|
166
|
+
# Sessions and local API
|
|
287
167
|
openacp api new [agent] [workspace]
|
|
288
168
|
openacp api status
|
|
289
|
-
openacp api
|
|
290
|
-
openacp api cancel <id>
|
|
169
|
+
openacp api cancel <session-id>
|
|
291
170
|
|
|
292
|
-
#
|
|
293
|
-
openacp update # Install the latest maintained npm release
|
|
294
|
-
|
|
295
|
-
# Tunnels
|
|
296
|
-
openacp tunnel add <port> [--label name]
|
|
297
|
-
openacp tunnel list
|
|
298
|
-
|
|
299
|
-
# Scoped proxy routing (requires running daemon)
|
|
171
|
+
# Scoped proxy routing
|
|
300
172
|
openacp proxy status
|
|
301
|
-
openacp proxy import
|
|
302
|
-
openacp proxy
|
|
303
|
-
openacp proxy
|
|
304
|
-
openacp proxy set channels.telegram profile:usa
|
|
305
|
-
openacp proxy set agents.codex profile:usa
|
|
173
|
+
openacp proxy import primary --env-file ~/.openacp/secrets/proxy.env
|
|
174
|
+
openacp proxy set channels.telegram profile:primary
|
|
175
|
+
openacp proxy set agents.codex profile:primary
|
|
306
176
|
openacp proxy test --scope channels.telegram
|
|
307
|
-
```
|
|
308
|
-
|
|
309
|
-
The protected JSON file supports a Quick URL mode: use either separate
|
|
310
|
-
`protocol`, `host`, and `port` fields or one write-only `proxyUrl` such as
|
|
311
|
-
`{"proxyUrl":"socks5h://user:password@proxy.example:1080"}`. The two forms are
|
|
312
|
-
mutually exclusive. A URL must include an explicit port; credentials are parsed
|
|
313
|
-
and stored separately, and the original URL is never persisted or returned.
|
|
314
177
|
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
if that guarantee is unavailable, OpenACP refuses the value and directs the
|
|
319
|
-
operator to a mode-0600 CLI/API input file.
|
|
320
|
-
|
|
321
|
-
Use a unique Telegram bot for each OpenACP instance. Command synchronization has
|
|
322
|
-
one heartbeat-backed owner per public bot ID and a second instance will not
|
|
323
|
-
modify the first instance's command menus.
|
|
178
|
+
# Updates
|
|
179
|
+
openacp update
|
|
180
|
+
```
|
|
324
181
|
|
|
325
|
-
|
|
182
|
+
The complete command contract is in [CLI Commands](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/api-reference/cli-commands.md).
|
|
326
183
|
|
|
327
184
|
## Documentation
|
|
328
185
|
|
|
329
|
-
|
|
|
330
|
-
|
|
331
|
-
| [Getting Started](https://
|
|
332
|
-
| [Platform Setup](https://
|
|
333
|
-
| [Using OpenACP](https://
|
|
334
|
-
| [
|
|
335
|
-
| [
|
|
336
|
-
| [Extending](https://
|
|
337
|
-
| [
|
|
338
|
-
| [Troubleshooting](https://openacp.gitbook.io/docs/troubleshooting) | Common issues and FAQ |
|
|
186
|
+
| Area | Maintained reference |
|
|
187
|
+
|------|----------------------|
|
|
188
|
+
| Start and configure | [Getting Started](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/getting-started) · [Self-Hosting](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/self-hosting) |
|
|
189
|
+
| Connect clients | [Platform Setup](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/platform-setup) |
|
|
190
|
+
| Use sessions and commands | [Using OpenACP](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/using-openacp) |
|
|
191
|
+
| Speech, proxy, handoff | [Features](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/features) |
|
|
192
|
+
| CLI, REST, config, env | [API Reference](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/api-reference) |
|
|
193
|
+
| Build plugins and adapters | [Extending](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/extending) |
|
|
194
|
+
| Diagnose failures | [Troubleshooting](https://github.com/an1creator/OpenACP/tree/main/docs/gitbook/troubleshooting) |
|
|
339
195
|
|
|
340
|
-
##
|
|
196
|
+
## Updating and Migration
|
|
341
197
|
|
|
342
|
-
- **Early stage** — OpenACP is under active development; expect breaking changes between minor versions
|
|
343
|
-
- **Single user** — Currently designed for individual use; multi-user/team support is planned
|
|
344
|
-
- **Remote host** — Agents run on the same machine as OpenACP; to use on a remote server, install OpenACP on that server
|
|
345
|
-
- **Agent availability** — Some agents require their own API keys and local installation
|
|
346
|
-
- **Platform features** — Not all messaging platform features are supported equally (e.g., Slack threads vs Telegram forum topics)
|
|
347
|
-
- **No Windows daemon** — Daemon mode (auto-start on boot) currently supports macOS and Linux only
|
|
348
|
-
|
|
349
|
-
## FAQ
|
|
350
|
-
|
|
351
|
-
### Why use Telegram or Discord instead of just the terminal?
|
|
352
|
-
Most AI coding agents are locked to a terminal REPL or IDE. OpenACP lets you send messages, review code diffs, approve or deny actions, and monitor progress from any device — phone, tablet, or browser — without opening a laptop.
|
|
353
|
-
|
|
354
|
-
### How is OpenACP different from MCP?
|
|
355
|
-
MCP (Model Context Protocol) is a standard for giving AI models access to tools and data sources. OpenACP uses the **Agent Client Protocol (ACP)** to manage full coding agent *sessions* — starting agents, streaming output, handling permissions, and routing results to your messaging platform. The two protocols are complementary: your agents can use MCP tools while OpenACP manages the session layer.
|
|
356
|
-
|
|
357
|
-
### Can I auto-approve agent actions?
|
|
358
|
-
Yes. By default, OpenACP shows a permission button for destructive actions. You can configure [auto-approve rules](https://openacp.gitbook.io/docs/using-openacp) to skip confirmation for specific action types (e.g., read-only operations) while still requiring approval for file writes or shell commands.
|
|
359
|
-
|
|
360
|
-
### How do I control API spending?
|
|
361
|
-
Set a monthly budget limit in your config. OpenACP tracks token usage and cost in real time and will pause the agent when the limit is reached. Run `openacp config` to set limits per session.
|
|
362
|
-
|
|
363
|
-
### Can I use a local or self-hosted LLM?
|
|
364
|
-
Yes, if the model has a compatible agent CLI. Any agent that implements the ACP protocol can be registered. Community adapters exist for Ollama and LM Studio — run `openacp agents` to browse available options.
|
|
365
|
-
|
|
366
|
-
### Does speech input only work in Telegram?
|
|
367
|
-
No. STT is part of the shared session pipeline. Telegram already converts voice and audio messages into standard audio attachments, while the REST API and SSE bridge accept base64 audio attachments. Any external adapter gets the same behavior when it submits an attachment with `type: "audio"`. If the selected agent supports native audio, OpenACP passes the audio through; otherwise it transcribes it with the configured STT provider.
|
|
368
|
-
|
|
369
|
-
### What happens if the agent gets stuck or the chat hangs?
|
|
370
|
-
Use `/cancel` in your chat to stop the current session. Run `openacp doctor` to check for connectivity or configuration issues. OpenACP's session persistence means you can resume with full context intact after a restart.
|
|
371
|
-
|
|
372
|
-
### Does OpenACP send my code to the cloud?
|
|
373
|
-
No. OpenACP runs entirely on your machine. AI agents connect directly to your chosen provider using your own API keys. Nothing is routed through OpenACP servers.
|
|
374
|
-
|
|
375
|
-
### Can I use multiple AI agents at the same time?
|
|
376
|
-
Each session uses one agent, but you can run multiple sessions simultaneously — one per thread/topic in your chat. Switch agents between sessions or start a new session with a different agent at any time.
|
|
377
|
-
|
|
378
|
-
### Is OpenACP free?
|
|
379
|
-
Yes. OpenACP is MIT-licensed and free to self-host. You only pay for the AI provider API keys you choose to use.
|
|
380
|
-
|
|
381
|
-
### How do I update OpenACP?
|
|
382
198
|
```bash
|
|
383
199
|
openacp update
|
|
384
200
|
```
|
|
385
201
|
|
|
386
|
-
|
|
387
|
-
finish and then requests a managed daemon restart. Do not run a second npm
|
|
388
|
-
install or stop the service while that update is in progress.
|
|
389
|
-
|
|
390
|
-
To migrate from the upstream npm package:
|
|
202
|
+
The managed updater installs the latest `@n1creator/openacp-cli` release and requests a daemon restart after npm finishes. To migrate an older global installation:
|
|
391
203
|
|
|
392
204
|
```bash
|
|
393
205
|
npm uninstall -g @openacp/cli
|
|
394
206
|
npm install -g @n1creator/openacp-cli@latest
|
|
395
|
-
openacp
|
|
207
|
+
openacp restart
|
|
396
208
|
```
|
|
397
209
|
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
OpenACP grants AI agents access to your filesystem and shell. Before using in production:
|
|
210
|
+
See [Updating](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/self-hosting/updating.md) before changing a production instance.
|
|
401
211
|
|
|
402
|
-
|
|
403
|
-
- Review agent permissions — use the built-in permission gate to approve/deny actions
|
|
404
|
-
- Never expose your OpenACP instance to the public internet without authentication
|
|
405
|
-
- Keep your bot tokens secret — rotate them if compromised
|
|
406
|
-
- See the [Security guide](https://openacp.gitbook.io/docs/self-hosting/security) for hardening recommendations
|
|
212
|
+
## Security
|
|
407
213
|
|
|
408
|
-
|
|
214
|
+
OpenACP grants selected agent processes access to configured workspaces and may allow shell or file operations. Keep connector tokens and provider credentials secret, review permission policy, avoid exposing the local API without authentication, and use process or container isolation where appropriate.
|
|
409
215
|
|
|
410
|
-
|
|
411
|
-
<picture>
|
|
412
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=an1creator/OpenACP&type=Date&theme=dark" />
|
|
413
|
-
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=an1creator/OpenACP&type=Date" />
|
|
414
|
-
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=an1creator/OpenACP&type=Date" />
|
|
415
|
-
</picture>
|
|
416
|
-
</a>
|
|
216
|
+
Follow the [Security guide](https://github.com/an1creator/OpenACP/blob/main/docs/gitbook/self-hosting/security.md) for the current hardening checklist. Report vulnerabilities through the repository's [Security Policy](https://github.com/an1creator/OpenACP/blob/main/SECURITY.md).
|
|
417
217
|
|
|
418
218
|
## Contributing
|
|
419
219
|
|
|
420
|
-
|
|
220
|
+
Read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, project conventions, tests, and pull-request requirements. Project conduct is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
|
|
421
221
|
|
|
422
222
|
## License
|
|
423
223
|
|