Framework guides

Lambda MicroVMs connector

Govern AWS Lambda MicroVM launches, endpoint tokens, shell access, and lifecycle controls with Contro1 approvals, audit evidence, and bypass detection.

AWS Lambda MicroVMs isolate AI-generated code. Contro1 governs the decision to run it with approval routing, token brokerage, and audit evidence.

Use the integration skill

Copy this skill link into your code agent to add Lambda MicroVMs and Contro1 to your system.

Copy skill link

Key takeaways

Use Contro1 as the governed launcher before RunMicrovm instead of giving agents direct cloud authority.
Broker endpoint and shell tokens through Contro1 so access is scoped, short-lived, approved, and auditable.
Treat direct AWS calls and MicroVMs without a contro1_request_id as unmanaged or bypassed execution.
Runtime shims are the next layer: launcher controls whether the MicroVM runs; shim controls what tools do inside it.

What this connector does

The connector is the small server from this GitHub repo. You deploy it in your cloud account or hosting environment, and your agent calls this server instead of calling AWS Lambda MicroVM APIs directly.

That server acts as a governed MicroVM launcher and token broker. It checks the request, asks Contro1 for approval when needed, and only then calls AWS.

Contro1 sits before the risky action: launch, endpoint token creation, shell token creation, suspend, resume, and terminate. It decides whether the request is auto-approved, sent to a human, or blocked.

RunMicrovm is governed before execution starts.
CreateMicrovmAuthToken is governed by port scope and token lifetime.
CreateMicrovmShellAuthToken always requires approval.
Suspend, resume, and terminate are logged as lifecycle control events.

Open the GitHub repo · Requests API · Webhooks

What to prepare in Contro1

Contro1 is where the approval decision happens. You create an API key there, choose who reviews risky MicroVM actions, and Contro1 keeps the evidence for every request.

Create a Contro1 account and organization.
Open Settings -> APIs & Webhooks.
Create an API key named something like Lambda MicroVMs connector.
Copy the API key value into the environment variables of the server you deploy from this repo as CONTRO1_API_KEY.
Reveal or rotate the organization webhook secret.
Copy the webhook secret into that same deployed server as CONTRO1_WEBHOOK_SECRET.
Choose where approvals go: dashboard, Slack, Microsoft Teams, or your operator workflow.
Define reviewer routing such as required role, department, SLA, and escalation.
Keep the API key and webhook secret outside source control.

What to prepare in the deployed server

Deploy one of the runnable example servers from this repo: examples/typescript/src/server.ts for TypeScript/Express, or examples/python/app.py for Python/Flask.

That server can run on Cloud Run, ECS, Kubernetes, a VM, Render, Fly.io, or any host that can receive HTTPS requests.

Set PUBLIC_BASE_URL to the public address of that deployed server. If the server is available at https://microvms.example.com, it will tell Contro1 to send the approval answer to https://microvms.example.com/contro1/callback.

When an operator approves or denies the request, Contro1 sends a signed POST to that route on your server. The server verifies the signature with CONTRO1_WEBHOOK_SECRET. Only then does it call AWS.

TypeScript local run: cd examples/typescript, npm install, npm run dev.
Python local run: cd examples/python, install requirements.txt, python app.py.
Set CONTRO1_API_KEY from Settings -> APIs & Webhooks.
Set CONTRO1_WEBHOOK_SECRET from Settings -> APIs & Webhooks.
Set PUBLIC_BASE_URL to the public HTTPS address of the deployed server.
Set allowed agents, image ARNs, execution role ARNs, token ports, max duration, and token TTL in the deployed server environment.

What to prepare in AWS

AWS remains the execution surface. The deployed server from this repo should use a dedicated AWS role. Do not give broad MicroVM permissions directly to agents, developers, or CI jobs that should go through approval.

Confirm Lambda MicroVMs is available in your AWS account and region.
Create or select the MicroVM image that agents are allowed to run.
Create a dedicated IAM role for the Contro1 connector/launcher.
Grant only the needed MicroVM lifecycle and token permissions to that connector role.
Create constrained execution roles for the MicroVM workloads.
Remove direct RunMicrovm and token permissions from agents, developers, and CI roles that should be governed.
Enable CloudTrail for MicroVM API activity so direct bypass calls can be detected.
Enable CloudWatch/runtime logs if you need stdout, stderr, or application-level evidence.
Pass or tag metadata such as contro1_request_id, agent id, owner, environment, and correlation id.

Local vs production mode

Use SIMULATE_AWS=true while evaluating the repo and testing policy behavior. This requires no AWS setup.

If you want to test real approval answers from Contro1 locally, expose the connector with a tunnel and set PUBLIC_BASE_URL to that tunnel URL.

Switch to SIMULATE_AWS=false only after the AWS account, region, IAM role, approved image ARNs, execution roles, CloudTrail/logging choices, and AWS SDK or boto3 support are ready.

Why isolation is not enough

A MicroVM can isolate code, but it does not decide whether an AI agent should be allowed to run that code, which role it may use, whether it can reach the internet or VPC, who approved shell access, or how the decision is proven later.

The control point is outside the VM: do not give the agent direct IAM permission for lifecycle and token APIs. Put Contro1 in front of those calls.

Threat model

Agent launches a sandbox with a production execution role.
Agent requests shell access without owner approval.
Developer creates a broad all-port auth token.
AI coding agent runs unreviewed generated code.
Long-running MicroVM keeps state without an audit trail.
Unknown agent launches a MicroVM outside the approved registry.
MicroVM gets internet or VPC access without human approval.

Bypass prevention

For Contro1 to be a real control layer, it must be the only principal allowed to call high-risk MicroVM lifecycle and token APIs.

Use IAM and CloudTrail together: restrict direct calls, then detect any call path that did not carry Contro1 request metadata.

Agents do not get direct lambda:RunMicrovm.
Developers do not get direct shell token permissions.
Endpoint and shell tokens are issued only through Contro1.
CloudTrail detects direct calls outside Contro1.
Any MicroVM without a contro1_request_id is treated as unmanaged.

Policy defaults

Decision	Default behavior
Auto-approve	Known agent, allowed image, constrained non-production role, no shell, scoped short-lived token, short duration, no private network access.
Require approval	Shell access, broad or long-lived token, VPC/private egress, production role, long duration, new image, or AI-generated workflow.
Block	Unknown owner, disabled agent, shell plus production role, unmanaged image, missing execution-role constraints, or bypass indicators.

TypeScript quick start

terminal

git clone https://github.com/contro1-hq/contro1-aws-lambda-microvms-connector
cd contro1-aws-lambda-microvms-connector/examples/typescript
npm install
cp ../../.env.example .env
npm run dev

Python quick start

terminal

git clone https://github.com/contro1-hq/contro1-aws-lambda-microvms-connector
cd contro1-aws-lambda-microvms-connector/examples/python
python -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cp ../../.env.example .env
python app.py

Event taxonomy

The connector emits audit-first event names so security, operations, and compliance can search the full execution timeline.

events.txt

aws.microvm.run.requested
aws.microvm.run.approved
aws.microvm.run.denied
aws.microvm.run.created
aws.microvm.auth_token.requested
aws.microvm.auth_token.issued
aws.microvm.shell_token.requested
aws.microvm.shell_token.approved
aws.microvm.shell_token.denied
aws.microvm.suspend.requested
aws.microvm.resume.requested
aws.microvm.terminate.requested
aws.microvm.bypass.detected
aws.microvm.unmanaged.detected

Important limitation

Contro1 cannot cleanly stop an already-running command inside a MicroVM unless the runtime or tool gateway is instrumented.

The launcher governs lifecycle, endpoint tokens, and shell access. A future runtime shim governs bash, file, network, and tool calls after the MicroVM starts.

Make the approval the gate, not a suggestion

The signed webhook is cryptographic proof of a human decision. Verify it inside the system that executes the action - not inside the agent. Any tool that must never run without human sign-off (payments, deploys, data deletion) should refuse to act without a verified approval; that way no agent, including shadow agents nobody registered, can trigger it by skipping Contro1.

Verify the signature and reject timestamps older than 5 minutes (replay protection; the timestamp marks callback delivery, not request creation, so long SLAs are unaffected).
Bind the approval to the exact action parameters via metadata / correlation_id - never treat "an approval arrived" as permission for a different action.
Execute each request_id exactly once (idempotency on your side).
When in doubt, confirm state directly with GET /v1/requests/:id using a read-only API key.

Full guardrail pattern with code: Webhooks

Frequently asked questions

Is this a runtime shim?

No. The first connector is a governed launcher and token broker. Runtime shim and tool gateway controls are the next layer for command-level control inside the MicroVM.

Can agents still call AWS directly?

They should not. Production IAM should make Contro1 the only principal allowed to call high-risk MicroVM lifecycle and token APIs. Direct calls should be treated as bypass events.

Does the example call real AWS APIs?

The examples run in mock AWS mode by default. Set SIMULATE_AWS=false after your AWS SDK or boto3 version exposes the Lambda MicroVM API operations in your account and region.