Python Runtime Enforcement Guide

This page is a complete Python-first manual for implementing MachineID runtime enforcement without relying on any specific agent framework.

Everything reduces to a single invariant:

Register. Validate. Work.

If validation fails, work does not begin.

This invariant is intentionally simple. Its strength comes from being external, enforceable, and non-negotiable.

MachineID enforces permission on an identity (a “device”) that represents an execution surface. In Python, an execution surface is usually one of:

• One worker process
• One queue consumer replica
• One scheduled job identity
• One tool runner / side-effect executor

Device IDs should be stable enough to audit, but specific enough to revoke. A practical format:

{service}:{env}:{role}:{instance}

Examples:

• worker:prod:queue-consumer:07
• job:prod:nightly-reindex:01
• agent:dev:planner:01
• tool:prod:payment-runner:02

MachineID uses canonical POST endpoints. Send your org key via x-org-key.

POST https://machineid.io/api/v1/devices/register
Headers:
  x-org-key: org_...
Body:
  {"deviceId":"worker:prod:queue-consumer:07"}

POST https://machineid.io/api/v1/devices/validate
Headers:
  x-org-key: org_...
Body:
  {"deviceId":"worker:prod:queue-consumer:07"}

Validation returns a decision including allowed, a stable code, and a request_id. Your runtime must treat allowed:false as an immediate stop condition.

Validation belongs at execution boundaries: points where work begins or commits side effects. Most production Python systems already have these boundaries; they are simply not treated as enforcement points.

• Startup boundary: before an instance begins processing work
• Task boundary: before each unit of work (job/message/task)
• Side-effect boundary: before irreversible actions (writes, payments, emails)

Pattern A: Startup gate (required)

Register once, validate once, then start the work loop. If validation fails, exit immediately.

register(device_id)
val = validate(device_id)
if not val.allowed:
    exit(1)

start_work_loop()

Pattern B: Per-unit-of-work gate (recommended)

Validate before each job/message/task. This makes revocation effective at predictable points.

while True:
    job = dequeue()

    val = validate(device_id)
    if not val.allowed:
        exit(1)

    process(job)

Pattern C: Side-effect gate (high leverage)

Validate immediately before irreversible actions: writes, transfers, external API calls, outbound messages.

val = validate(device_id)
if not val.allowed:
    exit(1)

commit_side_effect()

MachineID does not introspect internal loops. If a process runs for hours, you must define enforcement boundaries inside the loop.

Side effects are where runtime mistakes become expensive or irreversible: payments, emails, writes, deletes, credential rotations, outbound API calls, queue publishes, deployments.

Treat validation like a safety-critical call: it must be fast, and it must fail safely.

Decide your failure policy up front. Do not allow “it depends” behavior per team, per service, or per environment. Enforcement must be consistent.

The guarantee is binary. Avoid patterns like:

• Proceed anyway but log a warning
• Continue for 10 minutes until checks recover
• Fallback to internal flags when validation is down

Those patterns create a second authority path inside the runtime. That is precisely what an external control plane avoids.

The free tier is enough to implement a complete control loop and prove stop behavior end-to-end. A practical three-device model:

This tier supports multiple concurrent workers and multiple execution surfaces for tool calls and side effects.

At this scale, execution surfaces multiply under load: autoscaling, retries, event storms, and distributed consumers. The dominant requirement is consistent enforcement across replicas and across time.

Near the upper end of standard caps, the dominant failure mode is execution multiplication: autoscale, fan-out, retries, recursion, and delayed resumes.

If you need device limits beyond standard tiers, MachineID supports custom device limits. This does not require changes to runtime code — the identity model and enforcement boundaries remain the same.

The console lives outside your runtime so control does not depend on the process cooperating: machineid.io/dashboard

In addition to revoking individual devices, MachineID supports an org-wide disable control. This is a deliberate stop mechanism that affects validate outcomes across the org.

Revoke/restore and org disable are effective at the next validate. Stop latency is determined by boundary placement.

The prompts below are designed to produce practical integration plans with minimal guesswork. Replace bracketed placeholders and paste into your LLM of choice.

I have a Python worker/service runtime and I want hard enforcement using MachineID.io.

Context:
- Org key: [PASTE ORG KEY]
- Device ID scheme: {service}:{env}:{role}:{instance}
- Fail-closed policy, short timeout (1–3s)
- Validation boundaries required:
  1) Startup (register + validate)
  2) Before each unit of work (job/message/task)
  3) Before any external tool call that can incur cost
  4) Before any irreversible side effect (writes, payments, emails)
  5) Before entering high-cost loops or fan-out cycles

Please provide:
1) Exact files/functions where validation should be added
2) Copy/paste code blocks (SDK and direct-HTTP variants)
3) A recommended boundary map for my runtime
4) A test plan using the MachineID.io dashboard:
   - revoke a device
   - restore it
   - use org-wide disable
   - verify work stops at the next validate boundary

Help me model MachineID devices for my Python system.

Inputs:
- Execution surfaces: [describe workers/queues/cron/tools/side-effects]
- Expected scale: [3 / 25 / 250 / 1000]
- I need readable device IDs and surgical revoke control.

Output:
- Device ID naming scheme
- A concrete list of device IDs for the target tier
- Where to validate (startup / per-work / tool / side-effect / loops)
- A minimal runbook for revoke + org-wide disable

I have a Python process that can run for hours and includes tool calls and side effects.

Goal:
- Add MachineID.io validate boundaries inside the loop so I can stop it remotely.
- Fail closed on validation timeout or error.

Please provide:
- Exactly where to place validation calls
- A wrapper pattern that is hard to forget
- A test plan using dashboard revoke and org-wide disable

• Python SDK: github.com/machineid-io/python-sdk
• MachineID GitHub org: github.com/machineid-io
• Dashboard: machineid.io/dashboard
• Core guidance: External Control Plane, Implementation Guide, Operational Guarantees
• Architectural overview: Why Autonomous Systems Need an External Control Plane
• Proof of enforcement: What Happens When a Running Agent Is Revoked

← Back to Docs