Anil-matcha/open-dots

Open Dots: Open-Source Alternative to Paid AI Agents

Open Dots is an open-source, self-hosted alternative for people exploring paid AI agent products such as OpenAI Dots, Meta Muse, Grok Bot, Instinct, Manus Cue, Claude Cowork, and ChatGPT agent. The current prototype focuses on coding-agent workflows: run Claude Code tasks from Telegram or the web, review risky actions, connect GitHub, and schedule recurring prompts. Its features differ from those services; it is not a feature-for-feature replacement.

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

▶ Watch the Open Dots demo on YouTube

Status: Prototype / 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.
• Store user credentials encrypted and manage sandbox, task, permission, and schedule records in PostgreSQL.

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.

Quick start

Prerequisites

• uv for Python dependency management
• Node.js (18+) and npm, for the web UI
• Docker (for Postgres)
• Bash (Git Bash on Windows works fine) to use scripts/dev.sh
• A Boat API key for sandbox creation. If

• A Telegram bot token from @BotFather (only

• A public URL the sandbox can reach to call back into your backend for

Configure the environment

cp backend/.env.example backend/.env

Fill in backend/.env:

| Var | Required | Notes | |---|---|---| | BOAT_API_KEY | yes | From the Boat dashboard. | | BOAT_BASE_URL | no | Defaults to https://boat.dev/api/v1. | | BOAT_ORG_ID | see note above | Team/org id (e.g. team_...) to attach to sandbox creation so it bills the org instead of your personal account. | | TOKEN_ENCRYPTION_KEYS | yes | Fernet key used to encrypt stored credentials. Generate with uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())". Comma-separate multiple keys to support rotation. | | TELEGRAM_BOT_TOKEN | only for the bot / Telegram linking | From @BotFather. | | TELEGRAM_BOT_USERNAME | no | Your bot's @username (no @), shown as a clickable link in the web UI. Cosmetic only. | | FRONTEND_ORIGINS | no | Comma-separated origins allowed to call the API from a browser. Defaults to http://localhost:3000. | | HOOK_TOKEN | yes | Shared secret the permission hook's caller (the sandbox) must present, so only your backend's own sandboxes can submit permission decisions. Generate with python -c "import secrets; print(secrets.token_urlsafe(32))". | | PERMISSION_HOOK_BASE_URL | yes | The public URL from the ngrok-or-similar prerequisite above, no trailing slash — e.g. https://your-tunnel.ngrok-free.app. Baked into each sandbox's .claude/settings.json at task start. | | POSTGRES_* | no | Defaults match backend/docker-compose.yml. |

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 starts Postgres via Docker, 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, and the web UI (http://127.0.0.1:3000). 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 ever typed into the chat: the bot posts a one-time code and a github.com/login/device link, the user approves it in their browser, and the bot picks up the result on its own. 4. Any plain text message — runs it as a task in the user's sandbox and replies with the result once it finishes. If the user has connected GitHub, that credential is restored into the sandbox before the task runs too. 5. /schedule — repeats a prompt on a cron schedule (hourly/daily/weekdays/ weekly, always in UTC) instead of running it once. /schedules lists them, /pause//resume//unschedule manage one. Each run is reported back in the chat — the result on success, the error on failure — and a schedule that can't succeed (e.g. an expired login) is paused automatically instead of retrying forever. See Scheduling tasks below.

The web UI covers the same ground from a browser:

1. Get started — either continue as a guest (a local id, no Telegram needed) or link Telegram: the page generates a one-time code, you send /link to the bot, and that links the browser to your real Telegram user id instead. 2. Connect Claude — same OAuth flow as /connect, driven by REST endpoints instead of chat messages (get-or-create the sandbox, start login, paste the code back into the page). 3. Connect GitHub (optional) — same device-flow login as /connect_github: the page shows a one-time code and a github.com/login/device link, and picks up the result on its own once you approve it — no code to paste back. 4. Submit a task — a prompt box that submits to the same POST /api/v1/tasks endpoint, polls for the result, and lists past tasks for that user. Finished tasks can be replied to in place to continue that same Claude conversation, instead of starting a new unrelated one. Checking "Repeat this on a schedule" turns the same prompt into a recurring schedule instead (POST /api/v1/schedules) — pick a frequency (hourly/daily/weekdays/weekly) and a time, in the browser's own timezone. Schedules are listed below the composer with pause/resume/delete controls. See Scheduling tasks.

Telegram bot ─┐
              ├── FastAPI backend ── PostgreSQL
Next.js web UI┘          ├── disposable sandboxes (Boat provider)
                         ├── permission prompts and rules
                         └── task and schedule services