gtc start

Overview

The gtc start command launches the Greentic runtime server. It starts all necessary services including the HTTP server and flow executor.

Usage

gtc start [OPTIONS] <BUNDLE_PATH>

Options

Option	Description	Default
--bundle <BUNDLE>	Bundle path passed to the runtime
--tenant <TENANT>	Tenant identifier
--team <TEAM>	Team identifier
--locale <LOCALE>	UI locale as a BCP-47 tag
--config <CONFIG>	Runtime configuration file
--cloudflared <on/off>	Enable Cloudflare tunnel	off
--ngrok <on/off>	Enable ngrok tunnel	off
--restart <PART>	Restart part of a running stack (all, cloudflared, ngrok, gateway, egress, subscriptions)
--log-dir <DIR>	Log directory
--verbose	Enable verbose logging	false
--quiet	Minimal output	false
--admin	Enable the mTLS admin API endpoint	false
--admin-port <PORT>	Admin API port	8443
--admin-certs-dir <DIR>	Directory containing admin TLS certs
--admin-allowed-clients <CNS>	Comma-separated allowed admin client CNs

Basic Usage

Demo Flows

Extensible demo after wizard and setup:

gtc start ./crates/cloud-deploy-demo/bundle

End-to-end demo after setup from a published bundle:

gtc start ./cloud-deploy-demo.gtbundle

Start with Defaults

gtc start ./my-bundle

This starts:

• The runtime services for the bundle
• Any enabled tunnel you select with flags
• Gateway, egress, and subscription processes as required by the bundle

Start for Development

# Use ngrok instead of cloudflared
gtc start ./my-bundle --cloudflared off --ngrok on

# With verbose logging
gtc start ./my-bundle --verbose

Start for Production

# No tunnels
gtc start ./my-bundle --cloudflared off --ngrok off

# External runtime configuration file
gtc start ./my-bundle --config ./runtime.toml --cloudflared off

Tunnel Configuration

Cloudflared (Default)

Cloudflared creates a secure tunnel to Cloudflare’s network:

gtc start ./my-bundle --cloudflared on

# Output:
# Cloudflare tunnel started: https://random-words.trycloudflare.com
# Webhook URLs will use: https://random-words.trycloudflare.com

Note

Cloudflared URLs change on each restart unless you configure a persistent tunnel.

ngrok

Use ngrok for a stable URL during development:

gtc start ./my-bundle --ngrok on

# Output:
# ngrok tunnel started: https://abc123.ngrok-free.app
# Webhook URLs will use: https://abc123.ngrok-free.app

No Tunnel

For production with a public domain:

gtc start ./my-bundle --cloudflared off --ngrok off

# Make sure your server is publicly accessible
# and update provider webhooks with your domain

Setup Flow Behavior

Run gtc setup before gtc start when credentials, webhook URLs, or bundle assets need to be configured. Re-run gtc setup after credential or public URL changes, then restart the runtime:

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

Runtime Endpoints

When running, the server exposes:

Endpoint	Purpose
GET /health	Health check
GET /ready	Readiness probe
POST /webhook/{provider}/{tenant}/{team}	Provider webhooks
GET /api/v1/sessions	Session management
POST /api/v1/messages	Send messages
GET /auth/config	OAuth configuration endpoint
POST /oauth/token-exchange	Server-side OIDC token exchange proxy

Example Health Check

curl http://localhost:8080/health
# {"status": "healthy"}

OAuth Support

The runtime exposes two endpoints for OAuth/OIDC integration with messaging providers that require user authentication (such as WebChat or Teams).

GET /auth/config

Reads the OAuth configuration from the secrets store and returns it to the client. Clients use this endpoint to discover the identity provider settings needed to initiate an authorization flow.

curl http://localhost:8080/auth/config
# {
#   "authority": "https://login.microsoftonline.com/{tenant-id}/v2.0",
#   "client_id": "your-client-id",
#   "redirect_uri": "https://your-public-url/auth/callback",
#   "scope": "openid profile"
# }

POST /oauth/token-exchange

A server-side token exchange proxy for OIDC authorization code exchange. This endpoint allows clients to exchange an authorization code for tokens without running into browser CORS restrictions that occur when calling identity provider token endpoints directly from the frontend.

curl -X POST http://localhost:8080/oauth/token-exchange \
  -H "Content-Type: application/json" \
  -d '{"code": "authorization_code_here", "redirect_uri": "https://your-public-url/auth/callback"}'

Tip

The token exchange proxy eliminates the need for the browser to contact the identity provider’s token endpoint directly, which would otherwise fail due to CORS policies enforced by most identity providers.

Static Routes

Static routes (such as health checks and OAuth endpoints) can be configured without requiring an explicit public base URL. This means these endpoints are available immediately when the server starts, even before a tunnel or public URL is established.

Note

Provider webhook endpoints still require a public base URL so that external services can reach the server. Static routes are local-only and do not depend on tunnel availability.

Logging

Log Levels

# Debug (most verbose)
GREENTIC_LOG_LEVEL=debug gtc start ./my-bundle

# Info (default)
GREENTIC_LOG_LEVEL=info gtc start ./my-bundle

# Warning
GREENTIC_LOG_LEVEL=warn gtc start ./my-bundle

Verbose Mode

gtc start ./my-bundle --verbose

# Equivalent to GREENTIC_LOG_LEVEL=debug

Log Format

# JSON format (for production)
GREENTIC_LOG_FORMAT=json gtc start ./my-bundle

# Pretty format (for development, default)
GREENTIC_LOG_FORMAT=pretty gtc start ./my-bundle

Signals

Signal	Behavior
SIGTERM	Graceful shutdown
SIGINT (Ctrl+C)	Graceful shutdown
SIGHUP	Reload configuration

Environment Variables

Variable	Description
GREENTIC_HOST	Bind address
GREENTIC_PORT	HTTP port
GREENTIC_LOG_LEVEL	Log verbosity
GREENTIC_LOG_FORMAT	Log format (json/pretty)
GREENTIC_REDIS_URL	Redis URL for sessions

Troubleshooting

Port Already in Use

Error: Address already in use (os error 48)

Another process is using the configured runtime port. Stop the process or point gtc start at a different runtime configuration:

gtc start ./my-bundle --config ./runtime.toml

Tunnel Failed to Start

Error: Failed to start cloudflared tunnel

Install cloudflared or use ngrok instead:

# Install cloudflared
brew install cloudflared

# Or use ngrok
gtc start ./my-bundle --cloudflared off --ngrok on

Provider Setup Failed

Error: Setup flow failed for messaging-telegram

Check your credentials in the answers file and ensure the public URL is accessible:

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

Docker Deployment

Dockerfile

FROM rust:1.95 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/gtc /usr/local/bin/
COPY my-bundle /app/bundle
WORKDIR /app
EXPOSE 8080
CMD ["gtc", "start", "/app/bundle", "--cloudflared", "off"]

docker build -t my-worker .
docker run -p 8080:8080 my-worker

Next Steps

• Building Packs - Create and manage packs
• Configuration Reference - Full config options
• gtc setup - Configure extensions and credentials