paglets - mobile python agents

paglets is a compact Python runtime inspired by Java Aglets. A paglet is a mobile object with explicit dataclass state, lifecycle hooks, message handling, and proxy-based control.

Resources:

Introduction / overview paper:

PyPI package:

The runtime intentionally uses a Python-friendly mobility model:

• all hosts already have the same code importable;
• every active paglet instance runs in its own child Python process;
• only dataclass state moves between hosts;
• control calls use a JSON HTTP API, while paglet movement uses a binary HTTP state payload to avoid JSON encoding large mobile state;
• large state is streamed for host-to-host movement and shared-memory local host/child handoff, while JSON remains the small control-plane format;
• same-host movement bypasses HTTP/TCP and delivers the serialized envelope directly inside the local host; different host processes on the same machine still communicate over loopback HTTP;
• lifecycle hooks resume behavior after create, dispatch, clone, retract, or activation;
• deactivation persists inactive paglets to disk until activation;
• agents communicate through PagletProxy, Message, and per-paglet serial child-process mailboxes;
• service discovery, transfer tickets, proxy references, context events, and resource cleanup are first-class framework features.

The process-per-paglet model isolates crashes and CPU-heavy work from the host and from other paglets, and it gives worker paglets real multi-core parallelism. The tradeoff is stricter importability, process startup overhead, and actor-style serial message handling inside each individual paglet.

Quick Start

Install and test the project in development:

uv run pytest -q

Run two hosts:

uv run paglets-host --name alpha --port 8765 --mesh-version dev
uv run paglets-host --name beta --port 8766 --peer http://127.0.0.1:8765 --mesh-version dev

For hosts on different machines, start each host with --bind-public:

uv run paglets-host --name mac --bind-public --port 8765 --mesh-version dev
uv run paglets-host --name windows --bind-public [IP] --port 8765 --mesh-version dev

Without an IP, --bind-public binds only the detected LAN address. With an IP, it binds only that supplied address. Repeat the flag to bind multiple specific addresses; the first one is published to the mesh. The auto form keeps watching the detected address and rebinds/publishes a new one after DHCP or network reconnect changes it.

For locked-down networks, one public HTTPS endpoint can act as a relay. Bind the paglets backend on server A to localhost, publish it through an existing reverse-proxy path such as /paglets, require an API key, and let other hosts connect outbound:

Example Nginx drop-in:

# Example: /etc/nginx/default.d/paglets.conf
# Include this from an existing HTTPS server block.
location /paglets/ {
    proxy_pass http://127.0.0.1:8765/;
    proxy_http_version 1.1;
    proxy_set_header Authorization $http_authorization;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
    client_max_body_size 256M;
}

/etc/nginx/default.d/paglets.conf is common on RHEL-style layouts when the site includes default.d/*.conf. On Debian/Ubuntu-style layouts, place the same location in /etc/nginx/sites-available/<site> or include it as a snippet from that server block. Test with sudo nginx -t before reloading.

export PAGLETS_API_KEY='change-me'
uv run paglets-host --name A --host 127.0.0.1 --port 8765 \
  --public-url https://server-a.example.com/paglets
uv run paglets-host --name B --connect-to https://server-a.example.com/paglets

Paglets commands read PAGLETS_API_KEY automatically. Use --api-key-env NAME only when the key lives in a different environment variable.

Connect-mode hosts do not open inbound ports. Movement and messages are relayed through A over authenticated HTTP long-polling, and git auto-update is disabled in this mode.

Relay forwarding is transparent to paglets: lifecycle events name the final target, arrivals run only there, and the source paglet is kept active when a relay delivery fails. Hubs expose GET /paglets/relay/diagnostics and support --relay-offline-after, --relay-delivery-timeout, and --relay-queue-limit for corporate network tuning.

On first start, paglets-host copies ~/.paglets/launch.toml from the bundled config. The default launch config declares built-in resident services for host inspection, mesh resource snapshots, compute-slot scheduling, and user notifications:

uv run paglets-sysinfo df
uv run paglets-sysinfo load
uv run paglets-mesh-info summary
uv run paglets-artifacts list
uv run paglets-compute-slots status
uv run paglets-compute-groups
uv run paglets-analysis-jobs --tasks 3 --target-runtime 3
uv run paglets-file-grabber push ./data.bin --remote beta --dest /tmp/data.bin --dry
uv run paglets-pi-compute --digits 16
uv run paglets-perf-test
uv run paglets-mesh-benchmark --payload-size 64K

paglets-file-grabber is the smallest natural file mobility example: the source paglet registers one file, dispatches to the destination host, and writes the arrived scratch copy to the requested path.

paglets-perf-test is a pure mobile-agent example: the entry host creates a parent benchmark paglet, clones workers to online same-version mesh hosts, runs local CPU, memory, and bounded temporary disk I/O checks, and reports the summary centrally.

paglets-mesh-benchmark measures mobile-agent movement itself. A starter paglet remains on the entry host while a traveler visits every directed host pair, stores per-hop timings locally on arrival, then collects and prints a directional Markdown matrix plus clock-offset and message round-trip diagnostics, ending with the overall benchmark time.

Run the disk survey demo:

uv run python demos/disk_survey_demo.py --hosts alpha beta gamma

Documentation Map

• Implementing Paglets: how to write paglet classes, state objects, lifecycle hooks, message handlers, movement, and mesh-aware behavior.
• Example Agents: detailed explanations of packaged example agents, including server-info, mesh-info, Pi compute, paglets-file-grabber, paglets-perf-test, and paglets-mesh-benchmark.
• Git Auto-Update: how trusted host meshes can pull, synchronize dependencies, broadcast commit hashes, and restart from updated code.
• Usage Ideas: practical scenarios where mobile state and agent-to-agent communication are a useful fit.
• Technical Overview: how the topic packages fit together and where implementation details live.
• Core, Runtime, and Remote: package-level implementation notes and generated API references for the main runtime subsystems.
• Glossary: terminology used by the project.

Build The Docs Locally

uv run --extra docs mkdocs serve

For a production build:

uv run --extra docs mkdocs build --strict