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

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 using JSON-based storage (no database required):

# 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

Storage Architecture

The registry uses file-based JSON storage instead of a database:

Location: .pactown-registry/index.json in your project directory
Format: Single JSON file containing all artifacts and versions
Content: Full README content, metadata, checksums, and version history
Benefits: No database setup, portable, version-controllable

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.

Name		Name	Last commit message	Last commit date
Latest commit History 214 Commits
docs		docs
examples		examples
src/pactown		src/pactown
tests		tests
tools		tools
.bumpversion.cfg		.bumpversion.cfg
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
TODO.md		TODO.md
VERSION		VERSION
examples.md		examples.md
goal.yaml		goal.yaml
img.png		img.png
project.functions.toon		project.functions.toon
project.sh		project.sh
project.toon		project.toon
project.toon-schema.json		project.toon-schema.json
pyproject.toml		pyproject.toml
saas.pactown.yaml		saas.pactown.yaml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Pactown 🏘️

Overview

Key Features

Core Features

New in v0.4.0

📚 Documentation

Quick Navigation

All Documentation

Source Code Reference

🎯 Examples

Installation

Quick Start

1. Create ecosystem configuration

2. Create service READMEs

3. Start the ecosystem

Commands

Registry

Storage Architecture

Registry API

Configuration Reference

Examples

Architecture

License

About

Uh oh!

Releases

Packages

Languages

License

wronai/pactown

Folders and files

Latest commit

History

Repository files navigation

Pactown 🏘️

Overview

Key Features

Core Features

New in v0.4.0

📚 Documentation

Quick Navigation

All Documentation

Source Code Reference

🎯 Examples

Installation

Quick Start

1. Create ecosystem configuration

2. Create service READMEs

3. Start the ecosystem

Commands

Registry

Storage Architecture

Registry API

Configuration Reference

Examples

Architecture

License

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages