Installation & Setup

Install Compozy CLI

Main Methods

The most common installation methods across all platforms:

For Node.js developers:

# Install via NPM
npm install -g @compozy/cli

# Or with Yarn
yarn global add @compozy/cli

# Or with pnpm
pnpm add -g @compozy/cli

Linux-Specific Methods

Additional installation options for Linux distributions:

Download the appropriate .deb, .rpm, or .apk package for your distribution from the GitHub Releases page and install it using your system's package manager.

For Debian/Ubuntu:

# Replace with the downloaded file name
sudo dpkg -i compozy_*.deb

For Fedora/CentOS:

# Replace with the downloaded file name
sudo rpm -i compozy_*.rpm

For Alpine Linux:

# Replace with the downloaded file name
sudo apk add --allow-untrusted compozy_*.apk

Pre-built Binaries

Download pre-built binaries directly from GitHub:

Quick install script (coming soon):

# This feature will be available in a future release
# curl -fsSL https://install.compozy.com | sh

Manual download: Download the appropriate binary for your OS and architecture from our GitHub Releases page.

Download the archive for your platform (e.g., compozy_x.x.x_linux_x86_64.tar.gz)
Extract the archive: tar -xzf compozy_*.tar.gz
Move the binary to your PATH: sudo mv compozy /usr/local/bin/
Make it executable: sudo chmod +x /usr/local/bin/compozy

Verify the installation:

compozy --version

Initialize Your First Project

Create a new Compozy project:

# Initialize a new project
compozy init my-ai-project
cd my-ai-project

# Or with Docker infrastructure setup
compozy init my-ai-project --docker

This creates a complete project structure:

Prerequisites

Your project needs these dependencies:

Bun Runtime
For executing TypeScript tools: curl -fsSL https://bun.sh/install | bash
AI Provider API Key
OpenAI, Groq, Anthropic, or local Ollama setup
Infrastructure Services
PostgreSQL, Redis, and Temporal (cloud services or local Docker)

Infrastructure Setup

Choose your infrastructure setup approach:

Option 1: Cloud Services (Recommended)

Use managed cloud services for production deployments

PostgreSQL
AWS RDS, Neon, Supabase, or any PostgreSQL-compatible service
Redis
AWS ElastiCache, Upstash, Redis Cloud, or any Redis-compatible service
Temporal
Temporal Cloud for managed service, or self-hosted deployment

Option 2: Local Development

Use Docker Compose for a complete local development environment

The compozy init command automatically creates a docker-compose.yaml file with all required services when you use the --docker flag:

# Initialize project with Docker infrastructure
compozy init my-project --docker
cd my-project

# Start all services (PostgreSQL, Redis, Temporal, MCP Proxy)
docker-compose up -d

This includes PostgreSQL, Redis, Temporal, and MCP Proxy services pre-configured for your project.

Configuration

Environment Variables

Create a .env file in your project:

.env

# AI Provider (choose one)
OPENAI_API_KEY=sk-your-openai-key
GROQ_API_KEY=gsk_your-groq-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

# Infrastructure (adjust for your setup)
DATABASE_URL=postgresql://user:pass@localhost:5432/compozy
REDIS_URL=redis://localhost:6379
TEMPORAL_ENDPOINT=localhost:7233

Start Development

# Start your development server
compozy dev

After this you will have your server running at http://localhost:5001.

Quick Verification

Test your setup with a simple workflow:

# List available workflows
compozy workflow list

# Execute the default greeter workflow
compozy workflow execute greeter --json='{"name": "World", "style": "friendly"}'

Next Steps

Ready to build your first AI workflow? Choose your learning path:

Quick Start Guide

Build and test your first workflow in 5 minutes

Core Concepts

Understand agents, tasks, workflows, and tools fundamentals

First Workflow Tutorial

Complete walkthrough building a real-world workflow

Project Configuration

Configure models, runtime, and advanced project settings

Installation & Setup

Option 1: Cloud Services (Recommended)

Option 2: Local Development

On this page