Kolega Studio Manifest Reference

Last updated 5 months ago

Overview

The .kolega-manifest.yaml file configures your project's development environment in Kolega. Place this file at the root of your repository to define runtime environments, dependencies, build commands, and development servers.

For most users: Kolega automatically generates and manages this file when you create projects from templates. You typically don't need to touch this file.

For advanced users: You can manually create or modify this file for custom project configurations. However, this comes with important tradeoffs detailed below.

Primary use case: Manual manifest configuration is most useful when you select the Empty Project template and need full control over your development environment setup from scratch.

Important: Manual Configuration Considerations

When to Use Manual Configuration

Manual manifest configuration is recommended only if you:

  • Are importing an existing project with custom requirements

  • Need precise control over your development environment

  • Understand the technical implications of custom configuration

  • Are comfortable troubleshooting environment setup issues

Risks of Modifying Auto-Generated Manifests

USE AT YOUR OWN RISK

If you modify an auto-generated .kolega-manifest.yaml file (from templated projects), you may experience:

  • Broken deployments - Deployment pipelines expect specific configurations

  • Development server issues - Auto-restart and process management may fail

  • Feature incompatibilities - Platform features may not work as expected

For templated projects (Fullstack App, Mobile App, etc.):

  • Kolega generates optimal configurations automatically

  • Manual changes interfere with the platform's normal workflow

  • Some platform features are not guaranteed to work with custom configs

  • Deployments may fail if build commands or runtime configs are modified

Examples of templates with auto-generated manifests:

  • Fullstack App - Full-stack web applications with frontend and backend

  • Mobile App - React Native Expo mobile applications and backend

  • Any project created from Kolega's template gallery

Recommendation: If you're using a Kolega template, avoid manual manifest edits unless absolutely necessary and you understand the technical implications.

Configuration Structure

Your manifest file consists of two required fields and several optional command sections that execute at different stages of the sandbox lifecycle.

Required Fields

name

Type: string

Project identifier displayed in the Kolega interface.

name: my-project

runtime

Type: string
Status: Required for schema validation, but not actively used by the platform

The actual runtime environment is determined by Kolega Studio and pre-configured for your workspace, not this field. This field exists for documentation and future compatibility.

Recommended values for documentation:

  • Node.js projects: node:18, node:20, node:22

  • Python projects: python:3.9, python:3.10, python:3.11, python:3.12

runtime: node:20

Note: Choose the value that matches your project's actual runtime. While Kolega doesn't currently use this field for sandbox configuration, it helps document your project's requirements and may be utilized in future versions.

For Templated Projects: This field is auto-generated and matches your template's runtime. Changing it won't affect your actual runtime environment but may cause confusion.

Command Sections

environment_setup

Type: array of strings
Execution: On sandbox creation, before dependency installation
Timeout: 120 seconds per command
Use for: Environment configuration, registry setup, system-level tools

Commands execute in order during initial sandbox setup, before install_commands run. Use this to configure the environment that dependencies will be installed into.

Common use cases:

  • Package registry configuration: Configure npm, pip, or gem registries

  • System package installation: Install system-level dependencies via apt/apk

  • Directory creation: Create required directories before installation

  • Tool initialization: Initialize version managers (nvm, pyenv)

Examples:

environment_setup:
  - npm config set registry https://registry.npmjs.org/
  - pip config set global.index-url https://pypi.org/simple

System packages:

environment_setup:
  - apt-get update && apt-get install -y libpq-dev

Execution timing:

  • ✅ New sandbox creation

  • ✅ Sandbox resumed from pool

  • ❌ Sandbox resumed from pause

  • ❌ After git pull/reset

install_commands

Type: array of strings
Execution: On sandbox creation, after environment_setup
Timeout: 600 seconds (10 minutes) per command
Use for: Installing project dependencies

Commands execute sequentially after environment setup. Each command has a generous timeout for large dependency installations. Use this for one-time setup operations that install dependencies into your project.

Common use cases:

  • Package installation: npm install, pip install -r requirements.txt, bundle install

  • Global tools: npm install -g typescript, pip install poetry

  • Dependency compilation: npm rebuild, native module compilation

  • Database setup: Initial database creation (NOT migrations - use post_setup_commands)

Simple project:

install_commands:
  - npm install

Python with compiled dependencies:

install_commands:
  - pip install -r requirements.txt
  - pip install -e .

Monorepo example:

install_commands:
  - cd frontend && npm install
  - cd backend && pip install -r requirements.txt

Execution timing:

  • ✅ New sandbox creation

  • ✅ Sandbox resumed from pool

  • ❌ Sandbox resumed from pause

  • ❌ After git pull/reset

dev_server_commands

Type: array of strings (or use singular dev_server_command: string)
Execution: On sandbox creation, after install_commands
Runs: Automatically in background as managed processes
Use for: Starting development servers

Field Variants:

  • dev_server_commands - Array of commands (recommended for multiple servers)

  • dev_server_command - Single string command (legacy, for single server)

  • Both can be used together - they will be combined into one list

# Using array (recommended)
dev_server_commands:
  - npm run dev

# Using singular (legacy, still supported)
dev_server_command: npm run dev

# Both together (they combine)
dev_server_command: cd frontend && npm run dev
dev_server_commands:
  - cd backend && npm run dev
# Results in: [frontend command, backend command]

All commands start automatically in background after installation completes. Kolega uses two execution modes depending on template capabilities:

Single server:

dev_server_commands:
  - npm run dev

Multiple servers (monorepo):

dev_server_commands:
  - cd frontend && npm run dev -- --port 9001
  - cd backend && npm run dev -- --port 9002

Important: Always bind servers to 0.0.0.0 (not 127.0.0.1) to make them accessible:

# Good - accessible
- uvicorn main:app --host 0.0.0.0 --port 9002

# Won't work - only localhost
- uvicorn main:app --host 127.0.0.1 --port 9002

Execution timing:

  • ✅ New sandbox creation

  • ✅ Sandbox resumed from pool

  • ❌ Sandbox resumed from pause (servers restart automatically via profile watcher)

  • ❌ After git pull/reset

post_setup_commands

Type: array of strings
Execution: After git pull operations
Timeout: 180 seconds (3 minutes) per command
Use for: Code generation, database migrations, asset compilation

Commands execute after pulling latest code changes when resuming a paused sandbox or performing git operations. These are architecturally separate from install_commands because they:

  • Depend on code from git - Operate on existing code that was just pulled

  • Run on every resume - Execute each time you resume a paused sandbox

  • Are incremental - Sync generated code/migrations with updated source

  • Should be fast - Lighter operations (3-minute timeout vs 10-minute for install)

Common use cases:

  • Code generation: prisma generate, graphql-codegen, protobuf compilation

  • Database migrations: npm run db:migrate, alembic upgrade head

  • Shared library builds: npm run build:shared in monorepos

  • API schema generation: Generate client SDKs from OpenAPI specs

Anti-pattern: Do NOT use for initial dependency installation - that belongs in install_commands.

post_setup_commands:
  - npx prisma generate
  - npm run db:migrate
  - npm run build:shared

Execution timing:

  • ✅ Sandbox resumed from pause (after git pull)

  • ✅ After manual git pull/reset

  • ❌ New sandbox creation

  • ❌ Sandbox resumed from pool

Build Commands

Type: string
Execution: Only when AI agent explicitly calls build tools
Timeout: 1800 seconds (30 minutes)
Use for: Project compilation and build verification

Build commands are never executed automatically. The AI agent can call these through build_backend and build_frontend tools when you request build verification.

Critical for Deployments: Build commands are used during deployment processes. Modifying these in templated projects can cause deployment failures. Custom build commands are only recommended for projects you fully control and understand.

build_command

Generic build command for simple projects or fallback for monorepos.

build_command: npm run build

backend_build_command

Backend-specific build command. Falls back to build_command if not specified.

backend_build_command: cd backend && npm run build

frontend_build_command

Frontend-specific build command. Falls back to build_command if not specified.

frontend_build_command: cd frontend && npm run build

Usage pattern:

# Simple project - single build
build_command: npm run build

# Monorepo - separate builds
backend_build_command: cd backend && npm run build
frontend_build_command: cd frontend && npm run build

# Monorepo - unified script
build_command: npm run build:all

Best Practices & Guidelines

Choosing Between Auto-Generated and Manual Configuration

Keep Auto-Generated File and Do Not Modify It (Recommended for Most Users):

  • You created your project from a Kolega template (Fullstack App, Mobile App, etc.)

  • Standard web or mobile application from Kolega's template gallery

  • You want reliable deployments without configuration overhead

  • You prefer platform features to "just work"

  • You want automatic improvements as Kolega evolves

Create/Modify Auto-Generated File (Advanced Users Only):

  • Importing existing project with unique requirements

  • Working on a project that is not a Kolega template (Empty Project)

  • Custom build tooling not covered by templates

  • You need absolute control over the environment

  • You're willing to troubleshoot configuration issues independently

  • You accept that deployments and platform features may not work as expected

Summary

The .kolega-manifest.yaml provides powerful control over your development environment. For most users, Kolega's auto-generated configurations provide the best experience with minimal maintenance. Manual configuration is a power-user feature that trades convenience and guaranteed compatibility for ultimate flexibility.

Remember: If you know exactly what you need and understand the risks, manual configuration gives you complete control. If you're building with Kolega templates (Fullstack App, Mobile App, etc.), trust the auto-generated configs and focus on shipping features.