microvm-ctl 0.1.0__tar.gz → 0.2.0__tar.gz

{microvm_ctl-0.1.0 → microvm_ctl-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microvm-ctl
-Version: 0.1.0
+Version: 0.2.0
 Summary: Control and execution plane for AWS Lambda MicroVMs: build images, launch Firecracker microVMs, scale fleets inside your quotas, call into them securely, and watch it all live.
 Author: Vivek Raja P S
 License: Apache-2.0
@@ -9,6 +9,7 @@ Project-URL: Repository, https://github.com/Vivek0712/microvm-ctl
 Project-URL: Documentation, https://github.com/Vivek0712/microvm-ctl/tree/main/docs
 Project-URL: Changelog, https://github.com/Vivek0712/microvm-ctl/blob/main/CHANGELOG.md
 Project-URL: Examples, https://github.com/Vivek0712/awesome-microvm
+Project-URL: Articles, https://builder.aws.com/content/3JIDTpz0ZgatSBv24drra3gEod9/control-and-scale-aws-lambda-microvms-with-microvm-ctl
 Keywords: aws,lambda,microvm,firecracker,sandbox,serverless,fleet,orchestrator
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
@@ -17,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: System :: Distributed Computing
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.9
@@ -28,19 +30,21 @@ Requires-Dist: rich>=13.7
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"
+Provides-Extra: durable
+Requires-Dist: aws-durable-execution-sdk-python>=2.0.0; extra == "durable"
 Dynamic: license-file
 
 # microvm-ctl
 
-**The control and execution plane for [AWS Lambda MicroVMs](https://docs.aws.amazon.com/lambda/latest/dg/lambda-microvms-guide.html).** Build a snapshot image from a Dockerfile, launch Firecracker microVMs in seconds, scale a fleet inside the quotas your account actually has, call into every VM over its authenticated endpoint, and watch the whole thing live. One Python SDK, one `mvm` command.
+**The control and execution plane for [AWS Lambda MicroVMs](https://docs.aws.amazon.com/lambda/latest/dg/lambda-microvms-guide.html).** Build a snapshot image from a Dockerfile, launch Firecracker microVMs in seconds, scale a fleet inside the quotas your account actually has, call into every VM over its authenticated endpoint, watch the whole thing live, and hand a VM a task from Step Functions, Lambda durable functions, or any orchestrator through a lease the VM completes itself. One Python SDK, one `mvm` command.
 
 [![ci](https://github.com/Vivek0712/microvm-ctl/actions/workflows/ci.yml/badge.svg)](https://github.com/Vivek0712/microvm-ctl/actions/workflows/ci.yml)
 [![pypi](https://img.shields.io/pypi/v/microvm-ctl)](https://pypi.org/project/microvm-ctl/)
-![python](https://img.shields.io/badge/python-3.9%20to%203.12-blue)
+![python](https://img.shields.io/badge/python-3.9%20to%203.13-blue)
 ![license](https://img.shields.io/badge/license-Apache--2.0-green)
 
 ```console
-pip install microvm-ctl
+pip install microvm-ctl          # https://pypi.org/project/microvm-ctl/
 
 mvm bootstrap                              # one time: S3 artifact bucket + build/execution IAM roles
 mvm image build my-sandbox ./my-app        # Dockerfile at ./my-app root -> runnable snapshot
@@ -50,6 +54,8 @@ mvm scale my-sandbox 10                    # converge the fleet, throttled to yo
 mvm top --watch                            # live state table
 ```
 
+To see it used for real first, jump to [the eight examples](#see-it-working-eight-examples-and-the-article-series).
+
 ## Why this exists
 
 Lambda MicroVMs exposes the primitive under Lambda itself: a Firecracker VM with a full AL2023 userland, a dedicated HTTPS endpoint, and a lifecycle you control (run, suspend, resume, terminate). The service deliberately stops there. There is no load balancer (one endpoint per VM), no fleet abstraction, no token management, no dashboard, and a fresh account runs quotas far below the published defaults. microvm-ctl fills that gap.
@@ -63,6 +69,8 @@ Lambda MicroVMs exposes the primitive under Lambda itself: a Firecracker VM with
 | In-VM hook runtime | zero-dependency server for `/ready`, `/validate`, `/run`, `/resume`, `/suspend`, `/terminate` plus your own routes | `microvm/hooks/server.py` |
 | Observability and cost | live fleet table, CloudWatch tail, a cost model that prices a session shape before you commit to it | `microvm/monitor.py` |
 | Account bootstrap | artifact bucket plus separate build and execution roles | `microvm/bootstrap.py` |
+| Leases | `Lease`, `LeasePolicy`, `FleetManager.lease`: one task per VM, completed by the VM through a task token, callback id, HTTP, SQS, or EventBridge | `microvm/lease.py` |
+| Orchestrator integrations | generated Step Functions state machine and IAM (`mvm lease asl`, `mvm lease policy`), `lease_microvm` for Lambda durable functions | `microvm/integrations/` |
 
 The `lambda-microvms` botocore service model ships inside the package, so the plane works on whatever boto3 you already have.
 
@@ -142,6 +150,14 @@ app.serve(port=8080)
 
 ![mvm cost](docs/img/mvm-cost.png)
 
+## The playground
+
+`mvm playground` opens a local web app that drives everything above against the live service: build images, run and scale fleets, call VMs, tail logs, price sessions, run a parameterised benchmark, and watch every AWS API call the process makes in a trace. A dry-run switch turns each mutating action into a printout of the exact request it would send. See [docs/playground.md](docs/playground.md).
+
+```console
+mvm playground            # http://127.0.0.1:8765
+```
+
 ## Documentation
 
 - [Quickstart](docs/quickstart.md): from an empty account to a serving VM, with the environment variables explained.
@@ -150,11 +166,32 @@ app.serve(port=8080)
 - [Architecture](docs/architecture.md): the two planes, the lifecycle state machine, the fleet design decisions, and the security model.
 - [The hook contract](docs/hooks.md): what each hook is for and what breaks when you ignore it.
 - [Quotas and cost](docs/quotas-and-cost.md): the quota walls, what counts against them, and the cost model with worked examples.
-- [Troubleshooting](docs/troubleshooting.md): the errors we hit on the live service and what each one meant.
+- [Troubleshooting](docs/troubleshooting.md): the errors I hit on the live service and what each one meant.
+- [The playground](docs/playground.md): the local web app over the whole SDK, and how to host it.
+- [Integrations](docs/integrations.md): the lease contract for handing a VM to Step Functions, Lambda durable functions, or your own orchestrator, and what the plane should own.
+
+## See it working: eight examples and the article series
+
+The fastest way to understand the plane is to read the apps built on it. The companion repo [awesome-microvm](https://github.com/Vivek0712/awesome-microvm) holds eight production-shaped examples, each a Dockerfile plus a single-file app, deployed and recorded on the live service:
+
+| Example | What it shows |
+|---|---|
+| [code-sandbox](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/code-sandbox) | untrusted or AI-written Python per session; state persists across calls and suspend |
+| [ai-code-runner](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/ai-code-runner) | Bedrock writes code, the VM runs it, tracebacks drive a self-repair loop |
+| [agent-eval](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/agent-eval) | `Fleet.scale_to` fan-out over byte-identical clones, scoreboard, drain |
+| [notebook](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/notebook) | a kernel whose namespace survives suspend and resume with the same PID |
+| [data-analytics](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/data-analytics) | DuckDB over S3 through the execution role; bulk data off the endpoint |
+| [ci-runner](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/ci-runner) | clone, test, report, terminate; `--max-duration` as the runaway cap |
+| [pdf-service](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/pdf-service) | untrusted HTML rendered in the VM; idle policy sleeps it between bursts |
+| [multi-tenant-agents](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/multi-tenant-agents) | one VM per tenant, identity via `runHookPayload`, `run_payload_factory` on a `Fleet` |
+
+The three-part article series **Building on AWS Lambda MicroVMs** on the AWS Builder Center walks through them:
 
-## Examples and the article series
+1. [Control and scale AWS Lambda MicroVMs with microvm-ctl](https://builder.aws.com/content/3JIDTpz0ZgatSBv24drra3gEod9/control-and-scale-aws-lambda-microvms-with-microvm-ctl): this plane and its measurements.
+2. [Seven workloads Lambda could never run, until MicroVMs](https://builder.aws.com/content/3JJ2oNWY9EsZzivMMx044cSlrFQ/seven-workloads-lambda-could-never-run-until-microvms): the first seven examples through build, run, cost, and gotchas.
+3. [A kernel for every customer: scaling AI agents to 1,000 tenants on AWS Lambda MicroVMs with microvm-ctl](https://builder.aws.com/content/3JJ7tASPSSUUTrcpWnWtxOuu8g3/a-kernel-for-every-customer-scaling-ai-agents-to-1000-tenants-on-aws-lambda-microvms-with-microvm-ctl): the multi-tenant finale with the decision guide.
 
-Eight production-shaped apps run on this plane: a code execution sandbox, an AI code runner with a self-repair loop, an agent evaluation fleet, a stateful notebook kernel, sandboxed DuckDB analytics, an ephemeral CI runner, an HTML to PDF service, and multi-tenant AI agents. Each has a Dockerfile, a single-file app, a recorded live transcript, and an article in the series **Building on AWS Lambda MicroVMs**. They live in the companion repo [awesome-microvm](https://github.com/Vivek0712/awesome-microvm).
+The article sources and a long-form deep dive per example live under [awesome-microvm/blog](https://github.com/Vivek0712/awesome-microvm/tree/main/blog).
 
 ## Requirements and regions
 
@@ -162,7 +199,7 @@ Python 3.9 or newer on the machine running the plane. The VMs themselves are ARM
 
 ## Credits and inspiration
 
-This project grew out of [lambda-microvm-starter](https://github.com/vidanov/lambda-microvm-starter) by [Alexey Vidanov](https://github.com/vidanov), the one-command on-ramp that deploys any Dockerfile to a Lambda MicroVM behind a public CloudFront URL. His starter kit and its troubleshooting notes were the first working map of the service we had, and several of the gotchas documented here were first written down there. microvm-ctl takes the next step from one deployed app to fleets, tokens, quotas, and cost, and we are grateful for the ground he covered first.
+This project grew out of [lambda-microvm-starter](https://github.com/vidanov/lambda-microvm-starter) by [Alexey Vidanov](https://github.com/vidanov), the one-command on-ramp that deploys any Dockerfile to a Lambda MicroVM behind a public CloudFront URL. His starter kit and its troubleshooting notes were the first working map of the service I had, and several of the gotchas documented here were first written down there. microvm-ctl takes the next step from one deployed app to fleets, tokens, quotas, and cost, and I am grateful for the ground he covered first.
 
 ## Contributing
 

{microvm_ctl-0.1.0 → microvm_ctl-0.2.0}/README.md

@@ -1,14 +1,14 @@
 # microvm-ctl
 
-**The control and execution plane for [AWS Lambda MicroVMs](https://docs.aws.amazon.com/lambda/latest/dg/lambda-microvms-guide.html).** Build a snapshot image from a Dockerfile, launch Firecracker microVMs in seconds, scale a fleet inside the quotas your account actually has, call into every VM over its authenticated endpoint, and watch the whole thing live. One Python SDK, one `mvm` command.
+**The control and execution plane for [AWS Lambda MicroVMs](https://docs.aws.amazon.com/lambda/latest/dg/lambda-microvms-guide.html).** Build a snapshot image from a Dockerfile, launch Firecracker microVMs in seconds, scale a fleet inside the quotas your account actually has, call into every VM over its authenticated endpoint, watch the whole thing live, and hand a VM a task from Step Functions, Lambda durable functions, or any orchestrator through a lease the VM completes itself. One Python SDK, one `mvm` command.
 
 [![ci](https://github.com/Vivek0712/microvm-ctl/actions/workflows/ci.yml/badge.svg)](https://github.com/Vivek0712/microvm-ctl/actions/workflows/ci.yml)
 [![pypi](https://img.shields.io/pypi/v/microvm-ctl)](https://pypi.org/project/microvm-ctl/)
-![python](https://img.shields.io/badge/python-3.9%20to%203.12-blue)
+![python](https://img.shields.io/badge/python-3.9%20to%203.13-blue)
 ![license](https://img.shields.io/badge/license-Apache--2.0-green)
 
 ```console
-pip install microvm-ctl
+pip install microvm-ctl          # https://pypi.org/project/microvm-ctl/
 
 mvm bootstrap                              # one time: S3 artifact bucket + build/execution IAM roles
 mvm image build my-sandbox ./my-app        # Dockerfile at ./my-app root -> runnable snapshot
@@ -18,6 +18,8 @@ mvm scale my-sandbox 10                    # converge the fleet, throttled to yo
 mvm top --watch                            # live state table
 ```
 
+To see it used for real first, jump to [the eight examples](#see-it-working-eight-examples-and-the-article-series).
+
 ## Why this exists
 
 Lambda MicroVMs exposes the primitive under Lambda itself: a Firecracker VM with a full AL2023 userland, a dedicated HTTPS endpoint, and a lifecycle you control (run, suspend, resume, terminate). The service deliberately stops there. There is no load balancer (one endpoint per VM), no fleet abstraction, no token management, no dashboard, and a fresh account runs quotas far below the published defaults. microvm-ctl fills that gap.
@@ -31,6 +33,8 @@ Lambda MicroVMs exposes the primitive under Lambda itself: a Firecracker VM with
 | In-VM hook runtime | zero-dependency server for `/ready`, `/validate`, `/run`, `/resume`, `/suspend`, `/terminate` plus your own routes | `microvm/hooks/server.py` |
 | Observability and cost | live fleet table, CloudWatch tail, a cost model that prices a session shape before you commit to it | `microvm/monitor.py` |
 | Account bootstrap | artifact bucket plus separate build and execution roles | `microvm/bootstrap.py` |
+| Leases | `Lease`, `LeasePolicy`, `FleetManager.lease`: one task per VM, completed by the VM through a task token, callback id, HTTP, SQS, or EventBridge | `microvm/lease.py` |
+| Orchestrator integrations | generated Step Functions state machine and IAM (`mvm lease asl`, `mvm lease policy`), `lease_microvm` for Lambda durable functions | `microvm/integrations/` |
 
 The `lambda-microvms` botocore service model ships inside the package, so the plane works on whatever boto3 you already have.
 
@@ -110,6 +114,14 @@ app.serve(port=8080)
 
 ![mvm cost](docs/img/mvm-cost.png)
 
+## The playground
+
+`mvm playground` opens a local web app that drives everything above against the live service: build images, run and scale fleets, call VMs, tail logs, price sessions, run a parameterised benchmark, and watch every AWS API call the process makes in a trace. A dry-run switch turns each mutating action into a printout of the exact request it would send. See [docs/playground.md](docs/playground.md).
+
+```console
+mvm playground            # http://127.0.0.1:8765
+```
+
 ## Documentation
 
 - [Quickstart](docs/quickstart.md): from an empty account to a serving VM, with the environment variables explained.
@@ -118,11 +130,32 @@ app.serve(port=8080)
 - [Architecture](docs/architecture.md): the two planes, the lifecycle state machine, the fleet design decisions, and the security model.
 - [The hook contract](docs/hooks.md): what each hook is for and what breaks when you ignore it.
 - [Quotas and cost](docs/quotas-and-cost.md): the quota walls, what counts against them, and the cost model with worked examples.
-- [Troubleshooting](docs/troubleshooting.md): the errors we hit on the live service and what each one meant.
+- [Troubleshooting](docs/troubleshooting.md): the errors I hit on the live service and what each one meant.
+- [The playground](docs/playground.md): the local web app over the whole SDK, and how to host it.
+- [Integrations](docs/integrations.md): the lease contract for handing a VM to Step Functions, Lambda durable functions, or your own orchestrator, and what the plane should own.
+
+## See it working: eight examples and the article series
+
+The fastest way to understand the plane is to read the apps built on it. The companion repo [awesome-microvm](https://github.com/Vivek0712/awesome-microvm) holds eight production-shaped examples, each a Dockerfile plus a single-file app, deployed and recorded on the live service:
+
+| Example | What it shows |
+|---|---|
+| [code-sandbox](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/code-sandbox) | untrusted or AI-written Python per session; state persists across calls and suspend |
+| [ai-code-runner](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/ai-code-runner) | Bedrock writes code, the VM runs it, tracebacks drive a self-repair loop |
+| [agent-eval](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/agent-eval) | `Fleet.scale_to` fan-out over byte-identical clones, scoreboard, drain |
+| [notebook](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/notebook) | a kernel whose namespace survives suspend and resume with the same PID |
+| [data-analytics](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/data-analytics) | DuckDB over S3 through the execution role; bulk data off the endpoint |
+| [ci-runner](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/ci-runner) | clone, test, report, terminate; `--max-duration` as the runaway cap |
+| [pdf-service](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/pdf-service) | untrusted HTML rendered in the VM; idle policy sleeps it between bursts |
+| [multi-tenant-agents](https://github.com/Vivek0712/awesome-microvm/tree/main/examples/multi-tenant-agents) | one VM per tenant, identity via `runHookPayload`, `run_payload_factory` on a `Fleet` |
+
+The three-part article series **Building on AWS Lambda MicroVMs** on the AWS Builder Center walks through them:
 
-## Examples and the article series
+1. [Control and scale AWS Lambda MicroVMs with microvm-ctl](https://builder.aws.com/content/3JIDTpz0ZgatSBv24drra3gEod9/control-and-scale-aws-lambda-microvms-with-microvm-ctl): this plane and its measurements.
+2. [Seven workloads Lambda could never run, until MicroVMs](https://builder.aws.com/content/3JJ2oNWY9EsZzivMMx044cSlrFQ/seven-workloads-lambda-could-never-run-until-microvms): the first seven examples through build, run, cost, and gotchas.
+3. [A kernel for every customer: scaling AI agents to 1,000 tenants on AWS Lambda MicroVMs with microvm-ctl](https://builder.aws.com/content/3JJ7tASPSSUUTrcpWnWtxOuu8g3/a-kernel-for-every-customer-scaling-ai-agents-to-1000-tenants-on-aws-lambda-microvms-with-microvm-ctl): the multi-tenant finale with the decision guide.
 
-Eight production-shaped apps run on this plane: a code execution sandbox, an AI code runner with a self-repair loop, an agent evaluation fleet, a stateful notebook kernel, sandboxed DuckDB analytics, an ephemeral CI runner, an HTML to PDF service, and multi-tenant AI agents. Each has a Dockerfile, a single-file app, a recorded live transcript, and an article in the series **Building on AWS Lambda MicroVMs**. They live in the companion repo [awesome-microvm](https://github.com/Vivek0712/awesome-microvm).
+The article sources and a long-form deep dive per example live under [awesome-microvm/blog](https://github.com/Vivek0712/awesome-microvm/tree/main/blog).
 
 ## Requirements and regions
 
@@ -130,7 +163,7 @@ Python 3.9 or newer on the machine running the plane. The VMs themselves are ARM
 
 ## Credits and inspiration
 
-This project grew out of [lambda-microvm-starter](https://github.com/vidanov/lambda-microvm-starter) by [Alexey Vidanov](https://github.com/vidanov), the one-command on-ramp that deploys any Dockerfile to a Lambda MicroVM behind a public CloudFront URL. His starter kit and its troubleshooting notes were the first working map of the service we had, and several of the gotchas documented here were first written down there. microvm-ctl takes the next step from one deployed app to fleets, tokens, quotas, and cost, and we are grateful for the ground he covered first.
+This project grew out of [lambda-microvm-starter](https://github.com/vidanov/lambda-microvm-starter) by [Alexey Vidanov](https://github.com/vidanov), the one-command on-ramp that deploys any Dockerfile to a Lambda MicroVM behind a public CloudFront URL. His starter kit and its troubleshooting notes were the first working map of the service I had, and several of the gotchas documented here were first written down there. microvm-ctl takes the next step from one deployed app to fleets, tokens, quotas, and cost, and I am grateful for the ground he covered first.
 
 ## Contributing
 

{microvm_ctl-0.1.0 → microvm_ctl-0.2.0}/microvm/__init__.py

@@ -9,9 +9,10 @@ from microvm.config import PlaneConfig
 from microvm.endpoint import EndpointClient, EndpointError
 from microvm.fleet import Fleet, FleetManager
 from microvm.images import ImageBuilder, ImageBuildError
+from microvm.lease import Lease, LeasePolicy
 from microvm.monitor import CostModel, FleetMonitor
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = [
     "microvm_client",
@@ -21,6 +22,8 @@ __all__ = [
     "ImageBuildError",
     "Fleet",
     "FleetManager",
+    "Lease",
+    "LeasePolicy",
     "EndpointClient",
     "EndpointError",
     "FleetMonitor",

{microvm_ctl-0.1.0 → microvm_ctl-0.2.0}/microvm/bootstrap.py

@@ -74,7 +74,12 @@ def bootstrap(cfg: PlaneConfig, prefix: str = "microvm-ctl") -> dict:
     logs_stmt = {
         "Effect": "Allow",
         "Action": ["logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents"],
-        "Resource": f"arn:aws:logs:{cfg.region}:{account}:log-group:/aws/lambda/microvms/*",
+        # the service writes to /aws/lambda-microvms/<image>; the old prefix is kept
+        # so roles bootstrapped by earlier releases keep working
+        "Resource": [
+            f"arn:aws:logs:{cfg.region}:{account}:log-group:/aws/lambda-microvms/*",
+            f"arn:aws:logs:{cfg.region}:{account}:log-group:/aws/lambda/microvms/*",
+        ],
     }
     build_role = _ensure_role(
         iam,

{microvm_ctl-0.1.0 → microvm_ctl-0.2.0}/microvm/cli.py

@@ -10,9 +10,12 @@
     mvm suspend|resume|terminate ID...     lifecycle control
     mvm drain IMAGE                        terminate the whole fleet
     mvm call ID /path [-X POST -d '{}']    authenticated request into the VM
+    mvm status ID | watch ID               job telemetry from the hook runtime (/status, /events)
+    mvm lease asl|policy|run               Step Functions ASL, IAM statements, one manual lease
     mvm top [--image NAME] [--watch]       live fleet dashboard
     mvm logs IMAGE                         CloudWatch tail
     mvm cost [--memory-gb 2 ...]           session economics
+    mvm playground [--port 8765]           browser UI over everything above, live against AWS
 """
 
 from __future__ import annotations
@@ -253,11 +256,138 @@ def cmd_logs(args):
     mon = FleetMonitor(_cfg(args))
     events = mon.tail_logs(args.image, minutes=args.minutes)
     if not events:
-        console.print(f"[dim]no events in /aws/lambda/microvms/{args.image}[/]")
+        console.print(f"[dim]no events in {' or '.join(mon.log_groups(args.image))}[/]")
     for e in events:
         console.print(f"[dim]{e['stream'][:20]}[/] {e['message']}")
 
 
+# ---------------------------------------------------------------- job telemetry
+def _snapshot_table(snap: dict, title: str) -> Table:
+    t = Table(title=title, header_style="bold magenta", show_header=False)
+    t.add_column("field", style="cyan")
+    t.add_column("value")
+    prog = snap.get("progress") or {}
+    done, total = prog.get("done"), prog.get("total")
+    t.add_row("phase", str(snap.get("phase") or "-"))
+    t.add_row("elapsed", f"{snap.get('elapsed_s', 0):.0f} s")
+    t.add_row("progress", f"{done}/{total}" if total else str(done if done is not None else "-"))
+    for k, v in sorted((snap.get("counters") or {}).items()):
+        t.add_row(f"counter {k}", str(v))
+    lease = snap.get("lease")
+    if lease:
+        state = "done" if lease.get("done") else ("lost" if lease.get("lost") else "active")
+        err = lease.get("error")
+        colour = "red" if err else "green"
+        t.add_row("lease", f"{lease.get('kind')}  {lease.get('id') or ''}  "
+                           f"heartbeats={lease.get('heartbeats', 0)}  [{colour}]{state}[/]")
+        if err:
+            t.add_row("error", f"[red]{err.get('error_type')}[/] {err.get('message')}")
+    else:
+        t.add_row("lease", "[dim]none[/]")
+    return t
+
+
+def _log_line(entry: dict) -> str:
+    level = entry.get("level", "info")
+    style = {"error": "red", "warning": "yellow", "warn": "yellow"}.get(level, "dim")
+    extra = {k: v for k, v in entry.items() if k not in ("t", "level", "msg", "phase", "microvm_id", "seq")}
+    tail = f"  [dim]{json.dumps(extra, default=str)}[/]" if extra else ""
+    return f"[{style}]{level:<7}[/] [cyan]{entry.get('phase') or ''}[/] {entry.get('msg', '')}{tail}"
+
+
+def cmd_status(args):
+    client = EndpointClient(_cfg(args), args.id, ports=[args.port] if args.port else None)
+    snap = client.status()
+    console.print(_snapshot_table(snap, f"job on {args.id}"))
+    for entry in snap.get("log_tail") or []:
+        console.print(_log_line(entry) if isinstance(entry, dict) else str(entry))
+
+
+def cmd_watch(args):
+    from rich.live import Live
+    client = EndpointClient(_cfg(args), args.id, ports=[args.port] if args.port else None)
+    snap = client.status()
+    with Live(_snapshot_table(snap, f"job on {args.id}"), refresh_per_second=2, console=console) as live:
+        for obj in client.watch(timeout=args.timeout):
+            if not isinstance(obj, dict):
+                continue
+            if "msg" in obj:
+                live.console.print(_log_line(obj))
+            else:
+                live.update(_snapshot_table(obj, f"job on {args.id}"))
+
+
+# ---------------------------------------------------------------- leases
+def _lease_policy(args):
+    from microvm.lease import LeasePolicy
+    return LeasePolicy(budget_s=args.budget, heartbeat_timeout_s=args.heartbeat, slack_s=args.slack)
+
+
+def _image_arn_offline(image: str, region: str, role_arn: str | None, profile) -> str:
+    """Resolve a bare image name without calling STS when the account is readable
+    from the execution role ARN, so `mvm lease asl` works without credentials."""
+    from microvm.client import image_arn
+    if image.startswith("arn:"):
+        return image
+    parts = (role_arn or "").split(":")
+    if role_arn and role_arn.startswith("arn:") and len(parts) > 4 and parts[4]:
+        return f"arn:aws:lambda:{region}:{parts[4]}:microvm-image:{image}"
+    return image_arn(image, region, profile)
+
+
+def cmd_lease_asl(args):
+    from microvm.integrations.stepfunctions import lease_state_machine
+    cfg = _cfg(args)
+    role = args.execution_role or cfg.execution_role_arn
+    if not role:
+        sys.exit("mvm lease asl: --execution-role ARN (or MVM_EXECUTION_ROLE_ARN) is required")
+    asl = lease_state_machine(
+        image_arn=_image_arn_offline(args.image, cfg.region, role, cfg.profile),
+        execution_role_arn=role, policy=_lease_policy(args), region=cfg.region,
+        name=args.name, task_expr=args.task_expr, heartbeat_s=args.heartbeat_every,
+    )
+    print(json.dumps(asl, indent=2))
+
+
+def cmd_lease_policy(args):
+    from microvm.integrations.stepfunctions import iam_statements, orchestrator_statements, policy_document
+    cfg = _cfg(args)
+    out = {
+        "execution_role": policy_document(iam_statements(args.kind, orchestrator_arn=args.orchestrator)),
+        "orchestrator_role": policy_document(
+            orchestrator_statements(args.execution_role or cfg.execution_role_arn)),
+    }
+    print(json.dumps(out, indent=2))
+
+
+def cmd_lease_run(args):
+    from microvm.lease import Lease
+    cfg = _cfg(args)
+    if args.kind != "none" and not args.token:
+        sys.exit(f"mvm lease run: --token is required for kind {args.kind}")
+    try:
+        task = json.loads(args.task) if args.task else {}
+    except ValueError as e:
+        sys.exit(f"mvm lease run: --task is not valid JSON: {e}")
+    lease = Lease(kind=args.kind, token=args.token or "", region=cfg.region, target=args.target,
+                  heartbeat_s=args.heartbeat_every, id=args.id)
+    fm = FleetManager(cfg)
+    vm = fm.lease(args.image, lease, task, _lease_policy(args), version=args.version,
+                  execution_role=args.execution_role)
+    console.print(
+        f"[bold green]✓[/] {vm.microvm_id}  {_state(vm.state)}  "
+        f"[link=https://{vm.endpoint}]{vm.endpoint}[/link]  lease {lease.kind}"
+    )
+    if args.wait:
+        vm = fm.wait_until(vm.microvm_id, "RUNNING")
+        console.print(f"  now {_state(vm.state)}; follow it with: mvm watch {vm.microvm_id}")
+
+
+def cmd_playground(args):
+    from microvm.playground import serve
+    serve(host=args.host, port=args.port, dry_run=args.dry_run, open_browser=not args.no_open, cfg=_cfg(args))
+
+
 def cmd_cost(args):
     model = CostModel(memory_gb=args.memory_gb, snapshot_gb=args.snapshot_gb)
     s = model.session(args.active * 60, args.suspended * 60, args.cycles)
@@ -351,13 +481,63 @@ def main(argv: list[str] | None = None):
     c.add_argument("--port", type=int, default=None, help="non-default app port")
     c.set_defaults(fn=cmd_call)
 
+    st = sub.add_parser("status", help="job snapshot from the hook runtime (GET /status)")
+    st.add_argument("id")
+    st.add_argument("--port", type=int, default=None, help="non-default app port")
+    st.set_defaults(fn=cmd_status)
+
+    w = sub.add_parser("watch", help="live job table plus streamed log lines (GET /events)")
+    w.add_argument("id")
+    w.add_argument("--port", type=int, default=None, help="non-default app port")
+    w.add_argument("--timeout", type=float, default=600, help="stop after N seconds")
+    w.set_defaults(fn=cmd_watch)
+
+    le = sub.add_parser("lease", help="hand a VM a task through a lease").add_subparsers(
+        dest="sub", required=True)
+
+    def _policy_flags(sp):
+        sp.add_argument("--budget", type=int, default=900,
+                        help="seconds the orchestrator waits (task timeout)")
+        sp.add_argument("--heartbeat", type=int, default=120, help="heartbeat timeout in seconds")
+        sp.add_argument("--slack", type=int, default=120, help="VM outlives the budget by this many seconds")
+        sp.add_argument("--heartbeat-every", type=int, default=30, help="seconds between VM heartbeats")
+
+    la = le.add_parser("asl", help="print the Step Functions state machine (JSONata) for one lease")
+    la.add_argument("--image", required=True, help="image name or ARN")
+    la.add_argument("--execution-role", default=None,
+                    help="VM execution role ARN (default: MVM_EXECUTION_ROLE_ARN)")
+    la.add_argument("--name", default="Lease", help="name of the lease state")
+    la.add_argument("--task-expr", default="$states.input", help="JSONata expression for the task")
+    _policy_flags(la)
+    la.set_defaults(fn=cmd_lease_asl)
+
+    lp = le.add_parser("policy", help="print the IAM statements for the VM role and the orchestrator role")
+    lp.add_argument("--kind", required=True, choices=["sfn", "durable", "sqs", "eventbridge", "http"])
+    lp.add_argument("--orchestrator", default=None,
+                    help="state machine, function, queue, or bus ARN the VM completes to")
+    lp.add_argument("--execution-role", default=None, help="VM execution role for iam:PassRole")
+    lp.set_defaults(fn=cmd_lease_policy)
+
+    lr = le.add_parser("run", help="launch one lease by hand (manual tests)")
+    lr.add_argument("image")
+    lr.add_argument("--kind", required=True, choices=["sfn", "durable", "http", "sqs", "eventbridge", "none"])
+    lr.add_argument("--token", default=None, help="task token, callback id, or bearer (not for kind none)")
+    lr.add_argument("--target", default=None, help="http URL, SQS queue URL, or event bus name")
+    lr.add_argument("--task", default=None, help="task JSON (pointers, not bodies; 4096 chars total)")
+    lr.add_argument("--id", default=None, help="human label carried as lease.id")
+    lr.add_argument("--version", help="image version (default: latest ACTIVE)")
+    lr.add_argument("--execution-role", default=None)
+    lr.add_argument("--wait", action="store_true", help="poll until RUNNING")
+    _policy_flags(lr)
+    lr.set_defaults(fn=cmd_lease_run)
+
     tp = sub.add_parser("top", help="live fleet dashboard")
     tp.add_argument("--image")
     tp.add_argument("--watch", action="store_true")
     tp.add_argument("--interval", type=float, default=3)
     tp.set_defaults(fn=cmd_top)
 
-    lg = sub.add_parser("logs", help="tail CloudWatch logs for an image")
+    lg = sub.add_parser("logs", help="tail CloudWatch logs for an image (/aws/lambda-microvms/<image>)")
     lg.add_argument("image")
     lg.add_argument("--minutes", type=int, default=15)
     lg.set_defaults(fn=cmd_logs)
@@ -371,6 +551,14 @@ def main(argv: list[str] | None = None):
     co.add_argument("--cycles", type=int, default=1, help="suspend/resume cycles")
     co.set_defaults(fn=cmd_cost)
 
+    pgp = sub.add_parser("playground", help="local browser UI that drives the SDK against the live service")
+    pgp.add_argument("--host", default="127.0.0.1")
+    pgp.add_argument("--port", type=int, default=8765)
+    pgp.add_argument("--dry-run", action="store_true",
+                     help="start with dry run on: mutating actions are recorded, not sent")
+    pgp.add_argument("--no-open", action="store_true", help="do not open a browser tab")
+    pgp.set_defaults(fn=cmd_playground)
+
     args = p.parse_args(argv)
     try:
         args.fn(args)

{microvm_ctl-0.1.0 → microvm_ctl-0.2.0}/microvm/endpoint.py

@@ -15,6 +15,7 @@ retries the two endpoint errors you must design for:
 
 from __future__ import annotations
 
+import json
 import random
 import time
 
@@ -127,6 +128,47 @@ class EndpointClient:
             time.sleep(1)
         raise EndpointError(f"{self.microvm_id} not serving {path} after {timeout}s")
 
+    # -- job telemetry (HookApp built-in /status and /events) -------------------
+    def status(self, since: int | None = None) -> dict:
+        """The hook runtime's job snapshot (`GET /status`): phase, progress, counters,
+        the log tail, and the lease state. `since` returns only log lines with a
+        sequence number above it."""
+        path = "/status" if since is None else f"/status?since={int(since)}"
+        resp = self.get(path, timeout=10)
+        if resp.status_code != 200:
+            raise EndpointError(f"{self.microvm_id} answered {resp.status_code} on {path}")
+        return resp.json()
+
+    def watch(self, timeout: float = 600):
+        """Stream `GET /events` (Server-Sent Events) and yield each parsed JSON object:
+        log lines as they happen plus a snapshot every few seconds. Stops when a
+        snapshot reports the lease done, on `timeout` seconds, or when the VM closes
+        the stream."""
+        deadline = time.time() + timeout
+        resp = self.request("GET", "/events", timeout=(10, 30), max_attempts=1, stream=True)
+        if resp.status_code != 200:
+            raise EndpointError(f"{self.microvm_id} answered {resp.status_code} on /events")
+        try:
+            for line in resp.iter_lines():
+                if time.time() > deadline:
+                    return
+                if isinstance(line, bytes):
+                    line = line.decode("utf-8", "replace")
+                if not line.startswith("data:"):
+                    continue
+                try:
+                    obj = json.loads(line[5:].strip())
+                except ValueError:
+                    continue
+                yield obj
+                lease = obj.get("lease") if isinstance(obj, dict) else None
+                if isinstance(lease, dict) and lease.get("done"):
+                    return
+        except requests.RequestException:
+            return
+        finally:
+            resp.close()
+
     def shell_token(self, minutes: int = 15) -> dict[str, str]:
         """Token for interactive shell access (VM must run with SHELL_INGRESS)."""
         return dict(

{microvm_ctl-0.1.0 → microvm_ctl-0.2.0}/microvm/fleet.py

@@ -18,6 +18,7 @@ from typing import Callable
 
 from microvm.client import image_arn, microvm_client
 from microvm.config import TPS, PlaneConfig
+from microvm.lease import Lease, LeasePolicy, client_token, encode_payload
 from microvm.throttle import Throttled
 
 ACTIVE_STATES = {"PENDING", "RUNNING", "SUSPENDING", "SUSPENDED"}
@@ -122,7 +123,7 @@ class FleetManager:
         return self.quotas.get("MaxMemoryGb")
 
     # -- single VM ---------------------------------------------------------------
-    def run(
+    def run_params(
         self,
         image: str,
         *,
@@ -133,7 +134,14 @@ class FleetManager:
         ingress: list[str] | None = None,
         egress: list[str] | None = None,
         execution_role: str | None = None,
-    ) -> Microvm:
+        client_token: str | None = None,
+    ) -> dict:
+        """The exact RunMicrovm request `run` would send, for inspection or dry runs.
+
+        `client_token` (1 to 128 chars) makes the launch idempotent on the service
+        side: a retried request with the same token returns the same microVM instead
+        of a second one. Use it whenever the caller may replay, such as a durable
+        function step."""
         params: dict = {"imageIdentifier": image_arn(image, self.cfg.region, self.cfg.profile)}
         if version:
             params["imageVersion"] = version
@@ -149,8 +157,52 @@ class FleetManager:
         role = execution_role or self.cfg.execution_role_arn
         if role:
             params["executionRoleArn"] = role
+        if client_token:
+            params["clientToken"] = client_token
+        return params
+
+    def run(
+        self,
+        image: str,
+        *,
+        version: str | None = None,
+        idle_policy: IdlePolicy | None = None,
+        run_payload: str | None = None,
+        max_duration: int | None = None,
+        ingress: list[str] | None = None,
+        egress: list[str] | None = None,
+        execution_role: str | None = None,
+        client_token: str | None = None,
+    ) -> Microvm:
+        params = self.run_params(
+            image, version=version, idle_policy=idle_policy, run_payload=run_payload,
+            max_duration=max_duration, ingress=ingress, egress=egress, execution_role=execution_role,
+            client_token=client_token,
+        )
         return Microvm.from_api(self._run(**params))
 
+    def lease(
+        self,
+        image: str,
+        lease: Lease,
+        task: dict,
+        policy: LeasePolicy | None = None,
+        *,
+        version: str | None = None,
+        execution_role: str | None = None,
+        ingress: list[str] | None = None,
+        egress: list[str] | None = None,
+    ) -> Microvm:
+        """RunMicrovm with the lease in runHookPayload, the policy's idle policy and duration cap,
+        and clientToken = client_token(lease). One call, idempotent on the token."""
+        policy = policy or LeasePolicy()
+        return self.run(
+            image, version=version, idle_policy=policy.idle_policy(),
+            run_payload=encode_payload(lease, task), max_duration=policy.max_duration(),
+            ingress=ingress, egress=egress, execution_role=execution_role,
+            client_token=client_token(lease),
+        )
+
     def get(self, microvm_id: str) -> Microvm:
         return Microvm.from_api(self.api.get_microvm(microvmIdentifier=microvm_id))