Serve

The serve command starts a FastAPI server to expose Trilogy models from a directory or file. This is useful for interactive development and debugging, and can be added as a remote store in Trilogy Studio.

Requires pytrilogy[serve] extras.

Usage

trilogy serve [path] [engine] [options]

Arguments

Argument	Description
path	Directory or file to serve. Defaults to the current directory.
engine	Engine name to advertise. Defaults to generic.

Options

Option	Description
-p, --port INTEGER	Port to run the server on. Default 8100.
-h, --host TEXT	Host to bind the server to. Default 0.0.0.0.
-t, --timeout FLOAT	Shut down after N seconds.
--no-browser	Do not open the browser automatically on startup.
--no-auth	Disable token authentication. Local development only.
--auth-token TEXT	Use a specific auth token instead of generating one randomly.

Endpoints Exposed

• / - Server info
• /index.json - List of available models
• /models/<name>.json - Specific model details
• /files/<name> - Raw .preql/.sql file content

Full Examples

# Serve a directory of models
trilogy serve ./models/ duckdb

# Serve on a custom port
trilogy serve ./models/ duckdb --port 8080

# Serve with auto-shutdown (useful for testing)
trilogy serve ./models/ generic --timeout 60

# Bind to specific host
trilogy serve ./models/ postgres --host 127.0.0.1 -p 3000

# Headless, for scripting or containers
trilogy serve ./models/ duckdb --no-browser --auth-token mytoken

Authentication

The server generates a random auth token at startup and prints it. Pass --auth-token to pin a known value, which is what you want when another process needs to connect without scraping stdout.

--no-auth disables authentication entirely. Because the default bind address is 0.0.0.0, only use it on a trusted local network - or pair it with --host 127.0.0.1.

Notes

• Requires FastAPI and uvicorn: pip install pytrilogy[serve]
• CORS is enabled by default for all origins
• The server scans for .preql, .sql, and .csv files
• Opens the browser on startup unless --no-browser is passed
• Useful for connecting to Trilogy Studio for interactive exploration