Inspirations vs runtimes

Every entity on the grid is either an inspiration or a runtime. This is the single most useful distinction to internalize.

Side by side

	Inspiration	Runtime
What it holds	Static content: a single HTML page, a deck, a doc, an artifact, a PDF	A running service: an app or an agent
Defined by	Just the file	A cloudgrid.yaml manifest
Build	None — published instantly	Built into a container, then deployed
URL shape	Path: <grid>.cloudgrid.io/<slug>	Subdomain: <slug>.<grid>.cloudgrid.io
Lifecycle	Ephemeral — 30-day expiry unless pinned	Persistent
Infrastructure	None	Database, cache, cron, AI gateway, secrets
Where you can make it	Any edition (CLI, hosted MCP, local MCP)	Local edition (CLI or local MCP)

When it is an inspiration

Reach for an inspiration when the deliverable is one self-contained thing:

• A single HTML page (CSS and JS inline, images and fonts as data: URIs).
• A document, deck, PDF, or image.
• A Claude artifact or a code snippet you want to share.

grid plug ./landing.html

Inspirations deploy synchronously, so you get a URL right away. They keep no server-side state — a static page keeps state only in the browser and loses it on refresh.

When it is a runtime

Reach for a runtime (an app or agent) when the work needs to run:

• Separate files or folders (an assets/ directory, multiple pages, a SPA build).
• Server-side logic, an API, or a background job.
• Persistence — saving data, logging submissions, sharing state across users or sessions.
• A schedule (a cron job or an agent).
• The AI gateway, a database, or a cache.

grid new my-api --type node
grid plug

Runtime builds are asynchronous — grid plug uploads your source, builds a container, and rolls it out. Watch progress with grid status or grid logs.

Graduating an inspiration to a runtime

An inspiration can become a full app without changing its URL or losing its history:

1. Pick it up into a local folder: grid pickup my-deck
2. Add a cloudgrid.yaml describing the services it should run.
3. grid plug — the entity graduates from inspiration to runtime. The URL and history are preserved.