OpenASE
_{Issue-Driven Automated Software Engineering}

OpenASE is an all-in-one platform that turns tickets into working code — AI agents automatically pick up issues, execute workflows on your machines, and deliver results with full traceability.

✨ Key Features

📋 Ticket-Driven Orchestration Kanban Board & List Views Parent/Child & Dependency Tracking Custom Statuses & Priorities Repository Scope Binding	🤖 Multi-Agent Support Claude Code / Codex / Gemini CLI Real-time Streaming Output (SSE) Agent Lifecycle Management Concurrent Execution Control	⚡ Workflow Engine Markdown Harness Documents Skill Binding & Lifecycle Hooks Scheduled Cron Jobs Built-in Role Templates
🖥️ Machine Management SSH / Local / Cloud VMs Health Monitoring & Probes CPU / Memory / Disk Metrics Connectivity Diagnostics	🔐 Auth & Security OIDC Browser Login (Auth0, Entra ID) Agent Platform Token Auth Org & Project RBAC GitHub Credential Management	📡 Observability Live Activity Event Stream Agent Run Step Tracking GitHub Webhook Ingestion Project Update Threads

🤔 What is OpenASE?

OpenASE is a single Go binary that ships an API server, workflow orchestrator, and embedded web UI together. It follows an issue-driven model: every piece of work is a ticket, every ticket has a workflow, and AI agents automatically pick up and execute tickets based on status triggers.

You create a ticket  →  Orchestrator detects pickup status
    →  Agent claims the ticket  →  Executes workflow on a Machine
    →  Activity stream records every step  →  Ticket completes

No Node.js at runtime — the SvelteKit frontend is compiled and embedded into the Go binary via go:embed.

🚀 From Zero to Running

This section walks through everything you need on a fresh machine — from installing system dependencies to opening the web UI.

Step 0: System Prerequisites

# Download (adjust version and OS/arch as needed)
wget https://go.dev/dl/go1.26.1.linux-amd64.tar.gz

# Extract to /usr/local (requires sudo)
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.26.1.linux-amd64.tar.gz

# Add to PATH — append to ~/.bashrc or ~/.zshrc
export PATH=$PATH:/usr/local/go/bin

# Verify
go version   # go1.26.1 linux/amd64

export PATH=$PWD/.tooling/go/bin:$HOME/.local/go1.26.1/bin:$PATH

# Option A: via nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

# Option B: via package manager (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Enable corepack for pnpm
corepack enable

# Verify
node --version   # v22.x.x
pnpm --version   # 10.x.x (via corepack)

# Install Docker if not present
sudo apt-get update && sudo apt-get install -y docker.io
sudo usermod -aG docker $USER
newgrp docker   # or re-login

# OpenASE setup will create the container for you automatically

# Ubuntu/Debian
sudo apt-get install -y postgresql postgresql-client

# Create database and user
sudo -u postgres psql -c "CREATE USER openase WITH PASSWORD 'openase';"
sudo -u postgres psql -c "CREATE DATABASE openase OWNER openase;"

# Verify
psql postgres://openase:openase@localhost:5432/openase?sslmode=disable -c "SELECT 1;"

# Ubuntu/Debian
sudo apt-get install -y git make curl wget

# Verify
git --version
make --version

Step 1: Clone & Build

git clone https://github.com/PacificStudio/openase.git
cd openase

# Build frontend + Go binary in one command
make build-web

This runs the following under the hood:

corepack pnpm --dir web install --frozen-lockfile
corepack pnpm --dir web run api:generate
corepack pnpm --dir web run build
go build -o ./bin/openase ./cmd/openase

Verify the build:

./bin/openase version

Step 2: Run First-Time Setup

./bin/openase setup

The interactive terminal setup will walk you through:

1. Database — start a Docker PostgreSQL automatically, or enter an existing DSN
2. CLI detection — checks for git, claude, codex, gemini on PATH
3. Auth mode — disabled (local dev) or oidc (browser login)
4. Service mode — config-only, or install a systemd --user service
5. Seed data — creates org, project, ticket statuses, and detected providers

Setup creates the following under ~/.openase/:

~/.openase/
├── config.yaml       # Runtime configuration
├── .env              # Platform auth token
├── logs/             # Service logs
└── workspaces/       # Agent workspaces

Docker PostgreSQL note: When choosing Docker, setup uses predictable defaults — container openase-local-postgres, port 127.0.0.1:15432, database openase. It generates the password automatically.

Step 3: Launch

# All-in-one: API server + orchestrator in a single process
./bin/openase all-in-one --config ~/.openase/config.yaml

The control plane is now available at:

http://127.0.0.1:19836

Tip: Run ./bin/openase doctor --config ~/.openase/config.yaml to diagnose any issues.

Step 4: Verify

# Health checks
curl -fsS http://127.0.0.1:19836/healthz
curl -fsS http://127.0.0.1:19836/api/v1/healthz

# Or use the built-in doctor
./bin/openase doctor --config ~/.openase/config.yaml

Open http://127.0.0.1:19836 in your browser — you should see the OpenASE control plane.

What's Next?

Now that the platform is running, follow the User Guide — Quick Start to:

1. Configure ticket statuses and connect a repository
2. Register a machine and an AI agent
3. Create your first workflow and ticket
4. Watch the agent execute automatically

🔧 Alternative Run Modes

Managed User Service

Setup can install a systemd --user service automatically. You can also manage it manually:

./bin/openase up      --config ~/.openase/config.yaml   # Install & start
./bin/openase logs    --lines 100                        # Tail logs
./bin/openase restart                                    # Restart
./bin/openase down                                       # Stop & uninstall

Split-Process Mode

Run API server and orchestrator as separate processes:

./bin/openase serve       --config ~/.openase/config.yaml
./bin/openase orchestrate --config ~/.openase/config.yaml

Environment-Only Mode

If you prefer env vars over config files:

export OPENASE_DATABASE_DSN=postgres://openase:openase@localhost:5432/openase?sslmode=disable
export OPENASE_SERVER_PORT=19836
export OPENASE_ORCHESTRATOR_TICK_INTERVAL=2s

./bin/openase all-in-one

Or source from ~/.openase/.env:

set -a && source ~/.openase/.env && set +a
./bin/openase all-in-one

⚙️ Configuration

Environment Variables

Config File Lookup Order

1. --config <path> flag
2. ./config.yaml (or .yml, .json, .toml)
3. ~/.openase/config.yaml
4. OPENASE_* environment variables + built-in defaults

Authentication

OIDC supports standard providers: Auth0, Azure Entra ID, and any OpenID Connect compliant IdP. See OIDC & RBAC Guide for setup.

🏗️ Architecture

Product Shape

Repository Layout

openase/
├── cmd/openase/              # CLI entrypoint
├── internal/
│   ├── app/                  # App wiring (serve / orchestrate / all-in-one)
│   ├── httpapi/              # HTTP API, SSE, webhooks, embedded UI
│   ├── orchestrator/         # Scheduling, health checks, retries
│   ├── workflow/             # Workflow service, harness, hooks, skills
│   ├── agentplatform/        # Agent token auth
│   ├── setup/                # First-run setup
│   ├── builtin/              # Built-in role & skill templates
│   └── webui/static/         # Embedded frontend output
├── web/                      # SvelteKit control plane source
├── docs/
│   └── guide/                # User guide (per-module docs)
├── config.example.yaml
├── Makefile
└── go.mod

System Flow

flowchart LR
    U[User / Scheduled Job] --> T[Ticket]
    T --> O[Orchestrator]
    O -->|status trigger| A[Agent]
    A --> W[Workflow + Harness]
    W --> S[Skills]
    A -->|executes on| M[Machine]
    M --> R[Results]
    R --> E[Activity Stream]
    E --> UI[Web Control Plane]

🖥️ Control Plane

The embedded web UI provides a complete project management experience:

💻 CLI Reference

OpenASE follows a GitHub-style dual-layer CLI contract:

Resource Commands

openase ticket list       --status-name Todo --json tickets
openase ticket create     --title "Fix login bug" --description "..."
openase ticket update     --status_name "In Review"
openase ticket comment    create --body "Blocking dependency found"
openase ticket detail     $PROJECT_ID $TICKET_ID

openase workflow create   $PROJECT_ID --name "Codex Worker"
openase scheduled-job trigger $JOB_ID
openase project update    --description "Latest context"

Raw API Escape Hatch

openase api GET  /api/v1/projects/$PID/tickets --query status_name=Todo
openase api PATCH /api/v1/tickets/$TID --field status_id=$SID

Live Streams

openase watch tickets $PROJECT_ID

Output Formatting

--jq '<expr>'              # JQ filter
--json field1,field2       # Select fields
--template '{{...}}'       # Go template

Both --kebab-case and --snake_case flag spellings are accepted.

🔌 Agent Platform

Agent workers inherit environment variables from the workspace wrapper:

🛠️ Development

Build Commands

make hooks-install        # Set up git hooks (lefthook)
make check                # Run formatting + backend coverage checks
make build-web            # Build frontend + Go binary
make build                # Build Go binary only (uses existing frontend)
make run                  # Run API server in dev mode
make doctor               # Run local environment diagnostics

Frontend Quality Gates

make web-format-check     # Prettier formatting
make web-lint             # ESLint checks
make web-check            # Svelte type checking
make web-validate         # All of the above

OpenAPI Contract

make openapi-generate     # Regenerate api/openapi.json + TS types
make openapi-check        # Verify committed artifacts are up-to-date

Testing

make test                        # Go test suite
make test-backend-coverage       # Full backend tests + coverage gate
make lint                        # Lint changes since origin/main
make lint-all                    # Full lint suite

📖 Documentation

📄 License

See LICENSE.

OpenASE
Create the ticket. The agent does the rest.