Skip to content

wronai/pactown

BranchesTags

Repository files navigation

img.png

Pactown 🏘️

Decentralized Service Ecosystem Orchestrator – Build interconnected microservices from Markdown using markpact.

Python 3.10+ License

Overview

Pactown enables you to compose multiple independent markpact projects into a unified, decentralized service ecosystem. Each service is defined in its own README.md, runs in its own sandbox, and communicates with other services through well-defined interfaces.

┌─────────────────────────────────────────────────────────────────┐
│                     Pactown Ecosystem                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐   │
│  │   Web    │───▶│   API    │───▶│ Database │    │   CLI    │   │
│  │ :8002    │    │  :8001   │    │  :8003   │    │  shell   │   │
│  │ React    │    │ FastAPI  │    │ Postgres │    │  Python  │   │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘   │
│       │               │               │               │         │
│       ▼               ▼               ▼               ▼         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              markpact sandboxes (isolated)               │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Features

Core Features

  • 🔗 Service Composition – Combine multiple markpact READMEs into one ecosystem
  • 📦 Local Registry – Store and share markpact artifacts across projects
  • 🔄 Dependency Resolution – Automatic startup order based on service dependencies
  • 🏥 Health Checks – Monitor service health with configurable endpoints
  • 🌐 Multi-Language – Mix Python, Node.js, Go, Rust in one ecosystem
  • 🔒 Isolated Sandboxes – Each service runs in its own environment
  • 🔌 Dynamic Ports – Automatic port allocation when preferred ports are busy
  • 🔍 Service Discovery – Name-based service lookup, no hardcoded URLs
  • ⚡ Config Generator – Auto-generate config from folder of READMEs

New in v0.4.0

  • ⚡ Fast Start – Dependency caching for millisecond startup times (docs)
  • 🛡️ Security Policy – Rate limiting, user profiles, anomaly logging (docs)
  • 👤 User Isolation – Linux user-based sandbox isolation for multi-tenant SaaS (docs)
  • 📊 Detailed Logging – Structured logs with error capture (docs)

📚 Documentation

Quick Navigation

Category Documents
Getting Started Quick Start · Installation · Commands
Core Concepts Specification · Configuration · Network
Deployment Deployment Guide · Quadlet/VPS · Generator
Security Security Policy · Quadlet Security · User Isolation
Performance Fast Start · Logging
Comparisons vs Cloudflare Workers

All Documentation

Document Description
Specification Architecture and design
Configuration YAML config reference
Deployment Production deployment guide (Compose/Kubernetes/Quadlet)
Network Dynamic ports & service discovery
Generator Auto-generate configs
Quadlet Podman Quadlet deployment for VPS production
Security Quadlet security hardening and injection test suite
Security Policy Rate limiting, user profiles, resource monitoring
Fast Start Dependency caching for fast startup
User Isolation Linux user-based sandbox isolation
Logging Structured logging and error capture
Cloudflare Workers comparison When to use Pactown vs Cloudflare Workers

Source Code Reference

Module Description
config.py Configuration models
orchestrator.py Service lifecycle management
resolver.py Dependency resolution
network.py Port allocation & discovery
generator.py Config file generator
service_runner.py High-level service runner API
security.py Security policy & rate limiting
fast_start.py Dependency caching & fast startup
user_isolation.py Linux user isolation for multi-tenant
sandbox_manager.py Sandbox lifecycle management
registry/ Local artifact registry
deploy/ Deployment backends (Docker, Podman, K8s, Quadlet)

🎯 Examples

Example What it shows
examples/saas-platform/ Complete SaaS with Web + API + Database + Gateway
examples/quadlet-vps/ VPS setup and Quadlet workflow
examples/email-llm-responder/ Email automation with LLM integration
examples/api-gateway-webhooks/ API gateway / webhook handler
examples/realtime-notifications/ WebSocket + SSE real-time notifications
examples/microservices/ Multi-language microservices
examples/fast-start-demo/ NEW: Fast startup with dependency caching
examples/security-policy/ NEW: Rate limiting and user profiles
examples/user-isolation/ NEW: Multi-tenant user isolation

Installation

pip install pactown

Or install from source:

git clone https://github.com/wronai/pactown
cd pactown
make install

Quick Start

1. Create ecosystem configuration

# saas.pactown.yaml
name: my-saas
version: 0.1.0

services:
  api:
    readme: services/api/README.md
    port: 8001
    health_check: /health

  web:
    readme: services/web/README.md
    port: 8002
    depends_on:
      - name: api
        endpoint: http://localhost:8001

2. Create service READMEs

Each service is a standard markpact README:

# API Service

REST API for the application.

---

```python markpact:deps
fastapi
uvicorn
```

```python markpact:file path=main.py
from fastapi import FastAPI
app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}
```

```bash markpact:run
uvicorn main:app --port ${MARKPACT_PORT:-8001}
```

3. Start the ecosystem

pactown up saas.pactown.yaml
INFO:     127.0.0.1:57432 - "GET /health HTTP/1.1" 200 OK
INFO:     127.0.0.1:59272 - "GET /health HTTP/1.1" 200 OK
127.0.0.1 - - [15/Jan/2026 14:15:17] "GET /health HTTP/1.1" 200 -
INFO:     127.0.0.1:59300 - "GET /health HTTP/1.1" 200 OK
                Ecosystem: saas-platform                 
┏━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Service  ┃ Port  ┃ Status     ┃ PID    ┃ Health       ┃
┡━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━┩
│ database │ 10000 │ 🟢 Running │ 534102 │ ✓ 22ms       │
│ api      │ 10001 │ 🟢 Running │ 534419 │ ✓ 23ms       │
│ web      │ 10002 │ 🟢 Running │ 534424 │ ✓ 29ms       │
│ cli      │ 10003 │ 🔴 Stopped │ 534734 │ Process died │
│ gateway  │ 10004 │ 🟢 Running │ 535242 │ ✓ 23ms       │
└──────────┴───────┴────────────┴────────┴──────────────┘

Press Ctrl+C to stop all services

127.0.0.1 - - [15/Jan/2026 14:15:29] "GET / HTTP/1.1" 200 -
INFO:     127.0.0.1:42964 - "GET / HTTP/1.1" 200 OK
INFO:     127.0.0.1:53998 - "GET /health HTTP/1.1" 200 OK
INFO:     127.0.0.1:54008 - "GET /api/stats HTTP/1.1" 200 OK
INFO:     127.0.0.1:36100 - "GET /records/users HTTP/1.1" 200 OK
INFO:     127.0.0.1:54012 - "GET /api/users HTTP/1.1" 200 OK

Commands

Command Description
pactown up <config> Start all services
pactown down <config> Stop all services
pactown status <config> Show service status
pactown validate <config> Validate configuration
pactown graph <config> Show dependency graph
pactown init Initialize new ecosystem
pactown publish <config> Publish to registry
pactown pull <config> Pull dependencies

Registry

Pactown includes a local registry for sharing markpact artifacts:

# Start registry
pactown-registry --port 8800

# Publish artifact
pactown publish saas.pactown.yaml --registry http://localhost:8800

# Pull dependencies
pactown pull saas.pactown.yaml --registry http://localhost:8800

Registry API

Endpoint Method Description
/v1/artifacts GET List artifacts
/v1/artifacts/{ns}/{name} GET Get artifact info
/v1/artifacts/{ns}/{name}/{version}/readme GET Get README content
/v1/publish POST Publish artifact

Configuration Reference

name: ecosystem-name        # Required: ecosystem name
version: 0.1.0              # Semantic version
description: ""             # Optional description
base_port: 8000             # Starting port for auto-assignment
sandbox_root: ./.pactown-sandboxes  # Sandbox directory

registry:
  url: http://localhost:8800
  namespace: default

services:
  service-name:
    readme: path/to/README.md   # Path to markpact README
    port: 8001                  # Service port
    health_check: /health       # Health check endpoint
    timeout: 60                 # Startup timeout (seconds)
    replicas: 1                 # Number of instances
    auto_restart: true          # Restart on failure
    env:                        # Environment variables
      KEY: value
    depends_on:                 # Dependencies
      - name: other-service
        endpoint: http://localhost:8000
        env_var: OTHER_SERVICE_URL

Examples

See the examples/ directory for complete ecosystem examples:

  • SaaS Platform – Web + API + Database + CLI
  • Microservices – Multiple language services
  • Event-Driven – Services with message queues

Architecture

pactown/
├── src/pactown/
│   ├── __init__.py          # Package exports
│   ├── cli.py               # CLI commands
│   ├── config.py            # Configuration models
│   ├── orchestrator.py      # Service orchestration
│   ├── resolver.py          # Dependency resolution
│   ├── sandbox_manager.py   # Sandbox management
│   └── registry/
│       ├── __init__.py
│       ├── server.py        # Registry API server
│       ├── client.py        # Registry client
│       └── models.py        # Data models
├── examples/
│   ├── saas-platform/       # Complete SaaS example
│   └── microservices/       # Microservices example
├── tests/
├── Makefile
├── pyproject.toml
└── README.md

License

Apache License 2.0 – see LICENSE for details.

About

distributed markdown based modular software

Resources

Readme

License

Apache-2.0 license

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages