Core concepts

Interfold has a small, consistent model. Once these ideas click, the CLI and API read like plain English.

Accounts

An account is the workspace and billing boundary. Every site, file, function, cron job, and secret belongs to exactly one account. Users join accounts through membership; API keys are scoped to a single account with Read-only or Read/write access. Read/write includes all reads. See API authentication.

interfold accounts list
interfold accounts current

Buckets

A bucket is an account-owned collection of files. It works without hosting: store documents, source, assets, and data through the bucket Files API. A Site can attach to a bucket; creating a Site without a bucket creates one automatically.

Sites

A site attaches hosting and runtime behavior to one bucket, served at its own subdomain, https://<subdomain>.interfold.site. A Site interprets fixed bucket directories and owns its runtime resources:

A site has an access setting (PUBLIC or PRIVATE) that controls who can reach its static output. See Sites & access.

Files

Everything you publish is a file at a path. interfold files put creates or replaces a file; the path determines how it behaves:

• /web/index.html, /web/style.css, /web/logo.png — web files, served at /, /style.css, and /logo.png.
• /api/hello.ts — a function source, deployed as an endpoint.
• /cron/refresh.ts — a cron source, deployed as a scheduled handler.
• /data/state.json — data, written by handlers, never served publicly.

The path is the source of truth. Files under /web/ are served verbatim with the prefix omitted from hosted URLs. There is no runtime Markdown rendering or other transformation, and uploading is publishing. Because the prefix is omitted, /web/api/, /web/cron/, /web/data/, and /web/_interfold/ are rejected rather than colliding with reserved hosted routes.

Access

Bucket API access always requires account authentication. A Site’s PUBLIC or PRIVATE setting controls anonymous access only to hosted /web/ files. A deployed /api/<name> runtime is anonymously callable for either Site setting; the handler must enforce any function-specific authorization. There are no per-file overrides. Source, cron, data, database and migration assets, and files outside /web/ are never served directly; a function can still return data deliberately.

See Sites & access.

Functions

A function is a single TypeScript file at /api/<name>.ts that exports a handler. It runs on request and returns a standard Response. Functions get a ctx object with access to persistent data and site secrets.

export async function handler(req: Request, ctx: InterfoldContext) {
  return Response.json({ ok: true, siteId: ctx.siteId })
}

See Functions.

Cron Jobs

A cron job is a TypeScript file at /cron/<name>.ts with a static UTC schedule and a named handler. It runs in the same isolated environment as a function, with access to site data and secrets but no browser request or user session.

See Cron Jobs.

Storage & secrets

• Databases (ctx.db) store structured application data and support SQL queries and concurrent updates. See Databases.
• Data files (ctx.data) store text, JSON, and JSONL under /data/. See Data files.
• Secrets are named values set out-of-band and read at runtime via ctx.secrets.get(...). Secret values never appear in source or logs. See Secrets.