Concepts

Grain separates the useful thing your agent makes from the place it stays and the compute that may run it. An artifact is the output, a workspace is its durable home, and a sandbox is a runtime rather than the final destination. Start with the developer guide if you are choosing between the CLI, MCP and HTTP API.

Choose the model that matches the job

If you are…	Start with	Why
Writing one self-contained report or page	An html workspace and the first-artifact flow	No runtime or database is needed
Editing several files with an agent	A checkout through the CLI or MCP	Local edits can be reviewed and pushed explicitly
Building a dashboard or internal tool	An app runtime and runtime configuration	The app can execute code and use durable state
Calling Grain from an external service	The HTTP API	SQL, registered commands and Front Door have a published contract
Giving a coding agent Grain tools	MCP setup or integrations	The supported MCP server is local stdio, not a public URL

The three nouns

Concept	What it is	What it is not
Artifact	A page, report, walkthrough, internal app or dashboard made by an agent	The chat transcript or agent itself
Workspace	The durable place with a URL, files and runtime-local application state	A code editor, the Grain control-plane database or one-time execution
Sandbox	Compute where code runs once; hosted cloud workspaces use E2B microVM sandboxes	A guarantee that the output remains published

Artifact

Treat the artifact as the result another person opens. A static explanation may be one HTML page. An app may include files, a database-backed interface and runtime code. The current public templates use a workspace-local SQLite database when they need state; app login and scheduling do not have a general public setup recipe in this release. The useful boundary is the audience's job, not the framework or file count.

Workspace

A workspace gives the artifact continuity. Its files can be read again, linked to later work and exported. Its URL gives readers a stable address. If the artifact is an app, its runtime may hold application files and the workspace-local SQLite database at /project/workspace/data.db. Grain’s control-plane Postgres database is separate and is not the app’s public data store. Published artifacts remain published on the free tier after a session ends.

Checkout, sync and revision

A checkout is a local editing copy. In checkout mode, edits do not reach the workspace until push; use history to confirm a checkpoint. A sync folder can continuously synchronize a linked folder, but a command already running in a different sync folder is not silently reused. MCP-created workspaces use checkout mode and require an explicit push after edits. Remote drift means another writer changed the workspace first: pull, review preserved changes and retry.

A revision is durable workspace history. A share URL is delivery, not a revision. A private workspace URL is an authenticated preview, not proof that a public share exists.

Sandbox

A sandbox supplies execution. It can install dependencies, run a build or serve an app, but compute alone does not define what should remain available to readers. Grain's hosted cloud workspaces use E2B microVM sandboxes. Grain is not a bare sandbox provider; it keeps the output produced there.

How the pieces fit

1. You give a coding agent a concrete task, such as producing a release walkthrough from a changed codebase.
2. The agent writes the artifact files in a connected folder. Those files are the authored result.
3. The workspace keeps the files and gives the published result an address. If the result needs state, the current app templates use SQLite at /project/workspace/data.db.
4. A sandbox supplies runtime compute when the artifact needs to build, execute or run continuously.
5. Readers open the share, leave comments and return later. The agent can read those comments and revise the existing artifact instead of beginning from an empty session.

Static pages and full apps

Need	Static artifact	App artifact
Good fit	Write-ups, reports and walkthroughs	Dashboards, internal tools and automations
State	Files are enough	Current templates can use SQLite at data.db
Access	Can use public or password sharing; invited-person access is UI-specific	App-specific login is not a public setup contract in this guide
Background work	Usually none	Use bounded runtime commands/jobs; no public scheduler setup is documented

Authentication and access are separate

CLI login authenticates local Grain commands. MCP registration tells an agent how to start the local server; it does not contain credentials. An app’s login is an application-level user boundary. HTTP API tokens are workspace-bound credentials with explicit scopes. A share is an audience choice for readers. None of these should be substituted for another.

Names you will see

• Grain is the public product name.
• Workspace ID identifies the durable workspace. Keep it and pass it explicitly when a machine has more than one workspace.
• Operation ID identifies a long-running promotion or job. Poll it; do not create a duplicate when a response is lost.
• Share ID identifies an existing share for update or revoke. Do not derive one from a share URL.
• Runtime-ready means a promotion completed and the workspace can use the selected runtime. Pending or failed is not ready.

Frequently asked questions

What is an artifact in Grain?

It is the useful output an agent made, such as a page, report, walkthrough, app or dashboard.

Is a workspace the same as a sandbox?

No. The workspace is where the artifact stays. The sandbox is compute used to run code.

Does every artifact need a database?

No. Static pages can be files only. Current app templates use SQLite at /project/workspace/data.db when they need durable data. The control-plane Postgres database is an internal Grain service, not an app database you connect to through this API.

Does Grain include a coding agent?

No. Grain is agent-agnostic and does not sell or mark up model tokens. You bring your own CLI coding agent.