pactown 0.1.8

Decentralized Service Ecosystem Orchestrator - Build interconnected microservices from Markdown using markpact

Pactown 🏘️

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

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

• 🔗 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

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
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
registry/	Local artifact registry

Examples

Example	What it shows
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

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.