Quickstart

Greenlight has two quick paths: deploy with Docker for production or self-hosting, or run hybrid locally for development. Pick the section that matches your goal.

Self-hosting quickstart

Deploy the API, Admin UI, and Postgres with published GHCR images.

1. Clone and configure

git clone https://github.com/HashTerm/greenlight.git
cd greenlight
npm run env:ensure -- --profile self-host

That creates .env.self-host from .env.self-host.example with generated secrets (when missing). Or copy .env.self-host.example and set secrets yourself.

Confirm at least these are set:

• PUBLIC_WEBHOOK_URL — public HTTPS API host (no trailing slash)
• POSTGRES_PASSWORD
• WEBHOOK_SECRET
• CALLBACK_SIGNING_SECRET
• AUTH_SECRET
• GREENLIGHT_API_KEY (bootstraps admin key when api_keys is empty and USE_AUTH=true)

2. Start the stack

docker compose -f docker-compose.self-host.yml --env-file .env.self-host up -d
curl http://localhost:8100/healthz   # or your routed API URL

3. Route traffic

Point your reverse proxy or platform domains at:

For PaaS deploy steps, see Dokploy or Coolify.

4. Create an admin account

1. Open {ADMIN_UI_URL}/setup
2. Enter email and password (min 8 characters)
3. Sign in at /login

5. Register a Telegram prompt channel

Create a bot with @BotFather , add it to a group, and copy the chat ID (negative for groups). Then (replace $API_BASE with your public API URL):

export GREENLIGHT_API_KEY="$(grep '^GREENLIGHT_API_KEY=' .env.self-host | cut -d= -f2-)"
export API_BASE="https://greenlight.example.com"
 
curl -X POST "$API_BASE/v1/channels/new" \
  -H "X-API-Key: $GREENLIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "my-telegram-prompts",
    "platform": "telegram",
    "target_chat_id": "-1001234567890",
    "credentials": { "bot_token": "123456789:YOUR_TOKEN" },
    "channel_type": "PROMPT"
  }'

Or use Admin UI → Channels → Add channel.

For webhook-based platforms (Slack, Teams, Discord, and others), configure:

{PUBLIC_WEBHOOK_URL}/webhooks/{organization_id}/{platform}/{channel_id}

6. Send a test prompt

curl -X POST "$API_BASE/v1/prompts/new" \
  -H "X-API-Key: $GREENLIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "my-telegram-prompts",
    "text": "Ready to deploy v2.4.1?",
    "options": ["Deploy", "Cancel"],
    "callback_url": "https://your-agent.example.com/on_answer"
  }'

You should see the prompt in Telegram. Tap a button to complete the loop.

Full Compose and Swarm reference: Self-Hosting Docker.

Development quickstart

Run Greenlight on your machine for hacking on core/, ui/, and docs-site/.

1. Clone and configure

npm run setup

That creates .env from .env.example with generated secrets (when missing), installs dependencies, starts Postgres, and applies migrations.

Env only:

npm run env:ensure                         # .env (dev)

For local Telegram testing, PUBLIC_WEBHOOK_URL=http://localhost:8100 is enough (Telegram uses long polling when no public HTTPS URL is required).

2. Start (hybrid — recommended)

Postgres in Docker; API, admin UI, and docs on the host with hot reload:

npm run setup          # first time (if not already)
npm run dev
curl http://localhost:8100/healthz

Full Docker (optional):

npm run docker:full

3. Create an admin account

1. Open http://localhost:3001/setup 
2. Enter email and password (min 8 characters)
3. Sign in at /login

4. Register a Telegram prompt channel

Create a bot with @BotFather , add it to a group, and copy the chat ID (negative for groups). Then:

export GREENLIGHT_API_KEY="$(grep '^GREENLIGHT_API_KEY=' .env | cut -d= -f2-)"
 
curl -X POST http://localhost:8100/v1/channels/new \
  -H "X-API-Key: $GREENLIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "my-telegram-prompts",
    "platform": "telegram",
    "target_chat_id": "-1001234567890",
    "credentials": { "bot_token": "123456789:YOUR_TOKEN" },
    "channel_type": "PROMPT"
  }'

Or use Admin UI → Channels → Add channel.

5. Send a test prompt

curl -X POST http://localhost:8100/v1/prompts/new \
  -H "X-API-Key: $GREENLIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "my-telegram-prompts",
    "text": "Ready to deploy v2.4.1?",
    "options": ["Deploy", "Cancel"],
    "callback_url": "https://your-agent.example.com/on_answer"
  }'

You should see the prompt in Telegram. Tap a button to complete the loop.

Deeper hybrid and full Docker workflows: Local development.

Next steps

• Concepts — channel types and auth layers
• Admin UI — manage channels, prompts, and messages in the browser
• Platforms — Slack, Teams, Discord, and more
• Agent integration — verify signed callbacks
• Automation platforms — n8n, Zapier, Make, and similar
• Self-Hosting Docker — full Compose / Swarm reference
• Local development — hybrid and full Docker details