workpeg 0.6.1

Workpeg function runtime and SDK

Workpeg SDK

Python SDK and CLI for building, packaging, publishing, and distributing Workpeg Pegs.

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

The SDK currently focuses on function-based Peg development, runtime tooling, Docker packaging, registry publishing, and CDN asset management. The CLI is namespace-oriented and designed to grow alongside the platform.

---

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 such as Docker.

Current namespaces:

workpeg function ...
workpeg cdn ...

Namespace	Purpose
function	Create, build, run and publish Workpeg Functions
cdn	Upload public Peg assets

Future namespaces may include:

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

Get help:

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

---

Quick Start

Create a Function

Create a new function project:

workpeg function new hello

Generated structure:

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

Example function:

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

---

Fast Local Runtime

For quick 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 a warm HTTP runtime:

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 a Function

Build a Docker image:

workpeg function build

Custom image tag:

workpeg function build --tag my-image

The build process creates a portable runtime image for the Function.

---

Run a Function

Run using Docker:

workpeg function run --with docker

This will:

• Build the image (unless disabled)
• Start a detached runtime container
• Enable warm execution
• Expose HTTP endpoints

Default endpoint:

http://localhost:8000

---

Docker Networking

Attach a runtime to a Docker network:

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

Assign a container name:

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

Other containers can then reach the runtime via:

http://calendar:8000

This allows multiple Pegs to run simultaneously without host port collisions.

---

Publish a Function

Submit a Function version to the Workpeg Registry:

workpeg function submit hello:1.0.0

Authentication:

export WORKPEG_PK=<your-token>

Default registry:

https://repo.workpeg.com

---

CDN Asset Uploads

Upload public Peg assets to the CDN.

Single file:

workpeg cdn submit logo.svg

Directory:

workpeg cdn submit ./assets

Current directory:

workpeg cdn submit .

Specify a target CDN path:

workpeg cdn submit ./assets --path assets

Replace existing assets:

workpeg cdn submit ./assets --overwrite

Upload an archive exactly without extraction:

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

Authentication uses:

export WORKPEG_PK=<your-token>

The CDN uses the same authentication token as the Registry.

---

Recommended Peg Asset Structure

assets/
├── logo/
│   ├── icon.svg
│   ├── icon.png
│   ├── light.svg
│   └── dark.svg
│
├── screenshots/
│   ├── 01-dashboard.png
│   ├── 02-mobile.png
│   └── 03-settings.png
│
├── banners/
│   ├── hero.png
│   └── cover.png
│
├── social/
│   └── og.png
│
└── metadata/
    └── manifest.json

Publish assets:

workpeg cdn submit ./assets --overwrite

---

Runtime Backends

Workpeg supports multiple runtime backends.

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

Select runtime:

workpeg function run --with docker

Resolution order:

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

---

Configuration

Optional project configuration:

workpeg.json

Example:

{
  "name": "hello",
  "description": "Example Workpeg Function",

  "runtime": {
    "default": "docker",
    "docker": {
      "port": 8000
    }
  },

  "build": {
    "image": "workpeg-fn-hello"
  },

  "function": {
    "entrypoint": "app.main:main"
  },

  "cdn": {
    "assets_path": "assets"
  }
}

---

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:

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

---

Development Lifecycle

Typical development flow:

workpeg function new hello

workpeg function build

workpeg function run --with docker

workpeg function submit hello:1.0.0

workpeg cdn submit ./assets --overwrite

Progression:

Developer
    ↓
Function
    ↓
Package
    ↓
Peg
    ↓
PegStore

---

Philosophy

Workpeg is designed around portable applications.

Core progression:

Developer → Function → Peg → PegStore → Ecosystem

• Functions provide reusable application logic
• Pegs package functionality into portable micro-apps
• PegStore enables discovery and distribution
• Workpeg provides the tooling required to build and publish them

The long-term goal is a platform where developers can create, distribute, and monetize applications through a unified ecosystem.

---

Roadmap

Planned:

• Firecracker runtime backend
• Persistent microVM execution
• Peg packaging workflows
• PegStore publishing tools
• Client application tooling
• Runtime orchestration
• Registry governance & approvals
• Distributed runtime scheduling
• Additional CLI namespaces

---

License

MIT License