try-works/role-model / .agents/skills/cloudflare
cloudflare
UnverifiedComprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), feature flags (Flagship), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). Use for any Cloudflare development task. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
references/containers/api.md
View on GitHub## Container Class API
```typescript
import { Container } from "@cloudflare/containers";
export class MyContainer extends Container {
defaultPort = 8080;
requiredPorts = [8080];
sleepAfter = "30m";
enableInternet = true;
pingEndpoint = "/health";
envVars = {};
entrypoint = [];
onStart() { /* container started */ }
onStop() { /* container stopping */ }
onError(error: Error) { /* container error */ }
onActivityExpired(): boolean { /* timeout, return true to stay alive */ }
async alarm() { /* scheduled task */ }
}
```
## Routing
**getByName(id)** - Named instance for session affinity, per-user state
**getRandom()** - Random instance for load balancing stateless services
```typescript
const container = env.MY_CONTAINER.getByName("user-123");
const container = env.MY_CONTAINER.getRandom();
```
## Startup Methods
### start() - Basic start (8s timeout)
```typescript
await container.start();
await container.start({ envVars: { KEY: "value" } });
```
Returns when **process starts**, NOT when ports ready. Use for fire-and-forget.
### startAndWaitForPorts() - Recommended (20s timeout)
```typescript
await container.startAndWaitForPorts(); // Uses requiredPorts
await container.startAndWaitForPorts({ ports: [8080, 9090] });
await container.startAndWaitForPorts({
ports: [8080],
startOptions: { envVars: { KEY: "value" } }
});
```
Returns when **ports listening**. Use before HTTP/TCP requests.
**Port resolution:** explicit ports → requiredPorts → defaultPort → port 33
### waitForPort() - Wait for specific port
```typescript
await container.waitForPort(8080);
await container.waitForPort(8080, { timeout: 30000 });
```
## Communication
### fetch() - HTTP with WebSocket support
```typescript
// ✅ Supports WebSocket upgrades
const response = await container.fetch(request);
const response = await container.fetch("http://container/api", {
method: "POST",
body: JSON.stringify({ data: "value" })
});
```
**Use for:** All HTTP, especially WebSocket.
### containerFetch() - HTTP only (no WebSocket)
```typescript
// ❌ No WebSocket support
const response = await container.containerFetch(request);
```
**⚠️ Critical:** Use `fetch()` for WebSocket, not `containerFetch()`.
### TCP Connections
```typescript
const port = this.ctx.container.getTcpPort(8080);
const conn = port.connect();
await conn.opened;
if (request.body) await request.body.pipeTo(conn.writable);
return new Response(conn.readable);
```
### switchPort() - Change default port
```typescript
this.switchPort(8081); // Subsequent fetch() uses this port
```
## Lifecycle Hooks
### onStart()
Called when container process starts (ports may not be ready). Runs in `blockConcurrencyWhile` - no concurrent requests.
```typescript
onStart() {
console.log("Container starting");
}
```
### onStop()
Called when SIGTERM received. 15 minutes until SIGKILL. Use for graceful shutdown.
```typescript
onStop() {
// Save state, close connections, flush logs
}
```
### onError()
Called when container crashes or fails to start.
```typescript
onError(error: Error) {
console.error("Container error:", error);
}
```
### onActivityExpired()
Called when `sleepAfter` timeout reached. Return `true` to stay alive, `false` to stop.
```typescript
onActivityExpired(): boolean {
if (this.hasActiveConnections()) return true; // Keep alive
return false; // OK to stop
}
```
## Scheduling
```typescript
export class ScheduledContainer extends Container {
async fetch(request: Request) {
await this.schedule(Date.now() + 60000); // 1 minute
await this.schedule("2026-01-28T00:00:00Z"); // ISO string
return new Response("Scheduled");
}
async alarm() {
// Called when schedule fires (SQLite-backed, survives restarts)
}
}
```
**⚠️ Don't override `alarm()` directly when using `schedule()` helper.**
## State Inspection
### External state check
```typescript
const state = await container.getState();
// state.status: "starting" | "running" | "stopping" | "stopped"
```
### Internal state check
```typescript
export class MyContainer extends Container {
async fetch(request: Request) {
if (this.ctx.container.running) { ... }
}
}
```
**⚠️ Use `getState()` for external checks, `ctx.container.running` for internal.**
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |