ryven.json Reference

The ryven.json file lives at the root of your repository and configures how Ryven sets up and interacts with the codebase.

Schema

{
  "setup": {
    "commands": ["npm install", "npm run build"],
    "timeout": 120
  },
  "systemPrompt": "Your project-specific instructions here.",
  "secrets": ["DATABASE_URL"]
}

All fields are optional.

Fields

setup

Configuration for pre-execution environment setup.

setup.commands

• Type: string[]
• Default: []
• Validation: Each string must be non-empty

Shell commands to run before the agent starts. Commands execute sequentially in the repository root.

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

If any command fails (non-zero exit code), the task is marked as failed.

setup.timeout

• Type: number (integer)
• Default: 120
• Min: 1
• Max: 3600

Maximum seconds per individual setup command. If a command exceeds this timeout, it is killed and the task fails.

systemPrompt

• Type: string
• Default: none
• Max length: 2000 characters

Custom instructions injected into the agent's prompt. Use this to provide context about your codebase, coding conventions, or specific requirements.

{
  "systemPrompt": "This is a Django REST Framework API. Use class-based views. All endpoints must have OpenAPI docstrings. Run pytest before committing."
}

secrets

• Type: string[]
• Default: []
• Validation: Each string must be non-empty

Environment variable names to inject into the sandbox. Only the listed names are exposed — all other host environment variables are hidden.

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

Full example

{
  "setup": {
    "commands": [
      "npm ci",
      "npm run build",
      "npm run db:migrate"
    ],
    "timeout": 300
  },
  "systemPrompt": "TypeScript monorepo with Turborepo. Packages: @acme/api (Hono), @acme/web (Next.js), @acme/db (Drizzle). Always run typecheck. Use barrel exports. Prefer Zod for validation.",
  "secrets": ["DATABASE_URL", "GITHUB_TOKEN"]
}

Validation

The file is validated with Zod on task startup. If validation fails, the task is marked as failed with a descriptive error message. Common validation errors:

• systemPrompt exceeding 2000 characters
• setup.timeout outside the 1–3600 range
• Empty strings in commands or secrets arrays