Operator or individual
CLI or small console
Create Agents and Sessions, follow streamed Items, return function results, and manage Vault credentials.
rat-things sessions list
A cloud for your agents · Self-hosted in your AWS account
The open-source backend
for cloud agents.
Run durable, isolated agents in your AWS account. Hand off from local Codex, start work from Slack or Linear, trigger it from a schedule or your product, and let bounded tasks keep running without your laptop.
Engineering preview · self-hosted in your AWS account · not ready for untrusted multi-tenant production
- Durable agents
- keep working after you step away
- Fixed access
- permissions are resolved before each run
- Connected work
- Slack, Linear, private files, and accounts
- OpenAPI
- one discoverable API for products, CLIs, and agents
One path into the cloud
Start locally. Continue in an AWS Session.
Local Codex is one fast path into Rat Things. The AWS backend becomes a durable execution layer when a task needs time, parallel agents, schedules, connected accounts, or an entry point beyond your laptop.
Bring the Codex access included with your ChatGPT plan—no OpenAI Platform API key or Bedrock setup required—or start from Slack, Linear, a schedule, your product, or the API.
-
01
Sign in once
npm ci npm run codex:login # official ChatGPT browser login -
02
Work locally
rat-things local \ "Inspect this repo and fix the test" local Codex → local tools → local files -
03
Create a Session
rat-things sessions create \ --file session.json Agent → Session → Turns and Items
Bring your own experience
Use it from
the interface you own.
Rat Things is a self-hosted AWS stack with no central Rat service. A CLI, your product, another agent, a schedule, or a signed provider event can use the same public API and durable Session model.
Embedded product
Your UX, our primitives
Keep customer identity and the provider app in your product or AWS account. The self-hosted Rat stack can run PKCE callbacks and refresh; credentials remain in your Secrets Manager.
POST /v1/agents
Agent-to-agent
Machine-readable backend
Give an agent the deployment URL. It discovers the installed contract, starts with Agents and Sessions, and opens deeper controls only when needed.
GET /.well-known/rat-things
Agent quickstart
Events and schedules
Automation without a UI
Schedules select an owned Agent and environment. Signed provider events submit Session input through separate authenticated ingress.
cron(0 8 ? * MON-FRI *)
The host decides whether one deployment serves one person or many authenticated users. Rat derives an owner from each trusted principal and keeps Agents, Sessions, Vaults, and files within that boundary.
Slack → Rat Things → Linear
Turn conversation
into tracked work.
Start with an approved request in Slack. Let one isolated Session find the source context, check Linear for existing work, and create or update the issue through exact OAuth-backed operations.
Slack and Linear are separate verified Connections. The agent receives only the accounts and operations admitted before launch; neither credential enters its prompt or workspace.
Explore integrations, accounts, and permissions
# customer-ops
01 · Request in Slack
✓ Same thread · same durable conversation · bounded Linear writes
Linear
02 · Tracked outcome
ENG-482In Progress
Close renewal security gaps
Resolve the security review and confirm the rollout owner before the annual renewal is finalized.
Rat Things
Created from the approved #customer-ops decision. Added the two open items and rollout note.
Just now · app actorInstall both accounts
Connect Slack and Linear through deployment-owned OAuth. Rat verifies each provider identity and stores issued credentials in the host vault.
Resolve a fixed envelope
Select the Slack read and Linear read/write operations this Session needs. Provider scopes, grants, profiles, and resource limits all intersect.
Research before writing
Search the source thread and existing issues first. The agent can create, update, or comment only through reviewed GraphQL documents.
Keep the work durable
The Slack thread, Linear result, Turn and Item history, generated files, and native Codex context remain traceable across clients and compute.
Bring Slack and Linear into one workflow.
Connect both accounts, choose what Rat Things can do, and keep every handoff tied to the conversation that started it.
Rat Things for Linear
Connect issue tracking to your agent.
Install a verified Linear workspace, choose its account and operation grants, and expose the needed actions through declared MCP or application-function tools.
Sessions retain tool activity and results. Keep notification delivery separate from tool access, and enforce duplicate-creation protection in the tool implementation.
Set up LinearYour connected-service catalog
One contract.
As many trusted integrations as you choose.
Linear, Slack, and Stripe are built-in examples of Rat's Integration Contract, not the boundary of the system. Add the OAuth or API services your deployment needs by declaring authentication, account identity, operations, schemas, and a fixed provider origin—then compile each reviewed adapter into the trusted host.
The connection manager, permission intersection, credential broker, agent tools, CLI, and desktop controls reuse that contract instead of inventing a new integration path.
Build a trusted integration- 01Describe
Publish authentication choices, account metadata, operation schemas, access levels, and required provider scopes.
- 02Verify
Resolve the provider's real tenant and subject before a credential becomes an installed Connection.
- 03Constrain
Intersect provider authority, the persistent grant, the profile, and declared tools and resource constraints.
- 04Expose
Generate safe account setup, health, reconnect, “used by,” and agent-tool surfaces from the installed contract.
- 05Reuse
Bind signed provider events and schedules to owned Agents and submit work through Sessions.
Extensions are trusted host code. Rat does not load arbitrary provider packages inside the agent. Credentials stay in the host vault, provider calls use reviewed adapters, and the agent receives only admitted operation schemas.
Agents and Sessions
Follow each Turn.
Keep its results.
The reference console creates Sessions, displays streamed Items, submits function results, and cancels active Turns. Saved history remains available after a reload.
Manage reusable Agents and write-only Vault credentials from the same authenticated client.
rat-things sessions listreads the same durable Session resources.
rat-things consoleopens the local signed client for your deployment.
The reference console and CLI use the same Agents, Sessions, Turns, Items, environments and Vault contracts.
How work survives
The machine can stop.
The work continues.
Accepted input belongs to a durable Session Turn. Rat stores Items and artifacts outside compute. S3 Files preserves workspace and native checkpoints for replacement workers; interrupted processes are not recreated by file recovery.
- 01Authenticate
Verify IAM or a provider signature and derive the owner.
- 02Commit
Commit Session input with an idempotent receipt.
- 03Prepare
Resolve the saved Agent configuration and restore available native state.
- 04Execute
Launch or resume Codex with the tools and access resolved before the run.
- 05Retain
Retain Turn Items and saved artifacts. Delete the Session when its worker is no longer needed.
Authority is decided before launch
Autonomous inside.
Unavailable outside.
Choose permissions before creating a Session. The agent can use what you allowed; everything else is unavailable. Rat never pauses to ask for more permission during a Turn.
Read the complete capability contractInside the envelope
Use it autonomously
Admitted shell, files, browser actions, network destinations, and connected-account operations are available within the resolved Session configuration.
Outside the envelope
Absent or denied
The tool is missing, IAM returns AccessDenied, URL or egress policy blocks the destination, or the broker rejects the operation before reading a credential.
No suspended permission state: denied operations do not create approval requests. To change authority, configure an Agent and create a new Session with the required tools and environment.
Core capabilities
Build, connect, run, and retain.
Build and schedule
Configure an Agent, start a Session, or bind it to a rate or cron schedule.
Connect accounts safely
Verify several accounts per integration, monitor health, reconnect the same identity without rebinding workflows, and narrow provider access before use.
Declare browser tools
Expose browser operations through functions or MCP, constrain their access, and retain selected screenshots and recordings as Session artifacts.
Continue Sessions
Read Turns and Items, send follow-up input, submit function results, and continue work across clients.
Retain and share files
Keep generated files privately, inspect them through owner-gated viewers, or create expiring external links.
Use one Session model
API calls, schedules and signed provider events use the same Agent, Session, Turn and Item primitives.
Embed the API
Discover OpenAPI, JSON Schemas, integration manifests, stable errors, and capability profiles from each deployment.
Bring your Codex plan
Use the Codex access included with your ChatGPT plan locally, then delegate explicitly to OpenAI-authenticated cloud agents. Bedrock is optional.
Durability by design
Work that survives
the machine.
Sessions, files, schedules, connections, and results live outside ephemeral compute. Each Session resolves its authority before execution and retains Turns and Items for connected clients.
- ✓Exact account authority
Choose provider accounts and grants before launch. Keep provider credentials in the configured vault or trusted tool service.
- ✓One Session across clients
The console, CLI and API read the same durable Turns and Items. Signed provider bindings add input and deliver saved results.
- ✓Replacement continuity with S3 Files
Retain native checkpoints and workspace files outside the worker. Recovery uses saved state; live processes require the original connected worker.
- ✓Inspect work and retained files
Read Session activity and saved Items, continue with new input, and download selected artifacts through the authenticated API.
- ✓Schedules and provider events
Manual work, durable schedules, and signed provider events use the same Session lifecycle and saved-result delivery model.
Deployment and Session costs
Know what stays running.
Measure what work costs.
Your deployment pays for its API and relay baseline, connected workers, model usage, storage and networking. A worker that preserves live processes continues to consume compute while idle.
Understand the cost driversAccount for the complete deployment
- Model
- Requested model, input and output tokens, cached context, and tool usage.
- Compute
- API and relay services plus the lifetime of each connected worker.
- Storage
- Encrypted Session state, workspace files, artifacts and retained logs.
- Network
- Load balancing, NAT, private endpoints and transferred data.
Measure startup, continuation and cost in your own region with the selected backend and model. Retention policies and explicit Session deletion control resources that outlive a Turn.
How it works
A small public contract.
Durable AWS internals.
Your product, another agent, a CLI, or a signed event submits work. Rat authenticates it, accepts a Session input, executes it in your AWS account, and retains the result.
Architecture guide