greentic-start

greentic-start is the program that opens a Greentic bundle and keeps it running on your machine.

If you are not a systems programmer, a good way to think about it is:

• a bundle is a packaged Greentic app
• greentic-start is the launcher
• it starts the local services that bundle needs
• it keeps logs and runtime state in the bundle folder
• it can also stop or restart that running bundle later

Who This README Is For

This README is written for:

• people exploring Greentic for the first time
• app builders who are comfortable editing YAML or JSON but do not want to learn the whole runtime internals
• non-technical or lightly technical teammates who need to understand what greentic-start does

If you are a coding agent, automation tool, or someone changing runtime behavior, do not use this README as your main source of truth.

Read docs/coding-agents.md instead.

That guide explains:

• how greentic-start is expected to be used
• what commands and options exist
• what each option does
• which behaviors are automatic
• which settings come from the bundle versus the CLI

What greentic-start Does

When you run greentic-start, it can:

• find the bundle you want to run
• load the bundle's runtime configuration
• start local services such as the HTTP gateway
• optionally start helper services such as NATS
• optionally create a public tunnel with Cloudflare Tunnel or ngrok
• expose an admin API over mTLS if you enable it
• write logs so you can inspect what happened
• keep runtime state under the bundle's state/ area

In everyday terms, it is the part that turns “I have a bundle on disk” into “the app is now running locally.”

The Most Common Thing To Do

Most people only need one command:

greentic-start start --bundle /path/to/your-bundle

This starts the bundle using its own configuration files.

If your bundle is already the current folder, you will often see people use:

greentic-start start --bundle .

In some situations, greentic-start may choose a tunnel automatically for local development. That is normal behavior in this project.

The Main Commands

greentic-start has four main commands:

• start Starts the bundle.
• up Same meaning as start.
• stop Stops a running bundle.
• restart Starts again, and can also restart selected runtime services.

Examples:

greentic-start start --bundle /tmp/my-bundle
greentic-start stop --bundle /tmp/my-bundle
greentic-start restart --bundle /tmp/my-bundle

A Few Practical Examples

Start a bundle quietly

greentic-start start --bundle /tmp/my-bundle --quiet

This reduces log noise on the terminal.

Start a bundle and show more detail

greentic-start start --bundle /tmp/my-bundle --verbose

This is useful when something is not working and you want more clues.

Start with ngrok instead of Cloudflare Tunnel

greentic-start start --bundle /tmp/my-bundle --ngrok on

Start with an external NATS server

greentic-start start \
  --bundle /tmp/my-bundle \
  --nats external \
  --nats-url nats://127.0.0.1:4222

Enable the admin API

greentic-start start --bundle /tmp/my-bundle --admin --admin-port 8443

This enables a protected admin endpoint intended for operational control.

What You Need Before Starting

Usually you need:

• a Greentic bundle on disk
• any required local tools your bundle expects
• setup answers or secrets already provided if the bundle depends on them

Important detail:

• greentic-start starts and hosts the bundle
• it does not invent missing app configuration on its own
• if your app flow needs explicit runtime config in a node, that config still has to come from the bundle design or runtime contract that supports it

Where Things Are Stored

When the bundle runs, greentic-start writes data into the bundle area, especially:

• logs/
• state/
• .greentic/ for some persisted setup/runtime helpers

This means the bundle folder is not just input; it also becomes the local runtime workspace.

Troubleshooting Basics

If something seems wrong, check these first:

• did you point --bundle at the right directory?
• does the bundle have the expected config files?
• are required secrets already provisioned?
• are the ports already in use by another process?
• did the logs in logs/ show a startup or policy error?

Good first debugging steps:

greentic-start start --bundle /tmp/my-bundle --verbose

Then inspect:

• logs/flow.log
• logs/operator.log
• bundle state/ output for the specific run

For Coding Agents And Maintainers

If you are changing code, reviewing runtime behavior, or trying to automate greentic-start, go to docs/coding-agents.md.

That document is the operational guide for:

• command behavior
• option-by-option meaning
• bundle resolution
• automatic tunnel behavior
• restart semantics
• admin API flags
• logging and runtime expectations

Repository Notes

This repository focuses on lifecycle execution for Greentic bundles. It is not the place for every product-level behavior in the broader platform.

If you need deeper ownership boundaries, see docs/ownership.md.