Rat Things

AWS Lambda MicroVMs · Codex app-server · S3 Files

VM-level isolation.
Serverless scale.

Run durable Codex agents without an always-on worker fleet. Every active conversation gets a fenced MicroVM, while its history and workspace survive outside the machine.

View on GitHub Quick start
0
always-on agents
1
fenced owner per conversation
2 VMs
one Codex thread, live proven
E2E
LocalStack + live AWS
The subsystem

The runtime beneath
the agent.

Rat Things turns authenticated API calls and signed GitHub, GitLab, Teams, or Slack events into durable Codex work—not just ephemeral chat completions.

AWS holds the mailbox, history, artifacts, native Codex state, and workspace outside compute. MicroVMs wake for a turn, use tools, checkpoint, and suspend or disappear. Results return to the thread that asked.

Data flow

From mention to answer.
No permanent worker.

  1. 01Receive

    Verify IAM or a channel signature and normalize the source identity.

  2. 02Remember

    Commit the message and artifacts before spending compute.

  3. 03Fence

    Give exactly one MicroVM ownership of the conversation.

  4. 04Run

    Resume or launch Codex with its durable workspace and tools.

  5. 05Return

    Checkpoint state, release compute, and reply in the source thread.

Why MicroVMs

The isolation of a VM.
The operating model of Lambda.

Agent tools execute code the application did not write. Rat Things gives each active conversation a dedicated Firecracker guest instead of relying only on process-level or shared-kernel containment.

01

Dedicated guest kernel

Each session receives its own hardware-virtualized MicroVM boundary and resources.

02

Snapshot launch and resume

Pre-initialized environments wake rapidly and retain memory, disk, and processes while suspended.

03

Forceful termination

A hung shell, scraper, or tool process can be stopped by terminating its exact MicroVM.

04

No worker fleet

Lambda APIs own provisioning and lifecycle while the serverless control plane owns demand.

The VM limits execution blast radius; IAM, network policy, credentials, and destination authorization remain independent security boundaries.

The continuity layer

The machine can disappear.
The work doesn’t.

Codex app-server treats its state as a local filesystem. Rat Things gives each conversation a fenced S3 Files home, then restores that same home inside whichever MicroVM owns the next turn.

Turn one

MicroVM A

Codex uses tools, changes files, and records its native thread state.

terminated after checkpoint

Durable AWS state

S3 Files + DynamoDB

Workspace bytes and Codex SQLite state live beside a fenced lease, mailbox, and replay archive.

Turn two

MicroVM B

The replacement resumes the exact Codex thread and reads the exact workspace bytes.

live AWS validated

We tested the hard case: write a file with a real Codex tool call, terminate the first VM, observe the object in S3, then resume the same thread and file from a different VM.

What Rat Things owns

A complete agent runtime boundary.

01

Durable conversations

Prioritized mailbox, turn history, progress, replay checkpoints, and per-thread serialization.

02

Native Codex continuity

App-server thread state and workspace restoration, with normalized replay as the fallback.

03

Isolated tool use

Shell, Git, filesystem, and policy-controlled network access inside an unprivileged MicroVM worker.

04

Channel-native delivery

Signed ingress, immediate acknowledgement, durable work, and completion in the originating thread.

C4 architecture

The whole system.
Still a small boundary.

The views show the webhook-to-reply path, the continuity state beside disposable compute, and the two end-to-end validation environments.

C4 system context showing callers, Rat Things, model provider, and result destinations
C1System context
C4 container diagram for the Rat Things agent runtime
C2Agent runtime
C4 container diagram for the LocalStack test harness
C2LocalStack harness
C4 container diagram for the disposable live AWS test harness
C2Live AWS harness
Authentication

Codex-native.
Deployment-controlled.

Run against your ChatGPT subscription on a trusted device, use short-term Bedrock access in AWS, or remove model spend entirely for deterministic tests. A webhook cannot choose the credential mode.

Trusted local

ChatGPT subscription

Reuse the device's cached codex login session with the built-in OpenAI provider.

--codex-auth chatgpt

Unattended AWS

Short-term Bedrock

Mint a bounded bearer token from the execution role without exposing the AWS credential chain.

CODEX_AUTH_MODE=bedrock

Deterministic tests

Token-free mock

Exercise the orchestration and delivery contract without calling any model provider.

--driver mock
Evidence, not assumptions

We killed the machine.
The agent came back.

The suite crosses signatures, queues, leases, artifacts, MicroVM lifecycle, real Codex app-server calls, tool execution, S3 Files restoration, and threaded delivery.

Read the validation status
Quick start

Wake one up.

Start with the token-free path, connect your local Codex subscription, then deploy the same control plane as disposable AWS infrastructure.

git clone https://github.com/gpazo/Rat-Things.git
cd Rat-Things
npm ci
npm run check
npm run smoke:local
Engineering preview

Isolation is a boundary, not a permission slip.

Treat prompts, repositories, model output, and webhook fields as untrusted. Production still requires an independent IAM and malicious-repository review, budgets, outbound policy, output redaction, and destination authorization.