Quick Start

Prerequisites

• Docker and Docker Compose
• A Telegram bot token (from @BotFather)
• At least one model provider configured (OpenAI Codex, Ollama, or any OpenAI-compatible endpoint)

Steps

1. Clone the repo

   git clone https://github.com/q15co/q15.git
   cd q15

2. Initialize local secrets

   make compose-secrets-init

   This copies .example templates into local files. Edit the copies, not the templates.

3. Configure your secrets Edit the files under deploy/compose/secrets/:

   • q15_telegram_token — your Telegram bot token
   • github_token — a GitHub personal access token (if using GitHub)
   • moonshot_api_key — Moonshot API key (if using Moonshot models)

4. Set up auth Edit deploy/compose/auth/auth.json with your provider credentials, or use q15-auth to generate it:

   ./bin/q15-auth login --auth-path ./deploy/compose/auth/auth.json

5. Edit agent config Edit deploy/compose/agent-config.yaml to set your providers, models, and Telegram policy. See Agent Config for the full schema.

6. Edit proxy policy Edit deploy/compose/proxy-policy.yaml to set egress rules and secret aliases. See Proxy Policy for the full schema.

7. Bring up the stack

   make compose-up

8. Verify it’s running

   make compose-ps
   make compose-logs SERVICE=q15-agent

9. Send a message Send a message to your Telegram bot. The agent should respond.

Useful commands

make compose-down          # stop the stack
make compose-logs SERVICE=q15-agent  # tail logs
make compose-ps            # show running services

Development setup (without Docker)

If you want to build and run from source:

make project-setup
make verify
make build

This installs the pinned toolchain under ./.tools, runs checks, and builds the four binaries (q15-agent, q15-auth, q15-exec, q15-proxy) into ./bin.