workpeg 0.5.1

Workpeg function runtime and SDK

Workpeg SDK

Python SDK and CLI for building Workpeg Pegs and execution workloads.

Workpeg is a platform for developing portable micro-apps 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 and local runtime tooling, while the CLI architecture is designed to expand into additional capabilities such as client applications, Peg packaging, registry tooling, runtime orchestration, and deployment infrastructure.

Current capabilities

• Peg scaffolding
• Function-based execution model
• Fast local runtime
• Persistent Docker runtime
• Docker image packaging
• Registry submission
• Runtime configuration
• Warm container execution

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 namespace:

workpeg function ...

Future namespaces may include:

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

Get help:

workpeg --help
workpeg function --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 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.

---

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

Example execution model:

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 composable executable applications.

Core progression:

Function → Runtime → Peg → PegStore → Ecosystem

• Functions provide isolated execution units
• Pegs package functionality into portable micro-apps
• PegStore enables distribution
• Workpeg provides the runtime and orchestration foundation

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