Skip to main content

​
Deployment

A single command deploys your Idyllic application to production: 
npx idyllic deploy
The CLI bundles your system code, uploads it to Cloudflare Workers, and provisions the Durable Object namespace. Your application runs on Cloudflare’s global edge network—300+ cities, automatic routing to the nearest data center.

​
What Gets Deployed

Your project
├── idyllic/
│   └── system.ts      ← Deployed to Cloudflare Workers
├── app/               ← Deploy separately (Vercel, Cloudflare Pages, etc.)
├── idyllic.json       ← Configuration
└── .dev.vars          ← Local only; use `idyllic env` for production
Backend and frontend deploy separately. Your AI system deploys to Cloudflare Workers. Your frontend deploys to your hosting platform of choice. They communicate via WebSocket, so you can mix deployment targets freely.

​
Environment Variables

During development, store variables in .dev.vars (gitignored): 
# .dev.vars
OPENAI_API_KEY=sk-...
DATABASE_URL=postgres://...
For production, use the CLI: 
npx idyllic env set OPENAI_API_KEY sk-...
npx idyllic env list
npx idyllic env remove VARIABLE_NAME
Values are encrypted at rest. Access them through the env object: 
class MySystem {
  constructor(private env: Env) {
    this.openai = new OpenAI({ apiKey: env.OPENAI_API_KEY });
  }
}

​
How It Works

​
Cloudflare Workers

Your code runs as a Cloudflare Worker using V8 isolates (the Chrome JavaScript engine). Unlike container-based serverless (Lambda, Cloud Functions), isolates cold-start in under 5ms. The cold start problem effectively disappears. Workers run in 300+ data centers. A user in Tokyo executes code in Tokyo. Scaling happens automatically. You pay for actual usage, not provisioned capacity.

​
Durable Objects

Each conversation gets its own Durable Object instance. DOs provide:
  • Isolation: Conversations cannot share or corrupt each other’s state
  • Persistence: State survives across requests; return hours later and history remains
  • Single-threaded execution: One request at a time, no race conditions, no locks needed
  • Geographic mobility: DOs can migrate closer to users as they move
When a user connects, Cloudflare routes them to their conversation’s DO. If hibernating, it wakes up. If none exists, one is created.

​
WebSocket Connections

Clients connect via WebSocket. The Worker hands the connection to the appropriate Durable Object, which maintains it for the session duration. The DO receives messages, processes them through your system, and streams responses back. Cloudflare handles TLS, connection establishment, automatic reconnection, and rate limiting.

​
Configuration

The idyllic.json file controls deployment: 
{
  "name": "my-system",
  "compatibility_date": "2024-01-01"
}
The name determines your production URL (my-system.idyllic.run). The compatibility_date pins runtime API versions.

​
Multiple Environments

npx idyllic deploy              # production
npx idyllic deploy --env staging
npx idyllic deploy --env preview-123
Each environment is fully isolated—separate Workers, Durable Objects, and state. Environment variables are scoped too: 
npx idyllic env set OPENAI_API_KEY sk-test-... --env staging
npx idyllic env set OPENAI_API_KEY sk-prod-... --env production

​
Monitoring

​
Logs

npx idyllic logs          # real-time streaming
npx idyllic logs --recent # view recent logs
Logs include request timing, errors, and console.log output.

​
Metrics

Track request volume, latency (P50/P95/P99), active connections, storage usage, and error rates through the dashboard.

​
Cost

Cloudflare Workers uses usage-based pricing:
  • Workers: First 100K requests/day free, then $0.50 per million
  • Durable Objects: 0.15permillionrequests,0.15 per million requests, 0.20 per GB-month storage
A system handling one million requests/month with moderate state storage costs $5-15/month. AI model APIs typically cost 10-100x more than infrastructure.

​
Local vs Production

Aspectidyllic devidyllic deploy
RuntimeLocal emulator (wrangler)Global edge network
StateLocal SQLite fileDurable Objects
URLlocalhost:8787your-system.idyllic.run
Secrets.dev.vars fileEncrypted env variables
Code runs identically in both environments. If it works locally, it works in production.

​
Custom Domains

npx idyllic domains add api.yourdomain.com
Automatic DNS configuration and SSL provisioning through Cloudflare.

​
FAQ

​
How long does deployment take?

Under 30 seconds. Bundling is fast (esbuild), upload is small, and Cloudflare propagates globally within seconds.

​
Can I deploy from CI/CD?

Yes: 
npx idyllic deploy --token $IDYLLIC_DEPLOY_TOKEN
Generate tokens from the dashboard. Tokens can be scoped and revoked.

​
What happens during deployment?

Zero-downtime rolling update. New requests go to the new version. Existing WebSocket connections continue on the old version until they close naturally. State persists—Durable Objects aren’t recreated.

​
Can I rollback?

npx idyllic rollback
Or deploy a previous commit from git history.

​
Can I self-host?

The runtime depends on Cloudflare’s Durable Objects for state management. Reimplementing DO semantics (single-threaded execution, automatic persistence, geographic migration) is significant engineering effort. For most use cases, managed infrastructure is simpler and more cost-effective.