dot-prompt

Getting Started

This guide will walk you through setting up .prompt and writing your first prompt file.

Prerequisites

  • Docker and Docker Compose
  • Node.js >=18.0.0 (for TypeScript client) or Python >=3.10 (for Python client)

1. Start the Docker Container

The fastest way to get started is using our Docker containers. dot-prompt provides two images:

  • dot-prompt:headed - Full Phoenix web UI + API
  • dot-prompt:headless - API only, no web UI

Headless (API Only)

For server deployments, use the headless version: 

services:
  dot-prompt:
    build:
      context: .
      dockerfile: Dockerfile.headless
    image: dot-prompt:headless
    container_name: dot-prompt-server
    restart: unless-stopped
    ports:
      - "4000:4000"
    volumes:
      - "./prompts:/app/prompts:ro"
    environment:
      - MIX_ENV=prod
      - PORT=4000
      - PROMPTS_DIR=/app/prompts
      - PHX_HOST=localhost
      - SECRET_KEY_BASE=dEvSeCrEtKeYBaSeFoRTeStInG12345678901234567890
      - LIVE_VIEW_SIGNING_SALT=DeVSiGnInGsAlT123456789
    healthcheck:
      test: ["CMD-SHELL", "bash -c 'echo > /dev/tcp/127.0.0.1/4000'"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s

Start the container: 

docker compose -f docker-compose.headless.yml up -d

With UI (Development)

For development with the visual playground, use the headed version: 

services:
  dot-prompt-headed:
    build:
      context: .
      dockerfile: Dockerfile.headed
    image: dot-prompt:headed
    container_name: dot-prompt-headed
    restart: unless-stopped
    ports:
      - "4000:4000"
    volumes:
      - "./prompts:/app/prompts:ro"
    environment:
      - PORT=4000
      - PROMPTS_DIR=/app/prompts
      - SECRET_KEY_BASE=replace_with_secure_key
      - LIVE_VIEW_SIGNING_SALT=replace_with_secure_salt
      - PHX_HOST=localhost
    healthcheck:
      test: ["CMD-SHELL", "bash -c 'echo > /dev/tcp/127.0.0.1/4000'"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s

What you get:

  • Viewer at localhost:4000 — Select params, see compiled output in real time (headed only)
  • HTTP API at localhost:4000 — Compile prompts from your application
  • Live reload — File watcher recompiles on every save
  • MCP server — Connect your LLM coding tools

Environment Variables

The following environment variables can be configured:

Variable Default Description
PORT 4000 Container internal port
PROMPTS_DIR /app/prompts Directory where prompts are stored
MIX_ENV prod Elixir environment
DISABLE_UI (not set) Set to true to disable Phoenix web UI
SECRET_KEY_BASE (required) Phoenix secret key for sessions
LIVE_VIEW_SIGNING_SALT (required) Salt for LiveView signed payloads
PHX_HOST localhost Hostname for Phoenix endpoint

Your First .prompt File

Create a file called hello.prompt in your prompts folder: 

init do
  @version: 1.0
  @major: 1

  def:
    mode: greeting
    description: A friendly greeting.

  params:
    @name: str -> The user's name

end init

Hello, @name! Welcome to our app.

Compile and Render

Call the API to compile the prompt: 

curl -X POST http://localhost:4000/api/render \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "hello",
    "runtime": { "name": "World" }
  }'

Response: 

{
  "prompt": "Hello, World! Welcome to our app.",
  "response_contract": {
    "type": "object",
    "properties": {}
  }
}

Use the TypeScript Client

Install the package: 

npm install @dotprompt/client

Use in your code: 

import { DotPromptClient } from '@dotprompt/client';

const client = new DotPromptClient({
  baseUrl: 'http://localhost:4000'
});

const prompts = await client.listPrompts();

Use the Python Client

Install the package: 

pip install dotprompt-client

Use in your code: 

from dotprompt import DotPromptClient

with DotPromptClient() as client:
    prompts = client.list_prompts()

Next Steps