Deployments

A deployment is an immutable snapshot of static files. Once created, its contents never change.

Every deployment gets a unique name (e.g. happy-cat-abc1234) and an instant preview URL. On every response the deployment field carries the full hostname — happy-cat-abc1234.shipstatic.com — which is the form every interface shows and accepts.

Available via Web, CLI, SDK, MCP, Action, and API.

Properties

Status

pending → success → deleting
        → failed  → deleting

A deployment starts as pending during upload. On success, the preview URL goes live. Deletion is asynchronous from any terminal state — the status transitions to deleting while files are cleaned up.

Behaviors

Immutable. After creation, only labels can be modified. To change content, create a new deployment.

An index.html at the top. Every deployment needs an index.html at the top: it's the page visitors see first. A deploy without one, or with an empty one, is refused, and the refusal says what to do: publish the folder that holds your index.html when it sits one folder down (like dist/), put your main page at the top and name it index.html, or, to publish a file on its own, like an image or a PDF, add a small index.html that links to it.

Path optimization. When all files share a common root directory (e.g. dist/), the platform flattens it automatically — dist/index.html becomes index.html.

SPA detection. A deployment whose only page is an index.html with no content of its own (a container and a script, which is what React, Vue, Angular, Svelte and similar builds produce) is treated as a single-page app, and every path is routed to index.html automatically. Anything else is served as its files. The CLI, the SDK and the integrations ask for this on every deploy; through the API, send spa=true. If your app needs the fallback and is not detected, add the rewrite yourself in ship.json.

robots.txt and favicon.ico. If your site doesn't have a robots.txt at its root, we add one that lets every search engine crawl everything. If it doesn't have a favicon.ico at its root, we add ShipStatic's icon, which browsers show in the tab when your pages name no icon of their own. Both are real files in your deployment, so they count in files and size, but never against your file limits. If you upload your own, we use yours and add nothing.

Limits

What one deployment may carry. These bound a single publish — they are not account totals — and the API enforces them on every deploy, whichever interface you use.

Deploys made without an account use the Free limits. Scale is arranged directly and its limits are higher. What each plan is for is under Plans.

Your own current limits are always available from GET /limits (API), ship.getLimits() (SDK), and the Plan page in the console (Web). That answer reflects your plan and any adjustment made on your account, so prefer it to this table whenever the two could differ.

Public Deployments

Deploys without authentication go to the public account and expire 3 days from creation. The response includes a claim URL — visit it while signed in at my.shipstatic.com to transfer the deployment to your account.

$ npx -y @shipstatic/ship ./dist --json
{
  "deployment": "happy-cat-abc1234.shipstatic.com",
  "url": "https://happy-cat-abc1234.shipstatic.com",
  "claim": "https://my.shipstatic.com/claim/...",
  "expires": 1755302400
}

Once claimed, the deployment is yours and never expires. The claim URL then works for nobody else; opening it again yourself only shows you the deployment.

Until then, the claim URL is what transfers ownership, so anyone holding it can claim the deployment — share it the way you would a one-time invite rather than posting it somewhere public. Worth knowing if an agent prints one into a chat you keep around: the link stays usable for the same 3 days the deployment does. Claiming it yourself is what closes it.

The claim URL appears once, in the deploy response. The platform keeps only a hash of it, so nothing can show it again: whoever deploys on someone else's behalf, an agent included, hands it over straight away.

Custom domains, password rotation, and listing/management operations require an API Key. The deploy itself doesn't.

Password Protection

Deployments can be locked behind a password set at upload time. Visitors see an unlock page until they enter the correct value. Passwords are stored securely — ShipStatic cannot reveal or recover one, so keep it somewhere safe.

Length: 6 to 128 characters. There is no edit-in-place — to change or remove a password, redeploy.

ship ./dist --password 'hunter2!'

Labels

Labels organize deployments. A label is a word like production, or a key and a value split by one : like env:production. Each side is letters and numbers, with ., - or _ between them. A label is 3 to 63 characters, and a deployment can have up to 10.

production
v1.0.3
env:production
team:web

Labels are stored in lowercase, so Env:Prod becomes env:prod. A deployment can have more than one value for the same key. A deployment uploaded with a token also gets the token's labels, ahead of its own.

Origin tags

The via field records which interface created the deployment, useful for filtering listings by origin.

Operations