Quick Start

This quick start uses Temporal standalone mode, so you do not need Docker or an external Temporal cluster. For production hardening, read the Production guide.

Prerequisites

Compozy CLI
Bun for tool execution
An OpenAI-compatible API key stored in .env

Option 1: Standalone (Recommended for Dev)

Follow these steps to run everything locally without external services.

1. Initialize a Project

compozy init hello-standalone
cd hello-standalone

2. Configure Temporal Standalone Mode

Replace the generated compozy.yaml with the configuration below. It enables standalone mode and points to a simple workflow.

compozy.yaml

name: hello-standalone
version: "0.1.0"
description: Develop locally with embedded Temporal

temporal:
  mode: standalone
  host_port: localhost:7233
  standalone:
    database_file: :memory:
    frontend_port: 7233
    bind_ip: 127.0.0.1
    namespace: default
    cluster_name: compozy-standalone
    enable_ui: true
    ui_port: 8233

runtime:
  type: bun
  entrypoint: "./entrypoint.ts"
  permissions:
    - --allow-read
    - --allow-net

workflows:
  - source: ./workflows/greeting.yaml

3. Create a Tool and Workflow

entrypoint.ts

interface GreetingInput {
  name: string;
}

export default {
  async greeting_tool({ input }: { input: GreetingInput }) {
    return {
      message: `Hello, ${input.name}! Welcome to Compozy with Temporal standalone mode.`,
      timestamp: new Date().toISOString(),
    };
  },
};

workflows/greeting.yaml

id: greeting-workflow
version: 0.1.0
description: Quick start workflow using embedded Temporal

schemas:
  - id: greeting_input
    type: object
    properties:
      name:
        type: string
        description: Name of the person to greet
    required:
      - name

config:
  input:
    greeting_input

tools:
  - id: greeting_tool
    description: Generates a greeting message
    input:
      greeting_input

agents:
  - id: greeter
    model: openai:gpt-4o-mini
    instructions: "Use the greeting tool to produce a personalized welcome."
    tools:
      - greeting_tool
    actions:
      - id: make_greeting
        prompt: "Generate a greeting for {{ .workflow.input.name }}."

tasks:
  - id: greet
    type: basic
    agent: greeter
    action: make_greeting
    final: true

outputs:
  greeting: "{{ .tasks.greet.output }}"

Create a .env file with your API key:

OPENAI_API_KEY=sk-your-api-key

4. Start Compozy with Standalone Temporal

compozy start --temporal-mode=standalone --temporal-standalone-database=:memory:

The command boots Compozy, launches the embedded Temporal services on ports 7233-7236, and serves the Temporal Web UI at http://localhost:8233.

Visit the Temporal Web UI to watch workflow executions in real time. Use it to inspect task queues, workflow history, and failure retries without leaving your laptop.

5. Run the Workflow

compozy workflow run ./workflows/greeting.yaml --input '{"name":"Avery"}'

You should see the greeting response in your terminal or HTTP client within seconds.

Next Steps

Temporal Modes

Understand when to switch between remote and standalone

Production Deployment

Harden your deployment with a remote Temporal cluster

Embedded Temporal

Learn how the standalone server is wired into Compozy

Troubleshooting

Fix startup timeouts, port conflicts, and SQLite issues

On this page