Getting Started with OpenACP: A Complete Setup Guide

You have heard about OpenACP -- the free, open-source bridge that connects 28+ AI coding agents to Telegram, Discord, and Slack. You are intrigued. But how do you actually set it up? This guide walks you through every step, from a fresh machine to your first AI-powered conversation, with detailed explanations and troubleshooting tips along the way.

By the end of this article, you will have a fully working OpenACP setup that lets you control AI coding agents from your phone, your desktop, or any device with a messaging app. The entire process takes less than five minutes if you already have the prerequisites, and less than fifteen minutes if you are starting from scratch.

Prerequisites

Before installing OpenACP, you need two things: Node.js and at least one AI coding agent. Let us walk through each.

Node.js 20 or Higher

OpenACP is built with TypeScript and runs on Node.js. You need version 20 or higher. To check if you already have Node.js installed and which version you have, open your terminal and run:

node --version

If you see v20.0.0 or higher, you are good to go. If you see an older version or a "command not found" error, you need to install or update Node.js. The easiest way on macOS is with Homebrew:

# macOS with Homebrew
brew install node

# Or using nvm (recommended for managing multiple versions)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

On Linux, you can use your package manager or nvm. On Windows, download the installer from nodejs.org. If you are using a version manager like nvm, fnm, or asdf, just install version 20 or the latest LTS release.

At Least One AI Coding Agent

OpenACP does not include AI agents itself -- it connects to agents that you have installed separately. You need at least one agent installed and working on your system. The most common choices are:

• Claude Code by Anthropic -- install with npm install -g @anthropic-ai/claude-code
• Gemini CLI by Google -- install with npm install -g @anthropic-ai/gemini-cli
• Codex CLI by OpenAI -- install with npm install -g @openai/codex

Each agent has its own API key requirements. Make sure you have set up your API key for whichever agent you plan to use. For Claude Code, that means an Anthropic API key. For Gemini CLI, a Google AI API key. For Codex CLI, an OpenAI API key. Consult each agent's documentation for key setup instructions.

You do not need all agents installed -- just one is enough to get started. You can always add more later.

A Messaging Platform Account

You also need an account on at least one of the supported messaging platforms: Telegram, Discord, or Slack. If you do not have a preference, we recommend Telegram for the best experience. It has the richest feature set in OpenACP, including forum topics, voice messages, and streaming responses. It is also the easiest to set up because creating a Telegram bot is free and takes about two minutes.

Installation

Installing OpenACP is a single command. Open your terminal and run:

npm install -g @openacp/cli

This installs the openacp command globally on your system. The current version is 0.6.10. The package is lightweight -- it installs quickly and does not have heavy native dependencies. You can verify the installation by running:

openacp --version

If you see the version number, the installation was successful. If you get a permission error on macOS or Linux, you may need to fix your npm global prefix or use sudo (though fixing permissions is preferred over using sudo for global npm packages).

For those who prefer not to install globally, you can also run OpenACP directly with npx:

npx @openacp/cli

This downloads and runs the latest version without installing it permanently. It is a great way to try OpenACP before committing to a global install.

The Setup Wizard

Once installed, start OpenACP by simply running:

openacp

This launches the interactive setup wizard. The wizard is designed to guide you through every decision with clear explanations and sensible defaults. It runs entirely in your terminal and does not require a browser. Let us walk through each step in detail.

Step 1: Choose Your Platform

The first question the wizard asks is which messaging platform you want to use. You will see a list with three options:

? Which platform would you like to connect?
  > Telegram
    Discord
    Slack

Use the arrow keys to select your platform and press Enter. Each platform has different setup requirements, which the wizard will guide you through in the next step. As mentioned earlier, Telegram offers the richest experience and the simplest bot setup process. Discord is great for teams that already use it, and Slack is ideal for corporate environments where Slack is the standard communication tool.

Step 2: Connect Your Bot

This step varies depending on which platform you chose. The wizard provides platform-specific instructions right in the terminal.

Telegram Bot Setup

For Telegram, you need to create a bot through BotFather, Telegram's official bot creation tool. The wizard will display instructions like this:

1. Open Telegram and search for @BotFather.
2. Send the command /newbot.
3. Choose a display name for your bot (e.g., "My OpenACP Bot").
4. Choose a username for your bot (must end in "bot", e.g., "my_openacp_bot").
5. BotFather will give you an API token. Copy it.
6. Paste the token into the wizard when prompted.

The entire process takes about two minutes. The bot token looks something like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz. Keep it secret -- anyone with this token can control your bot. The wizard stores it securely in your local configuration file.

For the best Telegram experience, you should also enable forum topics in your Telegram group. This allows OpenACP to create a separate topic for each coding session, keeping everything organized. To enable forum topics, go to your group settings, tap "Topics", and enable the feature. Then add your bot to the group and make it an admin.

Discord Bot Setup

Discord requires creating a bot application through the Discord Developer Portal (discord.com/developers). You need to create an application, add a bot user, copy the bot token, and invite the bot to your server with appropriate permissions. The wizard guides you through each step, including generating the correct OAuth2 invite URL with the required permissions (Send Messages, Read Messages, Create Threads, Manage Threads, Use Slash Commands).

Slack Bot Setup

Slack requires creating a Slack App through api.slack.com/apps. You will need to configure Socket Mode (which OpenACP uses for firewall-friendly connections), add the necessary bot scopes, install the app to your workspace, and provide the bot token and app token to the wizard. Slack's setup is the most involved of the three platforms, but the wizard walks you through every step with detailed instructions.

Step 3: Pick Your Workspace

Next, the wizard asks you to select a workspace directory. This is the directory where your AI agent will operate -- where it can read and write files, run commands, and perform its work. By default, the wizard suggests your current directory, but you can specify any path:

? Select workspace directory:
  > /home/you/projects/my-app
    /home/you/projects
    Browse...

Choose the directory that contains the project you want to work on. The AI agent will have access to files within this directory (subject to the agent's own security constraints). You can change the workspace later by updating your configuration file or running the wizard again.

Step 4: Select Your Agent

Now comes the fun part -- choosing which AI coding agent to use. The wizard displays a list of all 28+ supported agents, organized by distribution type:

? Which agent would you like to use?
  > Claude Code (Anthropic)
    Gemini CLI (Google)
    Codex CLI (OpenAI)
    GitHub Copilot
    Cursor
    Cline
    goose (Block)
    Amp
    Auggie CLI (Augment Code)
    Junie (JetBrains)
    Kilo
    Qwen Code (Alibaba)
    ...

Select the agent you have installed and configured. If you are unsure which to choose, Claude Code is an excellent default -- it has strong coding capabilities, excellent context understanding, and works seamlessly with OpenACP. The wizard will verify that the selected agent is installed and accessible on your system.

Step 5: Choose Your Run Mode

Finally, the wizard asks how you want to run OpenACP:

? How would you like to run OpenACP?
  > Interactive (foreground)
    Daemon (background)

Interactive mode runs OpenACP in the foreground of your terminal. You can see logs in real time, which is useful for debugging or when you want to keep an eye on what is happening. Press Ctrl+C to stop.

Daemon mode runs OpenACP as a background process. It starts up, detaches from your terminal, and continues running even after you close the terminal window. This is the recommended mode for daily use. You can manage the daemon with commands like openacp stop and openacp status.

Your First Message

With the setup wizard complete, OpenACP is running and connected to your messaging platform. It is time to send your first message.

Open your messaging app (Telegram, Discord, or Slack), navigate to the channel or chat where your bot is active, and type a message. Something simple to start:

Hello! Can you tell me what files are in the current directory?

Within a second or two, you should see the AI agent respond. The response streams in real time -- you will see text appearing progressively as the agent generates it. If the agent needs to perform an action (like listing files), it will request permission first. You will see buttons in the chat to approve or deny the action.

Try pressing the approve button. The agent will execute the command and show you the results. Congratulations -- you are now controlling an AI coding agent from your messaging app.

Here are some more interesting prompts to try for your first session:

# Ask the agent to analyze your project
"Give me an overview of this project's architecture."

# Ask it to find and fix a bug
"Look at the login function in auth.js. Is there a potential security issue?"

# Ask it to write new code
"Create a new utility function that validates email addresses.
Add tests for it too."

# Ask it to refactor
"Refactor the database module to use connection pooling."

Understanding Sessions

One of OpenACP's most powerful concepts is sessions. A session is a persistent conversation with an AI agent, tied to a specific workspace and platform thread. Sessions are important because they maintain context -- the agent remembers everything you have discussed within a session, including files it has read, changes it has made, and decisions you have discussed.

On Telegram, each forum topic is a session. On Discord, each thread is a session. On Slack, each channel thread is a session. You can have multiple sessions running simultaneously, each with its own agent and workspace. This is incredibly powerful for multitasking -- you might have Claude Code working on your backend API in one session while Gemini CLI handles your frontend in another.

Sessions support several advanced features:

• Context resume -- powered by Entire.io integration, sessions can resume context even after an agent process restarts. Your conversation history and file context are preserved.
• Session transfer -- the /handoff command lets you transfer a session from one platform to another. Start a session in Telegram, then hand it off to Slack. The context follows.
• Auto-naming -- sessions automatically get descriptive names based on the conversation content, so your Telegram topics and Discord threads have meaningful titles.

Configuration Deep Dive

After the setup wizard completes, your configuration is stored at ~/.openacp/config.json. Understanding this file helps you customize OpenACP beyond what the wizard offers. Here is a breakdown of the key configuration sections:

{
  "platform": "telegram",
  "telegram": {
    "token": "your-bot-token",
    "groupId": -1001234567890
  },
  "workspace": "/home/you/projects/my-app",
  "agent": "claude-code",
  "daemon": false,
  "api": {
    "port": 21420,
    "enabled": true
  },
  "voice": {
    "enabled": true,
    "stt": "groq",
    "tts": "edge"
  },
  "usage": {
    "tracking": true,
    "budget": null
  },
  "tunnel": {
    "provider": null
  }
}

Let us examine each section:

• platform -- which messaging platform to use (telegram, discord, or slack).
• telegram/discord/slack -- platform-specific settings including bot tokens and target channels or groups.
• workspace -- the directory the agent operates in.
• agent -- which AI agent to use.
• daemon -- whether to run in background mode.
• api -- REST API settings. The API runs on port 21420 by default and allows programmatic control of OpenACP.
• voice -- voice message settings. Groq STT (speech-to-text) and Edge TTS (text-to-speech) are both free services.
• usage -- usage tracking and budget settings. You can set a maximum budget to prevent runaway costs.
• tunnel -- tunneling settings for remote access (Cloudflare, ngrok, bore, or Tailscale).

Any setting can also be overridden with environment variables using the OPENACP_ prefix. For example, OPENACP_PLATFORM=discord overrides the platform setting. This is useful for Docker deployments or CI/CD environments where you do not want to store configuration in a file.

Advanced Features Worth Exploring

Once you have the basics working, there are several advanced features worth exploring:

The REST API

OpenACP exposes a REST API on port 21420 that lets you control everything programmatically. You can create sessions, send messages, check status, and manage agents through HTTP requests. This is powerful for building automation on top of OpenACP -- for example, triggering an AI coding session from a CI/CD pipeline or a monitoring alert.

The Plugin System

OpenACP supports plugins distributed through npm. Plugins can extend OpenACP's functionality in various ways -- adding new commands, integrating with additional services, or customizing behavior. The plugin system uses npm's package infrastructure, making it easy to discover, install, and manage plugins.

Doctor Diagnostics

If something is not working right, OpenACP includes a diagnostic tool that checks your setup for common issues. Run openacp doctor to get a comprehensive report on your configuration, agent availability, platform connectivity, and system requirements. It is the first thing to try when troubleshooting.

Monaco File Viewer

When an agent reads or modifies files, OpenACP can render them in a Monaco-based file viewer (the same editor that powers VS Code). This gives you syntax-highlighted, line-numbered file views directly in your messaging app, making it easy to review code changes without switching to your editor.

Troubleshooting Common Issues

Even with the best setup wizard, things occasionally go wrong. Here are the most common issues and their solutions:

"Agent not found" Error

This means the AI agent you selected is not installed or not in your PATH. Make sure you have installed the agent globally (e.g., npm install -g @anthropic-ai/claude-code) and that the command works in your terminal. Run the agent directly to verify it is working before trying again with OpenACP.

"Bot token invalid" Error

Double-check that you copied the full bot token from BotFather (Telegram), the Developer Portal (Discord), or api.slack.com (Slack). Bot tokens are long strings with no spaces. Even a single missing character will cause authentication to fail.

Messages Not Appearing

If the bot is online but not responding to messages, check that it has been added to the correct group or channel and has the necessary permissions. On Telegram, the bot needs to be a group admin to read messages in forum topics. On Discord, it needs the appropriate permissions. On Slack, it needs to be invited to the channel.

Permission Buttons Not Working

If you see permission request messages but the buttons do not work, make sure your bot has "inline keyboard" permissions (Telegram) or "interaction" permissions (Discord). This is usually set up automatically, but some platform-level restrictions can interfere.

Streaming Not Working

If responses appear all at once instead of streaming, this is usually a rate limiting issue on the messaging platform side. Telegram has rate limits on message edits (which is how streaming works). OpenACP handles this gracefully by batching updates, but very fast responses from the agent might appear to "jump" rather than stream smoothly.

Next Steps

Now that you have OpenACP up and running, here are some suggested next steps to deepen your experience:

1. Try voice messages -- if you are on Telegram, send a voice message to your bot. Watch as it gets transcribed and sent to your AI agent. It is like having a conversation with your codebase. See our Telegram guide for details.
2. Explore the ACP Registry -- learn about all 28+ supported agents and find the best one for different tasks. Our ACP Registry guide covers each agent in detail.
3. Set up multiple agents -- configure different agents for different projects. Use Claude Code for complex architecture work and Codex CLI for quick fixes.
4. Enable daemon mode -- once you are comfortable with OpenACP, switch to daemon mode so it runs in the background. You will forget it is there until you need it.
5. Explore the REST API -- build automation on top of OpenACP. Trigger coding sessions from webhooks, integrate with your CI/CD pipeline, or build custom dashboards.
6. Compare with alternatives -- see how OpenACP stacks up against paid alternatives in our comparison guide.

OpenACP is under active development with new features and agent support being added regularly. Star the GitHub repository to stay updated, and consider contributing if you find a bug or have a feature idea. The community is welcoming and the codebase is well-structured TypeScript -- a great open-source project to contribute to.

Welcome to the future of AI-assisted development. Your coding agents are now in your pocket.

npm install -g @openacp/cli && openacp