workspace.yaml

The single configuration file that drives all EZKeel behavior. Place it at the root of your project.

Overview

Every EZKeel project has a workspace.yaml at its root. This file declares what your project needs: which paths are public, what secrets are required, which AI models to use, and how CI/CD is configured. The ezkeel CLI reads this file for every operation.

Full Schema

Here is a complete, annotated workspace.yaml:

workspace.yaml
            
            
            
          

# Project name — used for repo creation and Infisical project
project: my-project

# Visibility rules — control what is public vs private
visibility:
  default: private
  public_paths:
    - src/
    - docs/
    - tests/
    - README.md
    - LICENSE
    - CONTRIBUTING.md
  private_paths:
    - plans/
    - internal/
    - .claude/
    - workspace.yaml

# Secrets management via Infisical
secrets:
  required:
    - ANTHROPIC_API_KEY

# AI model configuration
ai:
  models:
    default: claude-sonnet-4-5
    fast: claude-haiku-4-5
  mcp_servers:
    - name: filesystem
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
  persona: |
    You are a senior engineer working on my-project.
    Follow the conventions in CLAUDE.md and AGENTS.md.

# Dev Container configuration
environment:
  devcontainer: .devcontainer/devcontainer.json

# CI/CD configuration
ci:
  provider: forgejo-actions
  workflows_dir: .forgejo/workflows

# Deployment (extensible)
deploy: {}
        

visibility

Controls which paths are public (mirrored to the public repo via ezkeel publish) and which stay private. See Visibility for a deep dive.

Field	Type	Description
`default`	string	Default visibility: `private` or `public`
`public_paths`	list	Paths or prefixes that are always public
`private_paths`	list	Paths or prefixes that are always private (overrides default)

secrets

Declares which secrets the project requires. EZKeel pulls these from Infisical at runtime. See Secrets.

Field	Type	Description
`required`	list	Environment variable names that must be present

ai

Configures AI tools, model preferences, MCP servers, and the persona prompt. See AI Configuration.

Field	Type	Description
`models.default`	string	Primary model for AI commands
`models.fast`	string	Fast model for quick tasks
`mcp_servers`	list	MCP server configurations (name, command, args)
`persona`	string	System prompt for AI assistants working in this project

environment

Points to the Dev Container configuration for reproducible development environments.

Field	Type	Description
`devcontainer`	string	Path to the `devcontainer.json` file

ci

Configures the CI/CD provider and workflow location.

Field	Type	Description
`provider`	string	CI provider: `forgejo-actions` or `github-actions`
`workflows_dir`	string	Directory containing workflow files

deploy

Extensible deployment configuration. Currently a placeholder for future deployment integrations (Docker, Kubernetes, etc.).

Tip: Run ezkeel init <name> to generate a workspace.yaml with sensible defaults pre-filled.