Open Dots: Open-Source Alternative to Paid AI Agents

Open Dots is an open-source, self-hosted workspace for running coding-agent tasks, aimed at people exploring paid AI agent products such as OpenAI Dots, Meta Muse, Grok Bot, Instinct, Manus Cue, Claude Cowork, and ChatGPT agent. Today it wraps the Claude Code CLI: run tasks from Telegram or the web, review risky actions before they run, connect GitHub, schedule recurring prompts, and chat with a locally signed-in Claude from a desktop app. It supports Claude only, has named agents but no multi-agent features yet, and is not a feature-for-feature replacement for those services. See docs/ROADMAP.md for what is planned.

Both interfaces use the same API, sandbox, and credentials for each user.

Status: Active development. See Known limitations before running it for others.

Contents

• What it does
• Why Open Dots
• Quick start
• Using Open Dots
• Scheduling tasks
• Permission prompts
• Architecture
• Project layout
• Known limitations
• Contributing

What it does

• Run coding-agent tasks in disposable sandboxes from Telegram or a browser.
• Connect Claude through its OAuth login flow and optionally connect a user's GitHub account.
• Ask for approval before risky actions such as file writes, shell commands, and Git pushes.
• Continue completed tasks in the same Claude conversation from the web UI.
• Schedule recurring prompts and receive run results in Telegram (Boat sandboxes).
• Run routines on your local agents (no Boat): cron, weekday, interval or one-off schedules with timezones, webhook triggers, run history, missed-run tracking, restart recovery and an in-app notification feed (see docs/ROUTINES.md).
• Keep durable local conversations (threads) with streaming answers, a tool-call timeline, inline approvals, Stop, and rename/archive/delete, using your own signed-in claude CLI (opt-in; see Local Claude).
• Run as a desktop app from a source checkout, or from unsigned installers built by the release workflow (experimental; see Desktop app).
• Store user credentials encrypted and manage sandbox, task, permission, thread, and schedule records in PostgreSQL (default) or SQLite (experimental, no Docker).

Why Open Dots

Open Dots gives individuals and developers an inspectable workspace they can run themselves, with coding tasks, visible approval steps, and local control over the app and its data. The web UI supports guest use without Telegram and can also link to a Telegram identity. Read Known limitations before running it for others.

Quick start

Prerequisites

• uv for Python dependency management
• Node.js (20.9+) and npm, for the web UI (required by Next.js 16)
• Docker (for Postgres; not needed with the experimental SQLite option, see DATABASE_BACKEND below)
• Bash (Git Bash on Windows works fine) to use scripts/dev.sh
• Optionally, a Boat API key for sandbox creation. If it belongs to a personal account that also has an org/team on a paid plan, you also need that org's id (see BOAT_ORG_ID below) — otherwise sandbox creation bills the personal account and returns 402 Payment Required.
• A Telegram bot token from @BotFather (only needed if you want to run the bot, or let people link the web UI to Telegram — the web UI's guest mode works without it)
• A public URL the sandbox can reach to call back into your backend for permission decisions (see Permission prompts) — in local dev this means tunneling your backend with ngrok or similar; not needed to run the app, only for any task that triggers a risky action (writing files, shell commands, etc.) to actually get a decision instead of hanging until it times out.

Configure the environment

scripts/dev.sh creates backend/.env from the example on first run, saves a private encryption key and webhook token, and preserves existing secrets on later runs. It also selects a trusted CA bundle for outbound HTTPS. Set SSL_CERT_FILE in your shell or in backend/.env to use a custom PEM bundle; certificate and hostname verification remain enabled. When Boat is configured, the script checks its TLS certificate before starting services, without sending credentials or creating a sandbox. You can start the API and web UI without a Boat key; sandbox features then remain unavailable.

For manual setup, copy the example yourself:

cp backend/.env.example backend/.env

Fill in backend/.env:

The web UI (frontend/) has its own .env.example — scripts/dev.sh copies it to .env.local automatically on first run. Copy it yourself if you're running the frontend separately, and point NEXT_PUBLIC_API_BASE_URL at the backend if you're not using the defaults.

Start the app

./scripts/dev.sh

From the repo root, this prepares local configuration, starts Postgres via Docker when PostgreSQL is selected, waits for it to be healthy, installs backend and frontend dependencies, runs migrations, and starts the FastAPI app (http://127.0.0.1:8000, docs at /docs), the Telegram bot when configured, and the web UI (http://127.0.0.1:3000). Without a Boat key, the API and web UI still start, while sandbox tasks stay unavailable. Ctrl+C stops everything it started (Postgres keeps running — docker compose -f backend/docker-compose.yml down to stop it too).

Skip pieces you don't need:

./scripts/dev.sh --no-bot        # API + web UI only
./scripts/dev.sh --no-frontend   # API + bot only

Run the pieces manually

cd backend
docker compose up -d                      # Postgres
uv sync                                   # install deps
uv run alembic upgrade head               # migrations
uv run fastapi dev app/main.py            # API (terminal 1)
uv run python -m app.telegram_bot         # bot (terminal 2)

cd ../frontend
npm install && npm run dev                # web UI (terminal 3)

Using Open Dots

The Telegram bot walks a user through:

1. /connect — creates a sandbox and starts an OAuth login for the agent provider (currently Claude) inside it.
2. Pasting the OAuth code — the bot reads the resulting credential file out of the sandbox, encrypts it, and stores it.
3. /connect_github (optional) — links the user's own GitHub account via device-flow login, so tasks that git push do so as that user rather than a shared/anonymous identity. No token is ev