{"id":45825296,"url":"https://github.com/mtzanidakis/praktor","last_synced_at":"2026-05-11T09:55:39.689Z","repository":{"id":340779896,"uuid":"1157160660","full_name":"mtzanidakis/praktor","owner":"mtzanidakis","description":"Multi-agent Claude Code orchestrator with Telegram I/O, Docker isolation, swarm patterns, and Mission Control UI","archived":false,"fork":false,"pushed_at":"2026-05-06T13:19:38.000Z","size":1214,"stargazers_count":25,"open_issues_count":0,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T15:18:45.238Z","etag":null,"topics":["agent-orchestration","agent-swarm","ai-agents","browser-automation","claude-agent-sdk","claude-code","docker","golang","mcp","mission-control","multi-agent","nats","nix","personal-ai-assistant","scheduled-tasks","self-hosted","telegram-bot","voice-ai"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mtzanidakis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-13T13:59:23.000Z","updated_at":"2026-05-06T13:19:06.000Z","dependencies_parsed_at":"2026-03-12T23:02:07.209Z","dependency_job_id":"b1460b79-32cf-4c7e-ae49-d7e2fd433abf","html_url":"https://github.com/mtzanidakis/praktor","commit_stats":null,"previous_names":["mtzanidakis/praktor"],"tags_count":61,"template":false,"template_full_name":null,"purl":"pkg:github/mtzanidakis/praktor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtzanidakis%2Fpraktor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtzanidakis%2Fpraktor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtzanidakis%2Fpraktor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtzanidakis%2Fpraktor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mtzanidakis","download_url":"https://codeload.github.com/mtzanidakis/praktor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mtzanidakis%2Fpraktor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32889971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-10T13:40:02.631Z","status":"online","status_checked_at":"2026-05-11T02:00:05.975Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","agent-swarm","ai-agents","browser-automation","claude-agent-sdk","claude-code","docker","golang","mcp","mission-control","multi-agent","nats","nix","personal-ai-assistant","scheduled-tasks","self-hosted","telegram-bot","voice-ai"],"created_at":"2026-02-26T21:53:38.556Z","updated_at":"2026-05-11T09:55:39.674Z","avatar_url":"https://github.com/mtzanidakis.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"ui/public/favicon.svg\" width=\"80\" alt=\"Praktor logo\" /\u003e\n\u003c/p\u003e\n\n# Praktor\n\nPersonal AI agent assistant. A single Go binary that receives messages from Telegram, routes them to named agents running Claude Code in isolated Docker containers, and serves a real-time Mission Control web UI. Self-hosted, single-binary deployment via Docker Compose.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/architecture.svg\" alt=\"Architecture diagram\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n## Features\n\n- **Mission Control** — Real-time dashboard with WebSocket updates\n- **Telegram I/O** — Chat with your agents from your phone\n- **Telegram commands** — `/start`, `/stop`, `/reset`, `/nix`, `/agents`, `/commands`\n- **Named agents** — Multiple agents with distinct roles, models, and configurations\n- **Smart routing** — `@agent_name` prefix or AI-powered classification via the default agent\n- **Per-agent isolation** — Each agent runs in its own Docker container with its own filesystem\n- **Persistent memory** — Per-agent SQLite memory database with hybrid search (FTS5 keyword + vector semantic similarity via all-MiniLM-L6-v2) for storing and recalling facts across sessions\n- **Agent identity** — Each agent has an `AGENT.md` for personality and expertise, editable from Mission Control or by agents themselves\n- **User profile** — Agents know who you are via `USER.md`, editable from Mission Control or by agents themselves\n- **Scheduled tasks** — Cron, interval, or one-shot jobs that run agents and deliver results via Telegram. Multiple tasks execute in parallel (up to 3 concurrent) with independent sessions\n- **Secure vault** — AES-256-GCM encrypted secrets injected as env vars or files at container start, never exposed to the LLM\n- **Web \u0026 browser access** — Agents can search the web and automate browsers via [agent-browser](https://github.com/vercel-labs/agent-browser)\n- **Voice messages** — Send voice messages in any language; they're transcribed via OpenAI Whisper and delivered as text. Optional TTS replies voice messages back using OpenAI TTS\n- **Email via AgentMail** — Agents can send and receive email via [AgentMail](https://agentmail.to/). Configure an inbox per agent and the gateway handles real-time email routing\n- **Hot config reload** — Edit `praktor.yaml` and changes apply automatically, no restart needed\n- **Nix package manager** — Agents can install packages on demand (Python, ffmpeg, LaTeX, etc.) via MCP tools or the `/nix` Telegram command\n- **Agent extensions** — Per-agent MCP servers, plugins, and skills, managed via Mission Control\n- **Agent swarms** — Graph-based multi-agent orchestration with fan-out, pipeline, and collaborative patterns\n- **Backup \u0026 restore** — Back up and restore all Docker volumes as zstd-compressed tarballs via CLI\n\n## Prerequisites\n\n- Docker and Docker Compose\n- A Telegram bot token ([create one with @BotFather](https://t.me/BotFather))\n- A Claude authentication method: [Anthropic API key](https://console.anthropic.com/) or Claude Code OAuth token (`claude setup-token`)\n- (Optional) An [OpenAI API key](https://platform.openai.com/api-keys) for voice message transcription and text-to-speech\n\n## Getting Started\n\n### 1. Clone and Configure\n\n```sh\ngit clone https://github.com/mtzanidakis/praktor.git\ncd praktor\ncp config/praktor.example.yaml config/praktor.yaml\ncp .env.example .env \u0026\u0026 chmod 0600 .env\n```\n\nEdit `.env` and fill in your credentials (see comments in the file for details). Set `DOCKER_GID` to the group ID of the `docker` group on your host so the non-root container user can access the Docker socket:\n\n```sh\ngrep docker /etc/group    # look for the docker group GID\n```\n\nEdit `config/praktor.yaml` to define your agents:\n\n```yaml\ntelegram:\n  allow_from: []            # Telegram user IDs (empty = allow all)\n  main_chat_id: 0           # Chat ID for scheduled task / swarm results\n\ndefaults:\n  model: \"claude-sonnet-4-6\"\n  max_running: 5\n  idle_timeout: 10m\n\nagents:\n  general:\n    description: \"General-purpose assistant for everyday tasks\"\n    nix_enabled: true\n  coder:\n    description: \"Software engineering specialist\"\n    model: \"claude-opus-4-7\"\n    nix_enabled: true\n    env:\n      GITHUB_TOKEN: \"secret:github-token\"    # Resolved from vault\n  researcher:\n    description: \"Web research and analysis\"\n    allowed_tools: [WebSearch, WebFetch, Read, Write]\n\nrouter:\n  default_agent: general\n```\n\n### 2. Build and Run\n\n```sh\ndocker compose build agent    # Build the agent image locally\ndocker compose up -d          # Start the stack (pulls gateway from GHCR)\ndocker compose logs -f        # Watch logs\n```\n\nThe agent image must be built locally because it bundles proprietary third-party software that cannot be redistributed. See [Third-Party Notice](#third-party-notice) for details.\n\nMission Control is available at `http://localhost:8080`.\n\n### 3. Start Chatting\n\nOpen Telegram and send a message to your bot. Praktor routes it to the right agent, spins up a container, and responds. Use `@agent_name` to target a specific agent, or let smart routing classify the message automatically:\n\n```\nHello!                              → smart routing picks best agent\n@coder fix the login bug            → explicit routing to coder\n@researcher find papers on RAG      → explicit routing to researcher\n```\n\nRouting works in 3 tiers: `@agent_name` prefix → AI-powered classification via default agent → default agent fallback.\n\nFor a secure setup without exposed ports, see [Production Deployment](https://github.com/mtzanidakis/praktor/wiki/Production-Deployment).\n\n## Upgrading\n\nPull the latest code, images, and rebuild the agent:\n\n```sh\n./scripts/upgrade.sh\n```\n\nThen restart the stack:\n\n```sh\ndocker compose up -d\n```\n\n## Documentation\n\nSee the **[Wiki](https://github.com/mtzanidakis/praktor/wiki)** for detailed documentation on all features:\n\n[Hot Config Reload](https://github.com/mtzanidakis/praktor/wiki/Hot-Config-Reload) · [Vault](https://github.com/mtzanidakis/praktor/wiki/Vault) · [Voice Messages](https://github.com/mtzanidakis/praktor/wiki/Voice-Messages) · [Browser Automation](https://github.com/mtzanidakis/praktor/wiki/Browser-Automation) · [AgentMail](https://github.com/mtzanidakis/praktor/wiki/AgentMail) · [Agent Extensions](https://github.com/mtzanidakis/praktor/wiki/Agent-Extensions) · [Agent Swarms](https://github.com/mtzanidakis/praktor/wiki/Agent-Swarms) · [Nix Package Manager](https://github.com/mtzanidakis/praktor/wiki/Nix-Package-Manager) · [Backup \u0026 Restore](https://github.com/mtzanidakis/praktor/wiki/Backup-and-Restore) · [Production Deployment](https://github.com/mtzanidakis/praktor/wiki/Production-Deployment)\n\n## Getting Help\n\nAfter cloning the repo, you can use [Claude Code](https://docs.anthropic.com/en/docs/claude-code) to get help with any aspect of Praktor. The project includes a detailed `CLAUDE.md` that gives Claude full context about the architecture, configuration, and available APIs.\n\n```sh\ngit clone https://github.com/mtzanidakis/praktor.git\ncd praktor\nclaude\n```\n\nFor example, you can ask Claude Code things like:\n\n- \"How do I install an MCP server on a Praktor agent?\"\n- \"How do I add a new agent to my configuration?\"\n- \"How do I set up secrets for an agent?\"\n\n## Development\n\n### Toolchain (mise)\n\nLocal tooling is pinned in `mise.toml`. With [mise](https://mise.jdx.dev) installed, run:\n\n```sh\nmise install                 # Provision go, golangci-lint, node, nats, jq\n```\n\nThis matches the versions used in CI, so `make lint` and `go test` behave identically locally and on GitHub Actions. `sqlite3` is expected from the system package manager.\n\n### Common commands\n\n```sh\ngo mod download              # Install Go dependencies\nmake dev                     # Run the gateway locally\nmake test                    # Run tests\nmake lint                    # Run golangci-lint\n```\n\nMission Control with hot reload:\n\n```sh\ncd ui \u0026\u0026 npm install \u0026\u0026 npm run dev    # Vite dev server on :5173, proxies /api to :8080\n```\n\n## License\n\nSee [LICENSE](LICENSE).\n\n## Third-Party Notice\n\nThis project integrates with third-party tools that have their own licenses and terms of service. In particular, [Claude Code](https://github.com/anthropics/claude-code) and the [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-typescript) are proprietary software by Anthropic and subject to [Anthropic's Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms). They are not included in this repository — users must install them at build time and are responsible for complying with Anthropic's terms. Pre-built Docker images containing these components should not be redistributed without Anthropic's permission.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtzanidakis%2Fpraktor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmtzanidakis%2Fpraktor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmtzanidakis%2Fpraktor/lists"}