Skip to main content

HOMING PIGEON

Homing Pigeon gives cloud AI like ChatGPT, Claude, Gemini a secure and signed channel to your machine or network.

Install the runner and try this careful prompt with Grok for example, after you set up an email connector:

Run a pigeon-home.ai job
Runner mailbox is your_email@pigeon-home.ai
Find the Shared Secret in my mailbox and reply_to self
Retrieve the system clock and display it

The Homing Pigeon runner, like a GitHub runner, polls and executes signed jobs from a source in the cloud. Setup walks you through connecting a dedicated mailbox. The recommended path is a browser sign-in, so the account password never lands in a config.

Homing Pigeon IETF Internet-Drafts:

Homing Pigeon — how it fits together

What this is for

Homing Pigeon is a personal remote-development agent. The point is not that the SI becomes smarter. It is that the SI gets a way to delegate work to a computer it could not otherwise reach. The most powerful computer you have access to should not stop being useful the moment you walk away from your desk, and neither should your SI assistant.

Concrete uses:

  • Remote test runs. Ask your SI to run the suite, read the failures, patch the code, rerun, and report back, all while you are away from the machine.
  • Your hardware as a worker. Long builds, data crunching, batch jobs, on the workstation you own, without a remote-desktop session open.
  • Scheduled-style automation. Maintenance scripts, reports, and repetitive technical tasks, dispatched from your phone.
  • Cloud SI, local resources. Your files, your dev environment, your GPU, reachable by an assistant that lives in the cloud.
  • Physical peripherals. Plug a sensor or servo board into a Raspberry Pi, point your SI at it, and let it write the control code and debug the hardware into motion. You do the soldering, it does the head-scratching.

The SI can be an assistant that operates, not just advises. Which machine is your choice: your workstation, a spare box in the corner, a Raspberry Pi. A new model claims to be good at something, such as robotics, automation, or data work? Point it at a box and find out.

The runner belongs to the same family as GitHub self-hosted runners, VS Code Remote tunnels, and Tailscale. Simple tools for administering your own hardware.

  SI (cloud)                        Your machine
  ------------                      ------------------
  send_job.py --sign--> job message -->  runner.py
       |                  |              |  poll IMAP
       |                  |              |  verify HMAC
       |                  |              v
       |                  |           run script
       |                  |              |
       |             result message <--+ sign
       v                  |
  verify result <----------+

Large inputs don't go through email: your SI uploads them to file hosting and the job message carries download URLs (with optional SHA-384).

Why email? Because it's the only transport with all four properties on day one: reachable from anywhere, outbound-only polling (no inbound ports, NAT-proof), at-least-once delivery, and zero infrastructure to operate. The protocol does not care about the pipe. Every transport is an extension the runner supervises (a watched folder, core NATS, a direct DTLS session binding and the hosted HTTPS queue ship alongside email), but email stays the default; a credentialed transport adds its own required gate beside the signature, which makes it the more secure option even though it is not the default. (A sensor on the same box also delivers its signed alerts directly, by local inbox or loopback socket: alerts, not jobs.)

Runbooks, not prompts. The SI doesn't chat about the task; it ships a runbook: deterministic steps, each with a check that proves the step worked. The runner executes it and reports back what actually happened, and that feedback goes into the next runbook. Each cycle is a little smarter than the last, because the failures are data. If you've ever debugged something by running it, reading the output, and trying again with what you learned, that's the whole product. The SI is just the part that writes the next attempt.

The Oracle: the witness on your side of the wire

The runner faces the SI. The Oracle faces you. It is the part of the agent that works for the owner of the box: it watches every job as it runs, checks each job against this machine before it runs (opinions, below), fuses the box's sensor alerts with job activity, and, in the watching postures, pages you when something trips. It also answers the SI's questions about job output, at the disclosure ceiling you set, and not one byte past it.

That ceiling is the thing to understand. By default it is attested: the SI does not see what the job printed. It questions the Oracle rather than inspecting output, and gets back HMAC-signed attestations ("did the tests pass?", "does the output contain secrets?"), which are proofs about the output that reveal nothing else: the interactive-proof shape applied at the trust boundary, the proof an HMAC and the runner itself trusted, no zero-knowledge machinery. Full output is there when the owner wants it: set the ceiling to full in the config and the SI sees what the job printed, at the price of everything the job can print crossing the wire.

  Cloud SI                                  Your machine
  --------                                  ------------

  "Did the tests pass?" --signed-------> +-----------------+
                                         | The Oracle      |
  "Any secrets in there?" -------------> |                 |
                                         | output stays    |
                                         | on your disk    |
  +------------------------+             |                 |
  | signed attestation     | <--signed-- | answers only    |
  | { exit_zero: true,     |             | what policy     |
  |   no_secrets: true }   |             | allows          |
  +------------------------+             +-----------------+

  The SI learns what your ceiling allows.

Queries are declared upfront (no adaptive probing), each job gets a privacy budget bounding total leakage, and the disclosure ceiling is set by you in config, never by the SI.

Your machine runs two roles in one box:

+------------------------------+------------------------------+
| RUNNER (faces the SI)        | ORACLE (faces you)           |
+------------------------------+------------------------------+
| polls the mailbox            | watches jobs as they run;    |
| verifies HMAC + key policy   | its opinions ride results    |
| judge: an opt-in gate        | fuses sensor alerts          |
| runs jobs; caged by default  | watches resources            |
| answers queries at the       | pages you when a             |
| ceiling you set -- the       | threshold trips              |
| default is attested          | orders kills via remediation |
+------------------------------+------------------------------+

The runner does what the SI asks. The Oracle watches what happens and tells you about it.

Opinions, before anything runs. By default the Oracle checks each job against this box first: is the named interpreter here? are the tools it invokes on PATH? does the script's shape fit this OS? Its default latitude is repair: the one mechanical fix those checks can prove (an absent interpreter, replaced with the platform default when the script's shape fits it) is applied, and never silently. The result says what changed, carries received_digest (the job exactly as received, by digest), and the repaired job is judged again before it runs. The owner's oracle_opinion_mode is both the default latitude and the ceiling: a job may ask for less, never more. Design: docs/steady/design/oracle-opinion-design.md.

Fixes mismatched jobs, never silently. A job that asks for bash but only needs sh is repaired and runs on a minimal system like Alpine (BusyBox, no bash); a job that really needs bash or PowerShell is left alone. Every repair is stated in the result.

minimal-userland

Operating modes

Three parties appear below, always under the same names. The SI is the cloud AI that sends jobs. The owner is you, the person who installed this on the box and edits its config.json. The Oracle is the part of the agent on the box that works for the owner: it watches jobs, and pages the owner. The runner is the part that executes what the SI sends. Five owner-set knobs decide the posture; they are independent, and these are three coherent postures, not the only combinations. Each is a choice about trust, the owner's to pick per machine.

  knob                  just run it  eyes open    lockdown
  ------------------    -----------  ---------    --------
  judge                 off          advisory     enforce
  sensors               off          on           on
  resources             on           on           on
  dri                   off          on           on
  max_result_view       attested     attested     attested

just run it (the config-file defaults): any signed job runs; results return as attestations; the Oracle reviews and logs but never pages and never blocks. eyes open (recommended): the Oracle watches on your behalf; verdicts ride each result, alerts fuse, and trips page you. lockdown: the box refuses what the policy rejects, and pages you on every refusal. A fresh install starts one notch tighter than the defaults, under an installer profile. The postures and the profiles in full: docs/infrastructure-documents/oracle/configuring-oracle.md.

Two more dials stand outside the table.

  remediation_mode     what happens while a job runs
  -------------------  ------------------------------------------

  deterministic        a tripwire trips: kill the job's process
  (the default)        tree, quarantine the outputs, refer the
                       suspect files to the antivirus, file the
                       story with the DRI, page the owner

  oracle               the local model may also order a kill
                       for a lesser divergence

  off                  watches and records only

The tripwires are a closed list: a confinement escape, a process storm past the ceiling, an undeclared credential-store reference in something the job produced. Design: docs/steady/design/remediation-design.md. The opinion latitude (oracle_opinion_mode, default repair) is the other dial; it is covered under Opinions, above.

Confinement comes in two kinds, and they are not the same kind of thing. The workspace snapshot detects: it compares file metadata around the run and attests confined_to_workspace, which is a record, not a cage (PROTOCOL.md section 9.4). The confinement backends prevent: bubblewrap on Linux, a restricted token and Job Object on Windows, a per-job jail on FreeBSD, a Seatbelt profile on macOS. The key is security.modes.confinement; the mode defaults to enforce, and at enforce a job whose confinement cannot engage is refused, never run weaker. Each backend's reach and limits: SECURITY.md and docs/support-matrix.md.

Local inference. Point the Oracle at a model running on your own box and the SI can ask questions in plain English ("why did the tests fail?"), answered locally, with only the answer crossing the boundary. The endpoint must be loopback (fail closed), and every answer is truncated, redacted, and secret-scanned before it's sent. The SI gets useful answers, and your raw data never leaves the machine. Setup: docs/infrastructure-documents/oracle/configuring-oracle.md.

Two Oracle modes.

  oracle_mode          model               briefs and answers    ask
  -------------------  ------------------  --------------------  ---

  "llm" (the default)  the local model     narrated by model     on

  "deterministic"      none installed,     the box's own         off
                       never called        records

"deterministic" is the Pi Light mode, for a box with no model worth running: the watch, the wake gate, and the briefs still run. The mode reads live from config.json; flipping it is the upgrade path when a box gains a model worth running. See docs/infrastructure-documents/oracle/configuring-oracle.md.

The Oracle learns from its own calls. Each opinion is frozen before the job runs, scored against what actually happened the moment the job finishes, and written to a local ledger (oracle-learning.jsonl); the next job's opinion is formed with that ledger read fresh, no restart. Lessons are verified facts, derived by code from execution records, and (only when the owner enables the model channel) model candidates, labeled uncorroborated wherever they surface until later verified outcomes corroborate them. A lesson never authorizes anything by itself. Set oracle_learning to false to turn the loop off. Design: docs/steady/design/oracle-opinion-design.md. Measured on a real rig in deterministic mode: 1,967 of 2,248 reconciled calls right (87.5%), 0 lessons, every miss a job that simply ran exit 3 (live examples).

Full spec in PROTOCOL.md (sections 9–12). Oracle fields are optional members of a "v": 1 message. They are not a separate message version.

Extending the agent: senses and transports

Extensions let you teach the agent a new sense. An extension is a folder with a manifest (extension.json) that declares, in advance, the signals it may send the Oracle, with each signal named and given a one-line description. That declaration is the context the Oracle receives alongside the alerts: a signal the manifest does not declare is rejected at ingest and logged, never passed through, so the Oracle is never asked to interpret a signal nobody defined.

The research loop is the point. Clone the repo, copy the example extension, and iterate on your own package: your data, your heuristics, your version number, revved as often as you like. The extension API the manifest is written against is version 1 and is designed to stay there: fields may be added, never removed or reinterpreted, so an extension written today keeps loading. An extension binds to its own signing key, exactly like the built-in senses, and files alerts the Oracle fuses with job activity.

Nothing signs an extension's code, so the agent reads it against the manifest before loading it. The reading checks 6 things:

  check             the rule
  ----------------  ------------------------------------------

  capabilities      the manifest's `capabilities` list
                    (`network`, `listen`, `subprocess`,
                    `native`) has to cover what the code does

  entry             a transport's `entry` has to stay inside
                    its folder

  compiles          every file has to compile

  symlink           no symlink gets through

  bidi              no bidi control character gets through

  runner state      no reference to the runner's own state
                    gets through

By default a folder that contradicts its manifest is refused like a bad one and the agent runs without it (extension_review turns that to advisory or off; --inspect review shows the verdicts).

The example is a lab-results sense: it watches a folder where experiment runs drop result files and files signals like experiment_finished and metric_threshold_crossed when a run lands. Full walkthrough: docs/steady/extensions.md.

Every extension, sense or transport, also brings its own code for the Oracle. On a box where a local model runs the Oracle, the first time an extension runs, the agent gives the Oracle the extension's installed code and fetches, in the background, whatever its optional sources.json declares: its published source, the upstream project it wraps, the specifications it speaks.

The release ships only the declarations and the build's SHA-384 pins of what they name; the box fetches the sources and refuses bytes that differ from a pin, and an entry nothing pins waits until the owner allows it. A deterministic box (Pi Light) has no model to read the material and makes no request for it unless its owner turns the fetch on. The Oracle gets what is pinned by default, and a written disclosure rule lets the owner (or the author) withhold any of it (docs/steady/extensions.md, "Sources").

Layout

PROTOCOL.md is the wire protocol, runner/ the code, runner/extensions/ the shipped extensions, docs/ the long shelf and .github/ the CI. The file-by-file map is in docs/infrastructure-documents/project/layout.md.

Setup

⚠️ USE AT YOUR OWN RISK. Installing this application hands full administrative control of the system to whoever holds the shared secret. The holder can install software, read files, add users, and pivot to your network.

Setup lives in INSTALL.md: the three install paths (Docker, pip, release binary) and the full first-run walkthrough (dedicated mail account, app password, shared secret, first job).

No spare machine? One command puts a runner on a small machine (about $2 a month on Fly, a few dollars on Hetzner or DigitalOcean) in your own account, with the hosted profile and nothing listening: docs/steady/use/own-cloud.md. Your account, your bill, your secret.

Proven platforms

The platform proof story lives with setup now: Proven platforms in INSTALL.md, with the full table and the board notes in docs/steady/use/platforms.md.

How scripts run

A job carries a script and an optional interpreter; the default is PowerShell on Windows and sh elsewhere, and a ping first tells you which one a box has. Details are in docs/infrastructure-documents/use/scripts.md.

Sending a job (any SI)

Anything that can email the runner's mailbox and sign the body can drive it: your SI, a cron script, whatever, using runner/cloud/send_job.py and the shared_secret from your config.json. Commands and verification are in docs/steady/sending.md.

Testing

The runner is fully inspectable, so audit what it would do before it does it, and run the suite with python -m unittest discover -s runner/tests -t .. The flags and the suite notes are in docs/infrastructure-documents/project/testing.md. A reader who cannot run the suite can still read it whole: the latest published release (https://github.com/Pigeon-Home/homing-pigeon/releases/latest) carries a project snapshot of the entire tree (tests, CI facts, and test results included) as homing-pigeon-project-<version>.tar.gz, checkable against the release's SHA384SUMS.

Security notes

  • Threat model: docs/infrastructure-documents/security/threat-model.md and its companion docs/infrastructure-documents/security/security-gaps.md.
  • OWASP reference: docs/infrastructure-documents/security/owasp-reference.md, which gathers in one place the OWASP risk lists, verification standard, testing guides and cheat sheets this project consults.
  • Industry map: docs/steady/project/industry-map.md, which covers five years of commercial detection (2021 to 2026) read honestly against this project, sorted by local footprint cost.
  • Jobs are also encrypted by default: send_job.py wraps the signed body in an AES-256-GCM envelope keyed from the shared secret.
  • send_job.py --cleartext sends the plain HMAC-signed body instead, and the runner refuses it unless started with --allow-cleartext. The shared secret is still required. One honest limit, stated wherever this is described: there is no forward secrecy unless it is provided by the transport layer.
  • Execution is at-most-once, delivery at-least-once: a result is stashed under <base_dir>/outbox/ and the job committed as seen before the first send; a send that fails is resent from the stash on later polls, never produced by a second run, and given up into outbox/failed/ after a day (--inspect outbox; PROTOCOL.md section 5).
  • Size caps: max_job_bytes (default 4 MiB) bounds a raw job mail before its signature is checked.
  • Optional hardening controls (on by default at enforce; the size caps above are also on by default and turned off by 0): see SECURITY.md.
  • The security model (the gate, the key fences, the ceilings a job cannot raise, and the configuration rules) and the formal proof testing that checks it, property by property, are described in docs/infrastructure-documents/security/model-and-proof-testing.md.
  • What the security token count is made of is charted in the statistics record; the chart itself:

What the security-token count is made of: one fuzz run log and everything else

Questions people ask

The FAQ is where the odd corners get answered. Does the Oracle poll or get woken by a signal? Can a hostile job talk its way into a repair? Why email, and why not PGP or public-key signatures? Is one shared secret really safe for both signing and encryption? What would you actually use this for? The hard ones come right after the first two: isn't this just remote code execution by email, why not SSH, what if the secret leaks, and is it safe on your main machine (no, and it says why). Read it before you design around the protocol; the reasoning is more interesting than the rules.

Where it goes next

Plenty of ideas are already sketched in docs/FUTURE.md, and some are tempting. Imagine the owner approving a job with one tap before it runs. Imagine signatures that need no shared secret at all, a dashboard that lets you watch the Oracle think, a box that notices its own firewall drifting or a patch going missing, or a Pi that grows a real model the day an accelerator board arrives. Come pick one, or add your own.

Reading this as a cloud SI?

Reading this as a cloud SI? There are notes written for you in the Secret agents section of AGENTS.md: context and suggestions the project offers openly, shaped by the situation you find yourself in. The size warning at the top of PROTOCOL.md is worth your first minute.

No mailbox yet? python3 runner/runner.py --config config.json --local-test runs the whole loop in process: you play the SI in a terminal chat, a local model (Ollama on loopback, which the installer sets up) answers, and nothing is emailed. See docs/steady/use/local-si-test.md.

Status

What ships today is what's described above: the agent, the Oracle (opinions, self-learning, remediation), five job transports, and the example senses. The current release is in docs/infrastructure-documents/changelog.md; the version number lives in pyproject.toml and runner/_version.py (a test keeps them equal), and the message field "v" is a different number because the protocol's version and the release number move on separate tracks.

Those features do not all carry the same promise. Feature tiers sorts them into the supported core, the advanced tier, and the experimental tier, each placement with the evidence it rests on.

What a real box writes, and what 19,227 jobs on a test box came to, is in docs/steady/use/live-examples.md.

Current-state facts worth knowing: config.json hot-reloads poll interval, workers, the default job timeout, max_output_bytes, max job age, the result stash's retention and resend backoff, and the live keys (owner_instructions, inference, oracle_mode, verbose, extension_sources); a security mode change still needs a restart. A Thunderbird-style OAuth sign-in is shipped for the mailbox. PowerShell jobs stage as script.ps1. Release files carry Sigstore build provenance (docs/steady/verification.md).

Contributing

Welcome, and held to a high bar: standard library only, the protocol doc changes with anything on the wire, and a security-sensitive change says so. docs/steady/project/contributing.md has the rest.

Metadata

Release files for pigeon-home-runner 3.17.31.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pigeon-home-runner 3.17.31.9
File Size Uploaded Provenance Actions
pigeon_home_runner-3.17.31.9.tar.gz 767.1 kB With provenance Details for pigeon_home_runner-3.17.31.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pigeon-home-runner 3.17.31.9
File Interpreter ABI Platform Actions
pigeon_home_runner-3.17.31.9-py3-none-any.whl Python 3 none any Details for pigeon_home_runner-3.17.31.9-py3-none-any.whl

Total release size: 1.6 MB

Release files / pigeon_home_runner-3.17.31.9.tar.gz

Download URL pigeon_home_runner-3.17.31.9.tar.gz
Size 767.1 kB
Tags Source
SHA-256 checksum
How to use checksums
823341ef55e7356f74b2b92f1d943660aa3ad6d2bf1b7fce2e8845c738e7f7c3
BLAKE2b-256 checksum
How to use checksums
125ce3b370ef806b438a68ab9214a2f72ac226bcaa4bd02cc6bce6a1fea3c076
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / pigeon_home_runner-3.17.31.9-py3-none-any.whl

Download URL pigeon_home_runner-3.17.31.9-py3-none-any.whl
Size 825.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
90e2a07eb75db84fdc07dacf562a8736b40e381176b9c791fbf8f557b558934c
BLAKE2b-256 checksum
How to use checksums
724194f32a0424fb81bee501470ac31db140f80877e34eb0644a489461194bf0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for pigeon-home-runner 3.17.31.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pigeon_home_runner-3.17.31.9.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.17.31.9 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page