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.
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.
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
Python quick start
Event taxonomy
The connector emits audit-first event names so security, operations, and compliance can search the full execution timeline.
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.
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.