gtc setup

Overview

The gtc setup command configures extension packs in your Greentic bundle. It runs setup flows for enabled messaging, event, OAuth, secrets, and runtime extensions, collecting credentials and configuring webhooks where needed.

Usage

gtc setup [OPTIONS] <BUNDLE_PATH>

Options

Option	Description
--answers <FILE>	Path to answers file (non-interactive)
--key <KEY>	Encryption/decryption key for answer documents that include secrets
--dry-run	Preview setup without making changes
--emit-answers <FILE>	Generate answers template
--advanced	Include optional fields in answers template
--tenant <TENANT>	Tenant identifier (default: demo)
--team <TEAM>	Team identifier
--env <ENV>	Environment (dev, staging, prod; default: dev)
--locale <LOCALE>	UI locale as a BCP-47 tag
--ui / --no-ui	Enable or disable the web setup UI
--non-interactive	Fail instead of prompting when answers are incomplete

Interactive Setup

Run setup interactively to be prompted for each extension:

gtc setup ./my-bundle

The CLI will prompt for:

• Extension credentials (API keys, tokens)
• Public URL for webhooks
• Optional configuration options

Non-Interactive Setup

Demo Catalog Flows

Every demo in the greentic-demo catalog publishes a *-setup-answers.json document alongside its pack. Apply it to a bundle that you created with gtc wizard:

gtc setup ./deep-research-demo-bundle --answers https://github.com/greenticai/greentic-demo/releases/latest/download/deep-research-demo-setup-answers.json

The same pattern works for any demo — just substitute the demo ID. See Running Demos for the full catalog with descriptions and required credentials.

You can also point gtc setup directly at a published .gtbundle artifact:

gtc setup https://github.com/greenticai/greentic-demo/releases/latest/download/cloud-deploy-demo.gtbundle --answers https://github.com/greenticai/greentic-demo/releases/latest/download/cloud-deploy-demo-setup-answers.json

Note

gtc setup auto-detects the bundle’s tenant from the tenants/ directory, so secrets are written to the correct tenant URI even when the bundle was not created with the default demo tenant. It also runs dependency capability validation across every pack in the bundle and warns if any required capability (e.g. greentic:state/state-store) is still unsatisfied.

Generate Answers Template

First, generate a template with all required fields:

# Basic template (required fields only)
gtc setup --dry-run --emit-answers answers.json ./my-bundle

# Full template (including optional fields)
gtc setup --dry-run --emit-answers answers.json --advanced ./my-bundle

Answers File Format

answers.json

{
  "messaging-telegram": {
    "enabled": true,
    "public_base_url": "https://xxx.ngrok-free.app",
    "bot_token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
  },
  "messaging-slack": {
    "enabled": true,
    "public_base_url": "https://xxx.ngrok-free.app",
    "api_base_url": "https://slack.com/api",
    "bot_token": "xoxb-xxx-xxx-xxx",
    "slack_app_id": "A07XXXXXX",
    "slack_configuration_token": "xoxe.xoxp-xxx"
  },
  "messaging-teams": {
    "enabled": false
  }
}

Setup answers are JSON. Use gtc setup --dry-run --emit-answers answers.json ./my-bundle to generate the current schema-backed file instead of hand-writing one from memory.

Apply Answers

gtc setup --answers answers.json ./my-bundle

Extension-Specific Configuration

Telegram

{
  "messaging-telegram": {
    "enabled": true,
    "public_base_url": "https://your-domain.com",
    "bot_token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
  }
}

How to get credentials:

1. Message @BotFather on Telegram
2. Send /newbot and follow prompts
3. Copy the bot token

Slack

{
  "messaging-slack": {
    "enabled": true,
    "public_base_url": "https://your-domain.com",
    "bot_token": "xoxb-xxx-xxx-xxx",
    "slack_app_id": "A07XXXXXX",
    "slack_configuration_token": "xoxe.xoxp-xxx"
  }
}

How to get credentials:

1. Go to api.slack.com/apps
2. Create a new app or select existing
3. Get Bot Token from OAuth & Permissions
4. Get App ID from Basic Information
5. Get Configuration Token from App Manifest

Microsoft Teams

{
  "messaging-teams": {
    "enabled": true,
    "public_base_url": "https://your-domain.com",
    "app_id": "your-app-id",
    "app_password": "your-app-password",
    "tenant_id": "your-tenant-id"
  }
}

WhatsApp (via Meta)

{
  "messaging-whatsapp": {
    "enabled": true,
    "public_base_url": "https://your-domain.com",
    "phone_number_id": "123456789",
    "access_token": "EAAxxxxx",
    "verify_token": "your-verify-token"
  }
}

Public URL Configuration

Attention

Webhook-based extensions require a publicly accessible URL. The public_base_url will be automatically replaced when using ngrok or cloudflared with gtc start.

Using ngrok

# Start ngrok in separate terminal
ngrok http 8080

# Copy the HTTPS URL (e.g., https://abc123.ngrok-free.app)
# Use this as public_base_url in answers

Using Cloudflared

# Cloudflared generates URL automatically with gtc start
gtc start ./my-bundle --cloudflared on

Bundle Capabilities

The bundle.yaml file can declare capabilities that unlock additional behavior during setup. Capabilities are listed as an array of capability identifiers.

Bundle Assets (greentic.cap.bundle_assets.read.v1)

When the greentic.cap.bundle_assets.read.v1 capability is present in bundle.yaml, gtc setup creates an assets/ directory at the bundle root and scaffolds eligible asset files from extension packs into it.

bundle.yaml

capabilities:
  - greentic.cap.bundle_assets.read.v1

Specifically, public assets from extension packs (currently assets/webchat-gui/ entries) are copied into the bundle-level assets/ directory. This gives you a place to customize extension assets — for example, webchat-gui skins and configuration files — without modifying the original pack contents.

How it works:

• During setup, extension packs that include eligible asset directories (e.g., assets/webchat-gui/) have those files scaffolded into the bundle root assets/ directory.
• You can then edit these files freely. Bundle-level asset files override pack defaults at runtime.
• This is useful for customizing the look and feel of webchat widgets, adjusting configuration, or applying branded skins.

Astuce

After setup scaffolds the assets, you can safely modify them. Your bundle-level customizations take precedence over the pack defaults when the runtime loads assets.

Setup Flow Execution

When you run gtc setup, it:

1. Loads bundle configuration

   Reads bundle.yaml and the resolved bundle metadata to find extension packs and setup requirements.

2. Validates answers

   Checks all required fields are present.

3. Runs setup flows

   Executes each extension’s setup flow (e.g., webhook registration).

4. Stores credentials

   Saves credentials to the configured secrets store.

5. Runs verification

   Executes verify_flow to confirm setup worked.

Re-run Setup

gtc setup is idempotent. Re-run it with the same answers file after credential or public URL changes:

gtc setup ./my-bundle --answers answers.json

For headless automation, combine an answers file with strict non-interactive mode:

gtc setup ./my-bundle --answers answers.json --non-interactive --no-ui

Troubleshooting

Webhook Registration Failed

Error: Failed to register webhook: 401 Unauthorized

Check that your bot token is correct and not expired.

Missing Required Field

Error: Missing required field 'bot_token' for messaging-telegram

Ensure all required fields are in your answers file.

Public URL Not Accessible

Error: Webhook verification failed: Connection refused

Ensure your public URL is accessible from the internet. Check ngrok/cloudflared is running.

Credential Not Found

Error: Secret 'slack_bot_token' not found

Run gtc setup to configure the extension, or check your answers file.

Best Practices

1. Use answers files in CI/CD - Avoid interactive prompts in automated pipelines
2. Keep credentials secure - Don’t commit answers files with real tokens to git
3. Use environment variables - Reference secrets via $ENV_VAR in answers
4. Test with dry-run - Preview setup before making changes
5. Regenerate on URL change - Re-run setup when your public URL changes

Next Steps

• gtc start - Run the runtime server
• Telegram Setup - Detailed Telegram guide
• Slack Setup - Detailed Slack guide