Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ona.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Copy and adapt these examples for your projects. These patterns work for both humans and agents - when Ona Agent sees these tasks available, it can use them as part of its run loop.

​
Database provisioning

Start PostgreSQL and seed it with development data: 
services:
  postgresql:
    name: PostgreSQL
    description: Development database
    triggeredBy:
      - postDevcontainerStart
    commands:
      start: docker run --rm --name postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:15
      ready: docker exec postgres pg_isready -U postgres
      stop: docker stop postgres

tasks:
  seed:
    name: Seed database
    triggeredBy:
      - manual
    command: ./scripts/seed-dev-db.sh

​
Containerized services

Run services in Docker containers using docker run directly. This gives you full control over ports, volumes, environment variables, and container entrypoints.
Do not use docker run -d (detached mode) in a service start command. The -d flag makes docker run exit immediately, which causes the service to transition to Stopped. Run containers in the foreground so the process stays alive.
services:
  redis:
    name: Redis
    description: In-memory cache
    triggeredBy:
      - postDevcontainerStart
    commands:
      start: |
        if docker inspect redis >/dev/null 2>&1; then
          docker start -a redis
        else
          docker run --name redis -p 6379:6379 \
            -e REDIS_MAXMEMORY=256mb \
            -e REDIS_MAXMEMORY_POLICY=allkeys-lru \
            redis:7-alpine
        fi
      ready: docker exec redis redis-cli ping | grep -q PONG
      stop: docker stop redis

  elasticsearch:
    name: Elasticsearch
    description: Search engine
    triggeredBy:
      - manual
    commands:
      start: |
        if docker inspect elasticsearch >/dev/null 2>&1; then
          docker start -a elasticsearch
        else
          docker run --name elasticsearch -p 9200:9200 \
            -e discovery.type=single-node \
            -e xpack.security.enabled=false \
            -e ES_JAVA_OPTS="-Xms512m -Xmx512m" \
            elasticsearch:8.11.0
        fi
      ready: curl -sf http://localhost:9200/_cluster/health
      stop: docker stop elasticsearch
The if docker inspect pattern handles environment restarts — it reuses the existing container instead of failing on a name conflict.

​
Prebuild optimization

Speed up environment starts by running tasks during prebuild: 
tasks:
  install-deps:
    name: Install dependencies
    description: Install and cache all dependencies
    triggeredBy:
      - prebuild
    command: |
      npm ci
      go mod download
      pip install -r requirements.txt

  build-assets:
    name: Build static assets
    description: Compile CSS and bundle JavaScript
    triggeredBy:
      - prebuild
    dependsOn:
      - install-deps
    command: npm run build:assets

  warm-cache:
    name: Warm build cache
    description: Pre-compile common modules
    triggeredBy:
      - prebuild
    dependsOn:
      - install-deps
    command: go build -v ./...
Tasks with the prebuild trigger run during prebuild execution. Organization and project secrets are available, but user secrets are not.

​
Build and test pipeline

Chain tasks with dependencies: 
tasks:
  build:
    name: Build
    command: yarn && yarn build

  test:
    name: Run tests
    dependsOn:
      - build
    command: yarn test

  setup:
    name: Full setup
    dependsOn:
      - build
      - test
    triggeredBy:
      - postDevcontainerStart
    command: echo "Ready to develop"
Agents can run test knowing it will build first.

​
Cloud authentication

Authenticate with AWS using Ona’s identity provider: 
tasks:
  aws-auth:
    name: AWS Auth
    triggeredBy:
      - postEnvironmentStart
    command: ona idp login aws --role arn:aws:iam::123456789:role/dev-role

​
Preview server

Serve your application for testing: 
services:
  preview:
    name: Preview server
    triggeredBy:
      - postDevcontainerStart
    commands:
      start: |
        npm install
        npm run build
        npx serve -p 3000 ./build
      ready: curl -sf http://localhost:3000 > /dev/null
Agents can share this preview URL when demonstrating changes.

​
Jupyter notebook

Start Jupyter for data science work: 
services:
  jupyter:
    name: Jupyter Notebook
    triggeredBy:
      - manual
    commands:
      start: |
        pip install jupyter pandas numpy matplotlib
        jupyter notebook --ip=0.0.0.0 --no-browser
      ready: curl -sf http://localhost:8888 > /dev/null

​
Storybook

Component development with hot reload: 
services:
  storybook:
    name: Storybook
    triggeredBy:
      - manual
    commands:
      start: yarn storybook
      ready: curl -sf http://localhost:6006 > /dev/null

​
Parallel database testing

Test against multiple database versions: 
services:
  pg14:
    name: Postgres 14
    commands:
      start: docker run --rm --name pg14 -p 5432:5432 postgres:14
      ready: docker exec pg14 pg_isready
      stop: docker stop pg14

  pg15:
    name: Postgres 15
    commands:
      start: docker run --rm --name pg15 -p 5433:5432 postgres:15
      ready: docker exec pg15 pg_isready
      stop: docker stop pg15

tasks:
  test-compat:
    name: Compatibility tests
    triggeredBy:
      - manual
    command: |
      DATABASE_URL=postgres://localhost:5432 npm test
      DATABASE_URL=postgres://localhost:5433 npm test

​
Troubleshooting environment

Manual task for debugging production issues: 
tasks:
  troubleshoot:
    name: Setup troubleshooting
    triggeredBy:
      - manual
    command: |
      sudo apt-get update && sudo apt-get install -y htop iftop
      ./scripts/setup-vpn.sh