#Configuration

Kibaco stores the project-local config at .kibaco/config.json. This file is developer-specific local state and should not be committed.

Commit kibaco.config.example.json and the JSON Schema so humans, AI coding assistants, and editors can understand the expected shape without sharing private local ports or commands.

{
  "$schema": "https://kibaco.dev/schemas/kibaco.config.schema.json",
  "workspace": "my-app",
  "proxyPort": 8080,
  "services": [
    {
      "name": "postgres",
      "image": "postgres:16",
      "ports": ["5432:5432"],
      "env": {
        "POSTGRES_PASSWORD": "postgres",
        "POSTGRES_DB": "app"
      },
      "healthCheck": {
        "type": "tcp",
        "host": "127.0.0.1",
        "port": 5432
      }
    }
  ],
  "projects": [
    {
      "name": "web",
      "host": "web.localhost",
      "target": "http://localhost:3000",
      "command": "pnpm dev",
      "cwd": ".",
      "services": ["postgres"],
      "cacheDirs": [".next", "node_modules/.cache"]
    }
  ]
}

#Discovery order

Kibaco checks config files in this order:

1. ./.kibaco/config.json
2. ./kibaco.config.json
3. Registered fallback config under ~/.kibaco/workspaces/...

Run kibaco explain to show exactly which file Kibaco found.

#Git ignore

kibaco init adds these entries to .gitignore when missing:

.kibaco/
kibaco.config.json

#Repo-local overrides

Add kibaco.yaml, kibaco.yml, or kibaco.json at the workspace root to override the stored config without rerunning kibaco init.

proxyPort: 18080
projects:
  - name: web
    target: http://localhost:4000
    command: pnpm dev -- --port 4000
services:
  - name: postgres
    env:
      POSTGRES_DB: local_app

Projects and services are merged by name, so a repo-local file can override just the fields that differ.

#AI-safe commands

Use these commands before editing JSON by hand:

kibaco config validate
kibaco config format
kibaco config list-routes
kibaco config set-target web http://localhost:3004
kibaco config set-service redis --image redis:7 --port 6379:6379
kibaco config set-service postgres --env POSTGRES_DB=app --env POSTGRES_PASSWORD=postgres
kibaco config attach-service web redis postgres
kibaco config detach-service web redis
kibaco explain

When a route such as http://web.localhost:8080 fails, check kibaco config list-routes and kibaco config validate before looking for Caddy, nginx, docker-compose, or system proxy settings.

#Projects

Each project describes one local app process and the URL Kibaco should expose.

• name: Project name used by commands such as kibaco open web
• host: Local hostname handled by the proxy
• target: Local server URL started by the project command
• command: Shell command for the app process
• cwd: Working directory for the command
• services: Service names that should be started before the project
• remote: Optional SSH endpoint such as devbox:3004; when set, kibaco dev opens an SSH tunnel and target/command can be omitted
• cacheDirs: Optional project-relative cache directories removed by kibaco clean and kibaco restart --force

Remote projects are useful when the dev server runs on another machine but you want the same local browser URL:

{
  "proxyPort": 8080,
  "projects": [
    {
      "name": "web",
      "host": "remote-web.localhost",
      "remote": "devbox:3004"
    }
  ]
}

This runs ssh -N -L 3004:localhost:3004 devbox during kibaco dev and routes http://remote-web.localhost:8080 to http://127.0.0.1:3004. Use object form when the local tunnel port differs:

{
  "name": "web",
  "host": "remote-web.localhost",
  "remote": {
    "host": "devbox",
    "port": 3004,
    "localPort": 13004
  }
}

#Services

Services are Docker containers, Compose-backed services, or command-backed external services managed by Kibaco.

• name: Service name referenced by projects
• type: docker or command
• image: Docker image for Docker services
• start: Start command for command services
• stop: Optional stop command for command services
• status: Optional status command for command services
• logs: Optional log command for command services
• mode: Command service mode, such as oneshot
• stopOnExit: Stop a command service when kibaco dev exits
• urls: Optional service URLs shown by kibaco urls
• ports: Docker port mappings
• env: Environment variables passed to the container
• volumes: Docker volume mappings
• dependsOn: Services to start first
• healthCheck: Optional readiness check