0xmrpeter 004a8ff1b1 docs: merge for-users and for-developers into single quick-start guide
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>
2026-03-25 23:54:05 +07:00

4.1 KiB

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:
  • An ACP-compatible agent installed on your machine (e.g. claude CLI, gemini CLI)

Step 1: Install OpenACP

npm install -g @openacp/cli

Verify it installed:

openacp --version

Step 2: Run the setup wizard

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:

openacp start

If you chose daemon mode, it started automatically. Check with:

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.


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:

openacp onboard

Next steps