Damascus Frontier

Deployment CLI and configuration for the Damascus agent orchestration framework.

One command to deploy your agent swarm. Bring your own personas and skills.

---

Quick start

npx damascus setup

Interactive wizard:

1. Select which agents to deploy (primary, researcher, orchestrator, validator, builder)
2. Point to custom personas and skills (or use built-in)
3. docker-compose.generated.yml is written
4. docker compose -f docker-compose.generated.yml up -d

Configuration

Create damascus.yaml in your project:

version: "1"

agents:
  primary:
    persona: primary
  researcher:
    persona: researcher
  orchestrator:
    persona: orchestrator

# Optional: bring your own agents and skills
custom:
  personas: ./my-personas/
  skills: ./my-skills/

infra:
  postgres:
    port: 5432
  redis:
    port: 6379
  litellm:
    url: ${LITELLM_URL}

Run damascus setup (or damascus setup --non-interactive to skip prompts).

How customization works

1. Personas — drop a .md file in ./my-personas/. Same format as built-in personas (YAML frontmatter + markdown).
2. Skills — drop .md files in ./my-skills/global/ (available to all agents) or ./my-skills/{agent-id}/ (agent-specific).
3. Custom wins — if a custom skill has the same name as a built-in, the custom one is used.
4. No rebuild needed — mounts are bind volumes. Edit a .md, restart the container.

Commands

Command	What it does
damascus setup	Interactive wizard → generates compose file
damascus setup --non-interactive	Reads damascus.yaml directly, no prompts
damascus validate	Validates damascus.yaml schema
damascus plan	Dry-run: shows what compose file would be generated

Docker Compose output

Every damascus.yaml produces exactly the services you listed. No extra containers.

services:
  postgres:
    image: postgres:16-alpine
  redis:
    image: redis:7-alpine
  primary:        # ← only if listed in agents
    image: ghcr.io/kaykayyali/damascus-v3:latest
    environment:
      AGENT_ID: primary
    volumes:
      - ./my-personas/primary.md:/app/personas/primary.md:ro

Related repos

Repo	Purpose
damascus-v3	Agent engine (TypeScript, BullMQ, PostgreSQL)
damascus-dashboard	Chat-first web dashboard (Solid.js)