workpeg 0.6.0

Workpeg function runtime and SDK

Workpeg SDK

Python SDK and CLI for building Workpeg Pegs and runtime-backed micro-apps.

Workpeg is a platform for developing portable applications called Pegs. Pegs can be packaged, executed, distributed through the PegStore, and integrated into the broader Workpeg ecosystem.

The SDK currently focuses on function-based Peg development, runtime tooling, Docker packaging, and asset distribution, while the CLI architecture is designed to expand into additional capabilities such as client applications, Peg packaging, orchestration, deployment infrastructure, and registry tooling.

Current capabilities

• Peg scaffolding
• Function-based runtime model
• Fast local runtime
• Persistent Docker runtime
• Docker image packaging
• Registry submission
• Public CDN asset uploads
• Runtime configuration
• Warm container execution
• Docker networking support

Repository

Workpeg SDK Repository

---

Installation

Install from PyPI:

pip install workpeg

Or install locally from source:

pip install -e .

Verify installation:

workpeg --version

---

CLI Architecture

Workpeg uses a namespace-oriented CLI inspired by tools like Docker.

Current namespaces:

workpeg function ...
workpeg cdn ...

Future namespaces may include:

workpeg client ...
workpeg peg ...
workpeg registry ...
workpeg runtime ...

Get help:

workpeg --help
workpeg function --help
workpeg cdn --help

---

Quick Start

Create a Function Peg

Create a new function project:

workpeg function new hello

Generated structure:

hello/
├── app/
│   ├── __init__.py
│   └── main.py
├── tests/
├── Dockerfile
├── requirements.txt
├── workpeg.json
└── README.md

Example function:

def main(context, payload):
    return {
        "message": "Hello from Workpeg",
        "payload": payload,
    }

---

Fast Local Runtime

For rapid iteration without Docker:

echo '{"context": {}, "payload": {"name":"world"}}' \
  | workpeg function runtime

Example response:

{
  "status": "success",
  "result": {
    "message": "Hello from Workpeg",
    "payload": {
      "name": "world"
    }
  }
}

---

Persistent Runtime Server

Run the runtime as a warm HTTP server:

workpeg function runtime --server

Default endpoint:

http://0.0.0.0:8000

Invoke:

curl -X POST http://localhost:8000/invoke \
  -H "Content-Type: application/json" \
  -d '{"context": {}, "payload": {"hello":"world"}}'

Health check:

curl http://localhost:8000/healthz

---

Build Docker Image

Build a Peg runtime image:

workpeg function build

Specify custom tag:

workpeg function build --tag my-image

The build process produces a portable runtime container for the Peg.

---

Run Peg Runtime (Docker)

Run a warm containerized runtime:

workpeg function run --with docker

This:

• Builds the image (unless disabled)
• Starts a detached persistent runtime container
• Exposes HTTP endpoints
• Enables warm execution

Default endpoint:

http://localhost:8000

---

Docker Networking

Attach runtimes to a Docker network:

workpeg function run \
  --with docker \
  --network workpeg_net

Useful for inter-Peg communication and local ecosystem development:

http://peg-name:8000

This enables multiple Peg runtimes to coexist without port collisions.

Example:

workpeg function run \
  --with docker \
  --network workpeg_net \
  --name calendar

Then other containers can reach it at:

http://calendar:8000

---

CDN Asset Uploads

Upload public Peg assets to the CDN:

Single file:

workpeg cdn submit logo.png

Directory:

workpeg cdn submit ./dist

Current directory:

workpeg cdn submit .

Custom CDN path:

workpeg cdn submit ./dist --path assets

Upload archive exactly without extraction:

workpeg cdn submit ./dist \
  --path archives/dist.tar.gz \
  --exact

Authentication uses:

export WORKPEG_PK=<your-token>

Default registry:

https://repo.workpeg.com

---

Detached Warm Runtime Model

The Docker runtime uses persistent detached containers instead of one-shot execution.

This enables:

• Warm execution
• Faster repeated invocations
• Health monitoring
• Automatic restarts
• Internal networking
• Future orchestration support

Execution progression:

Function → Runtime Container → Peg → PegStore

---

Runtime Backends

Workpeg supports multiple execution backends.

Runtime	Purpose	Status
docker	Local Peg development	Available
cracker	Firecracker microVM runtime	Planned

Select backend:

workpeg function run --with docker

Runtime resolution order:

1. CLI flag
2. workpeg.json
3. Fallback default (cracker)

---

Configuration

Optional project configuration:

workpeg.json

Example:

{
  "runtime": {
    "default": "docker",
    "docker": {
      "port": 8000,
      "network": "workpeg_net",
      "restart": "unless-stopped"
    }
  },
  "build": {
    "image": "my-custom-image"
  },
  "function": {
    "entrypoint": "app.main:main"
  }
}

---

Function Contract

Functions implement:

def main(context: dict, payload: dict):
    return {...}

Input:

{
  "context": {...},
  "payload": {...}
}

Success output:

{
  "status": "success",
  "result": {...}
}

Error output:

{
  "status": "error",
  "error_type": "...",
  "error": "..."
}

---

Entrypoint

Default entrypoint:

app.main:main

Override:

FUNCTION_ENTRYPOINT=app.main:handler \
  workpeg function runtime

---

Docker Requirements

Required for:

workpeg function build
workpeg function run --with docker

Requirements:

• Docker installed
• Docker daemon running
• Docker CLI available on PATH

When running inside another container:

-v /var/run/docker.sock:/var/run/docker.sock

---

Philosophy

Workpeg is designed around portable executable applications.

Core progression:

Function → Runtime → Peg → PegStore → Ecosystem

• Functions provide isolated runtime units
• Pegs package functionality into portable micro-apps
• PegStore enables discovery and distribution
• Workpeg provides runtime, packaging, and orchestration foundations

The long-term direction is a platform where developers can build, distribute, and execute intelligent applications inside a unified ecosystem.

---

Roadmap

Planned:

• Firecracker runtime backend
• Persistent microVM execution
• PegStore tooling
• Peg packaging workflows
• Client app tooling
• Runtime orchestration
• Streaming execution
• Registry approvals & governance
• Distributed runtime scheduling

---

License

MIT License