OpenACP is self-hosted so the user and developer are the same person. Consolidated into one unified quickstart page with a natural flow: Install → Setup wizard → Start → Chat. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
147 lines
4.1 KiB
Markdown
147 lines
4.1 KiB
Markdown
# Quick Start
|
|
|
|
This guide gets you from zero to chatting with an AI agent in your Telegram (or Discord, or Slack) in about ten minutes.
|
|
|
|
## What you'll need
|
|
|
|
- **Node.js 20 or later** — check with `node --version`
|
|
- **A bot token** for your chat platform:
|
|
- Telegram: create one via [@BotFather](https://t.me/BotFather)
|
|
- Discord: create one in the [Discord Developer Portal](https://discord.com/developers/applications)
|
|
- Slack: create one at [api.slack.com/apps](https://api.slack.com/apps)
|
|
- **An ACP-compatible agent** installed on your machine (e.g. `claude` CLI, `gemini` CLI)
|
|
|
|
---
|
|
|
|
## Step 1: Install OpenACP
|
|
|
|
```bash
|
|
npm install -g @openacp/cli
|
|
```
|
|
|
|
Verify it installed:
|
|
|
|
```bash
|
|
openacp --version
|
|
```
|
|
|
|
---
|
|
|
|
## Step 2: Run the setup wizard
|
|
|
|
```bash
|
|
openacp
|
|
```
|
|
|
|
The first time you run `openacp`, it detects there's no config and launches an interactive setup wizard that walks you through:
|
|
|
|
1. **Choose your platform** — Telegram, Discord, or Slack
|
|
2. **Enter your bot token** — paste the token you created above
|
|
3. **Validate the token** — confirms it can reach the platform API
|
|
4. **Detect agents** — scans your system for installed ACP-compatible agents
|
|
5. **Set your workspace** — the directory your agents will have access to
|
|
6. **Choose run mode** — foreground (for testing) or daemon (runs in background)
|
|
|
|
Most prompts have sensible defaults — just press Enter to accept them.
|
|
|
|
---
|
|
|
|
## Step 3: Start OpenACP
|
|
|
|
If you chose foreground mode:
|
|
|
|
```bash
|
|
openacp start
|
|
```
|
|
|
|
If you chose daemon mode, it started automatically. Check with:
|
|
|
|
```bash
|
|
openacp status
|
|
```
|
|
|
|
---
|
|
|
|
## Step 4: Chat with your AI agent
|
|
|
|
Open the Telegram group (or Discord server, or Slack channel) linked to your bot and send:
|
|
|
|
```
|
|
/new
|
|
```
|
|
|
|
OpenACP creates a **session** — a dedicated thread between you and an AI agent. On Telegram this becomes a forum topic, on Discord and Slack a thread.
|
|
|
|
Now send a real message:
|
|
|
|
```
|
|
What files are in the src/ directory?
|
|
```
|
|
|
|
You should see:
|
|
|
|
- **Streaming text** — the agent's response arrives piece by piece in real time
|
|
- **Tool calls** — status updates like `🔧 Running: read_file src/main.ts` when the agent reads files or runs commands
|
|
- **Permission requests** — some actions show **Approve** / **Deny** buttons and wait for your response
|
|
- **Auto-naming** — the session topic gets renamed based on your first message
|
|
|
|
---
|
|
|
|
## Step 5: Useful commands
|
|
|
|
| Command | What it does |
|
|
|---|---|
|
|
| `/new` | Start a new session with a fresh agent |
|
|
| `/cancel` | Stop the current response |
|
|
| `/status` | Check the status of your active session |
|
|
| `/menu` | Open the action menu |
|
|
|
|
For the full list, see [Chat Commands](../using-openacp/chat-commands.md).
|
|
|
|
---
|
|
|
|
## What just happened?
|
|
|
|
When you ran `openacp start`, OpenACP:
|
|
|
|
1. Loaded your config from `~/.openacp/config.json`
|
|
2. Connected your bot to the chat platform
|
|
3. Started listening for messages
|
|
|
|
When you sent `/new`, OpenACP:
|
|
|
|
1. Created a new **Session** for you
|
|
2. Spawned an **AgentInstance** — a subprocess running your AI agent via ACP
|
|
3. Routed your message to the agent and streamed the response back to chat
|
|
|
|
---
|
|
|
|
## Your data directory
|
|
|
|
Everything OpenACP stores lives in `~/.openacp/`:
|
|
|
|
| Path | What's in it |
|
|
|---|---|
|
|
| `config.json` | Your configuration (bot token, agent, allowed users) |
|
|
| `sessions.json` | Active and recent session metadata |
|
|
| `usage.json` | Token and cost tracking |
|
|
| `logs/` | Application logs |
|
|
| `files/` | Files shared through the chat |
|
|
| `plugins/` | Installed plugins |
|
|
|
|
To reconfigure at any time:
|
|
|
|
```bash
|
|
openacp onboard
|
|
```
|
|
|
|
---
|
|
|
|
## Next steps
|
|
|
|
- **Platform setup** — detailed guides for [Telegram](../platform-setup/telegram.md), [Discord](../platform-setup/discord.md), and [Slack](../platform-setup/slack.md)
|
|
- **[Configuration](../self-hosting/configuration.md)** — all config options explained
|
|
- **[Agents](../using-openacp/agents.md)** — configure and switch between agents
|
|
- **[Daemon Mode](../self-hosting/daemon-mode.md)** — running OpenACP as a background service
|
|
- **[Voice & Speech](../using-openacp/voice-and-speech.md)** — voice messages and audio responses
|