Data & Privacy
Understand where Grain artifact files live, how local and hosted workspaces differ, what each sharing mode exposes and how export works.
Grain keeps artifact files in the workspace and lets you pull them back through the CLI. You can use local workspaces in the desktop app or hosted cloud workspaces on E2B, then control audience access explicitly. The current CLI and MCP creation surface supports public and password-protected shares; named-person access may exist in product UI but is not a CLI contract.
Deployment choices
| Choice | Where it runs | What remains true |
|---|---|---|
| Local workspace | Through the desktop app | Artifact files remain workspace files and can be exported. |
| Hosted cloud workspace | On E2B | Artifact files remain workspace files and can be exported. |
What lives in a workspace
Artifact files live in the workspace and can be pulled through the CLI. The same file model applies to local workspaces in the desktop app and hosted cloud workspaces on E2B.
Sharing modes
| Mode | Who can reach it | Use when |
|---|---|---|
| Public link | Anyone who has the link | The artifact is intended for an open or broadly shareable audience. |
| Password-protected link | Anyone who has both the link and password | You need a simple shared secret around the artifact. |
| Invited people only | Product/UI capability where available | Use the product’s named-audience flow; no public CLI flag is documented for it. |
Export artifact files
grain pull [--force]The pull command receives remote changes into the linked local folder while preserving local work during normal reconciliation. Its only flag is --force. Expected output is pulled <n> remote change(s), deleted <n> local path(s), preserved <n> local change(s). An unknown option reports Unknown pull option: <option>. Usage: grain pull [--force]. If another sync client holds the workspace, the command reports that the workspace lease is active and tells you to stop that client or wait for its lease to expire.
Platform boundaries
The Grain desktop app runs on macOS, Windows and Linux. Hosted runtime workspaces use E2B microVM compute. These platform boundaries do not change where artifact files live.
Limits that affect design
| Area | Current boundary |
|---|---|
| Single HTML artifact through MCP/CLI artifact flow | HTML input is at most 256 KiB of UTF-8 |
| Managed content synchronization | The service advertises limits for file count, individual file size and revision bytes; inspect the workspace capability response rather than assuming a larger upload is safe |
| Runtime jobs | Default 15 minutes, maximum 1 hour, output capped at 1 MiB; records are local to the current CLI profile/host |
| SQL API | 512 KiB request body, 256 KiB SQL text, 120-second execution timeout, 16 MiB output cap, 1,000-row default and 100,000-row maximum for all-mode reads |
| Front Door | 64 argv entries, 1–60 second command timeout, 1 MiB command output, 100 MiB direct upload, two concurrent commands per token |
For the exact HTTP schemas, rate limits and error responses, use the external API contract. Limits are implementation boundaries, not a promise that a large artifact will be accepted by every surface.
Copies, revocation and export
Pulling a workspace retrieves remote file changes into a linked local folder; checkpoint history is the durable record. A share grants reader access to the published artifact, not to your CLI credentials. Revoking or disabling a share prevents future access through that share but cannot retract files someone already downloaded or copied.
Store API, Front Door and CLI credentials as secrets. Do not put them in an artifact, URL, MCP config, browser bundle, shell history or issue. API credentials are workspace-bound and scopes are intentionally narrower than a user session; see HTTP API for the credential matrix.
An app connected through Remote MCP reaches only the one workspace you approved, as you, while you keep builder access there. Grain stores the app's name and client ID, the workspace, and when the connection was made and last used. Its tokens are stored only as hashes. See and disconnect your apps at Connected apps. Disconnecting takes effect on the app's next request, but it can't undo changes the app already made in the workspace.
Frequently asked questions
Where do Grain artifact files live?
They live in the workspace and can be pulled back through the CLI.
Can anyone open a public share made with Grain?
Anyone with the link can reach it. Use password protection or the product’s named-audience flow for a narrower audience.
How do I export Grain workspace files?
Use the pull command from a linked local folder. It receives remote changes and normally preserves local work during reconciliation.
Does Grain run only in the cloud?
No. It supports local workspaces through the desktop app on macOS, Windows and Linux, and hosted cloud workspaces on E2B.