Reference

Getting a key

statice is not self-serve. Every call to the API carries an access key, keys are issued by hand, and there is no page anywhere that will mint you one. Email access@statice.run and ask, saying roughly what you want to publish.

statice key stores the key you were given in ~/.statice/key; it does not request one, and everything below assumes it is already set. The key is still not an account — see Two credentials.

Commands

Files

Everything under ~/.statice is 0600 inside a 0700 directory. STATICE_KEY and STATICE_TOKEN override the files, for machines with no durable home directory. STATICE_API points the CLI at a different API; it must be HTTPS, or plain HTTP on a loopback address only, since the key rides on every call.

Two credentials

The access key is admission: one per caller, on every API call, and handed out by a person at access@statice.run. The name token is possession: one per label, generated locally. The server stores only its SHA-256, which is what the claim sends; the token itself is sent over HTTPS with each update, check and retirement it authorizes, compared against that hash, and never written down server-side.

They are never merged. A key that also owned names would be an account, with every site linkable to every other and one leak losing all of them.

What gets published

The CLI walks the folder and admits files by extension. It prunes .git, node_modules and dot-directories — except a top-level .well-known — skips symlinks entirely, and drops CLAUDE.md and AGENTS.md at every depth: they are an admitted type, but they are written for an agent standing in the folder, never for the web.

Nothing leaves quietly. Every deploy names what the type table refused, and then, separately, what the walk dropped before the table saw it — each path beside the rule that dropped it, and a pruned tree named with a trailing slash and no count, because it is never opened.

Two things it does not do. It does not read .gitignore, or any other ignore file: what is in the folder is what is considered. And it drops dot-directories, not dot-files: a file like .env.local.json has an admitted extension and is published like any other. Source, JSON, sourcemaps and documents in admitted types all go up. statice --dry-run prints the exact list without sending anything, and the first deploy from a folder shows the same list before it asks.

Admitted: .html .htm .css .js .mjs .json .wasm .pck .data .map, the image set, the font set, the media set, plus .pdf .txt .xml .svg .webmanifest .vtt .md .obj.

Excluded, which is the more interesting half: .ts .tsx .jsx .yml .toml .sql .sh .py .pem .key .tfstate, and everything extensionless — except a fixed set of names directly under a top-level .well-known, which are admitted by name. That happens to stop a source tree being published — but it cannot stop a secret in an admitted type, and it was never a security control.

.map is admitted and flagged: every sourcemap is named back to you on every deploy in which it is new, because sourcemaps embed original source. Dropping .map from the table instead would break the production error reporting sourcemaps exist for.

Caching

The hash host can promise a year because the root is in the name. Named hosts get no-cache plus a strong ETag — so a match is a 304 with no read, and a deploy is live the instant it lands. Not stale-while-revalidate, and not a small max-age: a deployer refreshing mid-write would otherwise get a page that is half old and half new, because assets resolve against whichever record their own request caught.

Limits

Ranges and media

One range per request is honored; every other shape of the header gets the full 200. If-Range is enforced against the strong ETag, so a client resuming yesterday's download never gets today's bytes spliced onto it. Safari probes <video> with Range: bytes=0-1 and will not play without a 206 — which is why the media set works at all.

Path resolution

A path ending in / tries index.html then index.htm. A path whose directory form exists gets a 301. There is no 404.html, no SPA fallback and no extensionless lookup. If you need client-side routing, serve it from index.html and route in the browser.

One cookie jar

Every hash URL and every name is its own origin, so localStorage, IndexedDB and service workers are separate per site. Cookies are not: statice.app is not on the Public Suffix List, so a page on any *.statice.app host can set a cookie with domain=.statice.app that every other site under it receives. Nothing served here can prevent that. Do not put anything cookie-authenticated on a statice.app host.

When something looks broken

A plain redeploy of unchanged bytes answers from a single operation without checking a single file — which is the point, and also means it will not repair a file that has been taken down. statice --verify is what re-uploads everything. Reach for it, not for a plain redeploy.