Repository Configuration

Each repository can include a ryven.json file at its root to customize how Ryven sets up and works with the codebase. This is optional — Ryven works without it, but the configuration gives you control over the development environment and agent behavior.

Creating ryven.json

Add a ryven.json file to the root of your repository:

{
  "setup": {
    "commands": [
      "npm install",
      "npm run build"
    ],
    "timeout": 300
  },
  "systemPrompt": "This is a TypeScript monorepo. Always run typecheck before committing. Prefer functional patterns.",
  "secrets": ["DATABASE_URL", "REDIS_URL"]
}

Setup commands

The setup.commands array defines shell commands that run before the agent starts working. Use these to prepare the development environment:

{
  "setup": {
    "commands": [
      "pnpm install",
      "pnpm run build",
      "pnpm run db:generate"
    ]
  }
}

Commands run sequentially in the repository root. If any command fails, the task is marked as failed.

Timeout

The setup.timeout field sets the maximum seconds per setup command (default: 120, max: 3600):

{
  "setup": {
    "timeout": 600
  }
}

System prompt

The systemPrompt field injects custom instructions into the agent's prompt (max 2000 characters):

{
  "systemPrompt": "You are working on a Next.js 14 app with App Router. Use server components by default. All API routes should validate input with Zod."
}

Good system prompts include:

• Framework and architecture context
• Coding conventions and patterns
• Testing requirements
• Common pitfalls to avoid

Secrets

The secrets array lists environment variable names to inject into the sandbox:

{
  "secrets": ["DATABASE_URL", "STRIPE_SECRET_KEY", "REDIS_URL"]
}

Only the listed variable names are injected — no other host environment variables are exposed to the sandbox.

Full reference

See the ryven.json reference for the complete schema and validation rules.