Kibaco

    Config Schema

    The schema is published in this repository at schemas/kibaco.config.schema.json.

    Root

    {
  "$schema": "https://kibaco.dev/schemas/kibaco.config.schema.json",
  "workspace": "my-app",
  "proxyPort": 8080,
  "log": {
    "maxBytes": 5242880,
    "maxFiles": 3
  },
  "services": [],
  "projects": []
}
    • workspace: Name used for Docker container names
    • proxyPort: Local proxy port
    • log: Per-project log rotation settings
    • services: Docker, Compose-backed, or command-backed services Kibaco can manage
    • projects: Local app commands and URL routes

    The standard project-local config path is:

    .kibaco/config.json

    This file should be ignored by Git. Commit kibaco.config.example.json instead.

    Project logs are stored under:

    ~/.kibaco/logs/{workspace}/{project}.log
~/.kibaco/logs/{workspace}/{project}.jsonl

    Command service logs are stored under:

    ~/.kibaco/logs/{workspace}/service-{service}.log

    Project

    {
  "name": "web",
  "host": "web.localhost",
  "target": "http://localhost:3000",
  "command": "pnpm dev",
  "cwd": ".",
  "services": ["postgres"],
  "healthCheck": {
    "type": "http",
    "url": "http://localhost:3000/api/health"
  }
}

    Project healthCheck is optional. kibaco dev --watch-health uses an HTTP project health URL when configured, otherwise it probes target.

    Remote project:

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

    When remote is set, target and command can be omitted. kibaco dev opens an SSH local forward and routes the proxy to the local tunnel port.

    Service

    Docker service:

    {
  "name": "postgres",
  "type": "docker",
  "image": "postgres:16",
  "ports": ["5432:5432"],
  "env": {
    "POSTGRES_PASSWORD": "postgres"
  },
  "volumes": [],
  "dependsOn": [],
  "healthCheck": {
    "type": "tcp",
    "host": "127.0.0.1",
    "port": 5432
  }
}

    Command service:

    {
  "name": "supabase",
  "type": "command",
  "start": "pnpm supabase:start",
  "stop": "pnpm supabase:stop",
  "status": "pnpm supabase:status",
  "logs": "pnpm supabase:logs",
  "mode": "oneshot",
  "stopOnExit": false,
  "healthCheck": {
    "type": "tcp",
    "host": "127.0.0.1",
    "port": 54321
  },
  "urls": [
    { "name": "api", "url": "http://127.0.0.1:54321" },
    { "name": "db", "url": "tcp://127.0.0.1:54322" },
    { "name": "studio", "url": "http://127.0.0.1:54323" }
  ]
}

    Health Check

    Supported types:

    • tcp
    • http
    • command

    Validation

    Run:

    kibaco config validate

    Typical output:

    Config file: ./.kibaco/config.json
Valid: true