Configuration

Ploy uses a ploy.yaml file in the root of your repository to configure build settings and deployment options. This file provides fine-grained control over how your project is built and deployed.

Quick Start

Create a ploy.yaml file in your repository root:

kind: static
build: npm run build
out: dist

Commit and push the file to trigger a deployment with your custom configuration.

Configuration Options

kind

Type: "static" | "nextjs" | "dynamic" | "worker" Required: No (auto-detected if omitted)

Specifies the project type:

• static: Static site generation (React, Vue, Angular, HTML, etc.)
• nextjs: Next.js applications with server-side rendering support
• dynamic: Worker-based applications and full-stack runtimes
• worker: Alias for dynamic

kind: static

Example - Static React App:

kind: static
build: npm run build
out: dist

Example - Next.js App:

kind: nextjs
build: npm run build
out: .next

Example - Cloudflare Vite / TanStack Start App:

kind: dynamic
build: pnpm build
out: dist

build

Type: string Required: Yes (when your project needs a build step)

The command to run to build your project. This is typically a script defined in your package.json.

build: npm run build

Common examples:

# npm
build: npm run build

# pnpm
build: pnpm build

# yarn
build: yarn build

# Custom script
build: npm run build:production

assets

Type: object Required: No

Configures uploaded static assets for dynamic projects such as Cloudflare Vite apps. This replaces the need to commit wrangler.json just to wire static assets.

assets:
  binding: ASSETS
  not_found_handling: single-page-application
  run_worker_first:
    - /api/*
    - "!/api/docs/*"

Fields:

• binding: Optional binding name exposed to your worker. Must be uppercase with underscores.
• not_found_handling: One of none, 404-page, or single-page-application.
• run_worker_first: Either true, false, or an array of route patterns.

Use run_worker_first when your worker should handle some requests before the asset layer. In the example above, /api/* stays worker-first, while /api/docs/* is served from static assets.

out

Type: string Required: No (auto-detected if omitted) Default: Framework-specific (e.g., dist, build, .next)

The relative path to the output directory containing your built files.

out: dist

Validation rules:

• Must be a relative path (not absolute)
• Cannot start with /
• Cannot contain .. (path traversal prevention)
• Trailing slashes are automatically removed

Common output directories:

Example:

kind: static
build: npm run build
out: dist

base

Type: string Required: No Default: Repository root

The base directory where your project is located within the repository. This is useful for monorepos where your deployable project is in a subdirectory.

base: apps/web

Validation rules:

• Must be a relative path (not absolute)
• Cannot start with /
• Cannot contain .. (path traversal prevention)
• Trailing slashes are automatically removed

Monorepo example:

my-monorepo/
├── apps/
│   ├── web/          ← Your Next.js app
│   └── api/
├── packages/
│   └── ui/
└── ploy.yaml

kind: nextjs
base: apps/web
build: npm run build
out: .next

monorepo

Type: boolean Required: No Default: false

Enables monorepo mode. When enabled, Ploy will:

• Look for package.json in the repository root
• Install dependencies from the root
• Execute build commands from the base directory

monorepo: true
base: apps/web

Typical monorepo configuration:

kind: static
monorepo: true
base: apps/frontend
build: npm run build
out: dist

How it works:

1. Ploy installs dependencies from the repository root (where the main package.json is)
2. Changes directory to the base path
3. Runs the build command from the base directory
4. Looks for output in {base}/{out}

Per-App Configuration in Monorepos

In a monorepo, you can place ploy.yaml directly in each app's subdirectory (the base directory) instead of — or in addition to — the repository root. During builds, Ploy automatically discovers and uses the ploy.yaml closest to your app:

1. If a ploy.yaml exists in the base directory (e.g., apps/web/ploy.yaml), it is used
2. Otherwise, Ploy falls back to the root ploy.yaml

This lets each app in a monorepo define its own build configuration independently:

my-monorepo/
├── apps/
│   ├── web/
│   │   └── ploy.yaml    ← Config for web app
│   └── docs/
│       └── ploy.yaml    ← Config for docs app
├── packages/
│   └── ui/
└── package.json

apps/web/ploy.yaml:

kind: nextjs
base: apps/web
monorepo: true
build: pnpm build --filter web

apps/docs/ploy.yaml:

kind: nextjs
base: apps/docs
monorepo: true
build: pnpm build --filter docs

agentSDK

Type: boolean Required: No Default: false

Enables the Agent SDK bindings. When set to true, Ploy automatically configures all bindings required by @meetploy/agent-sdk:

• ai: true (AI gateway)
• state: { PLOY_AGENT_STATE: ploy_agent_state } (durable key-value storage)
• fs: { PLOY_AGENT_FILES: ploy_agent_files } (file storage)
• workflow: { PLOY_AGENT_WORKFLOW: ploy_agent_run } (durable workflow)
• timer: { PLOY_AGENT_SCHEDULER: ploy_agent_scheduler } (scheduled tasks)

kind: worker
agentSDK: true

You can still add extra bindings alongside agentSDK: true — they will be merged with the defaults.

Complete Examples

Static Vite + React App

kind: static
build: npm run build
out: dist

Next.js App

kind: nextjs
build: pnpm build
out: .next

Monorepo with Turborepo

Project structure:

my-app/
├── apps/
│   ├── web/          # Next.js frontend
│   └── docs/         # Documentation site
├── packages/
│   └── ui/           # Shared UI components
├── package.json      # Root with workspaces
├── turbo.json
└── ploy.yaml

ploy.yaml for deploying the web app:

kind: nextjs
monorepo: true
base: apps/web
build: npm run build
out: .next

Custom Output Directory

kind: static
build: npm run build:prod
out: public/dist

SPA with Custom Base Path

kind: static
build: npm run build
out: build
base: packages/client

Configuration Priority

Ploy uses the following priority order for configuration:

1. ploy.yaml (highest priority) - Explicit configuration file
2. Dashboard settings - Manual overrides in project settings
3. Auto-detection (lowest priority) - Framework detection

Validation Errors

Common validation errors and how to fix them:

"Build command is required when kind is 'static'"

# ❌ Missing build command
kind: static
out: dist

# ✅ Fixed
kind: static
build: npm run build
out: dist

"Out path must be relative, not absolute"

# ❌ Absolute path
kind: static
build: npm run build
out: /dist

# ✅ Fixed - relative path
kind: static
build: npm run build
out: dist

"Out path cannot contain '..'"

# ❌ Path traversal
kind: static
build: npm run build
out: ../dist

# ✅ Fixed
kind: static
build: npm run build
out: dist

"Base path must be relative, not absolute"

# ❌ Absolute path
kind: static
base: /apps/web
build: npm run build

# ✅ Fixed
kind: static
base: apps/web
build: npm run build

Best Practices

1. Commit ploy.yaml to version control - Keep configuration in sync with code
2. Use kind: static for most frameworks - Only use nextjs for Next.js apps requiring SSR
3. Set monorepo: true for monorepos - Ensures proper dependency installation
4. Use relative paths - Never use absolute paths or .. for security
5. Match your framework's output directory - Check your framework's documentation for the correct out path

Troubleshooting

My build is failing

1. Check that your build command works locally: npm run build
2. Verify the out directory exists after building
3. Review deployment logs for specific error messages

My monorepo isn't building correctly

1. Ensure monorepo: true is set in ploy.yaml
2. Verify your root package.json has workspace configuration
3. Check that the base path points to the correct app directory
4. Ensure build commands are run from the base directory

Configuration changes aren't taking effect

1. Ensure ploy.yaml is committed to your repository
2. Push your changes to trigger a new deployment
3. Check deployment logs to see which configuration was used
4. Verify there are no YAML syntax errors in your file

Next Steps

• Review the Quick Start Guide for deployment basics
• Learn about Self-Hosting to deploy Ploy on your infrastructure
• Check out example projects for inspiration