# Deployments

> Immutable snapshots of static files, each with its own URL: properties, lifecycle, limits, public deploys and claiming, passwords, labels and origin tags.

Source: https://docs.shipstatic.com/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](https://docs.shipstatic.com/web), [CLI](https://docs.shipstatic.com/cli), [SDK](https://docs.shipstatic.com/sdk), [MCP](https://docs.shipstatic.com/mcp), [Action](https://docs.shipstatic.com/action), and [API](https://docs.shipstatic.com/api).

## Properties

| Property | Description |
|----------|-------------|
| `deployment` | Unique identifier — the deployment's hostname |
| `url` | Preview URL, immediately accessible |
| `files` | Number of files |
| `size` | Total size in bytes |
| `status` | Lifecycle state (see below) |
| `labels` | Mutable tags for organization |
| `password` | `true` if the deployment is password-protected |
| `via` | Origin tag — see [Origin tags](https://docs.shipstatic.com/deployments#origin-tags) below |
| `created` | Creation timestamp |
| `claim` | Claim URL — present only on response of public (unauthenticated) deploys |
| `expires` | Expiry as a unix timestamp in seconds. Set for deploys made without an account (3 days from creation) and for any deployment given a `ttl` |

## 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.

**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.** The platform analyzes your `index.html` for single-page app patterns (React Router, Vue Router, etc.) and configures client-side routing fallbacks automatically.

## 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.

| | Free | Pro | Team |
|---|---|---|---|
| Largest single file | 20 MB | 50 MB | 50 MB |
| Files per deployment | 500 | 1,000 | 1,000 |
| Total deployment size | 50 MB | 200 MB | 200 MB |

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](https://docs.shipstatic.com/plans).

Your own current limits are always available from `GET /limits` ([API](https://docs.shipstatic.com/api)),
`ship.getLimits()` ([SDK](https://docs.shipstatic.com/sdk)), and the Plan page in the console ([Web](https://docs.shipstatic.com/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](https://my.shipstatic.com) to transfer the deployment to your account.

```bash
$ 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](https://docs.shipstatic.com/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.

```bash
ship ./dist --password 'hunter2!'
```

## Labels

Labels organize and filter deployments. Each label is 3 to 25 lowercase alphanumeric characters with `.`, `-`, or `_` separators. Maximum 10 per deployment.

```
production
v1.0.3
staging.preview
```

## Origin tags

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

| Value | Origin |
|-------|--------|
| `web` | [Web](https://docs.shipstatic.com/web) console (drag-drop or upload) |
| `cli` | [CLI](https://docs.shipstatic.com/cli) |
| `sdk` | [SDK](https://docs.shipstatic.com/sdk) used directly |
| `mcp` | [MCP](https://docs.shipstatic.com/mcp) server (AI agents) |
| `git` | [Action](https://docs.shipstatic.com/action) (GitHub Actions) |
| `n8n` | n8n community node |
| `gpt` | The ChatGPT app |
| `vsc` | [VS Code](https://docs.shipstatic.com/vs-code) extension |
| `cld` | The Claude connectors directory |
| `crs` | The Cursor marketplace |
| `gmn` | [Gemini](https://docs.shipstatic.com/gemini) CLI extension |
| `api` | A call straight to the [API](https://docs.shipstatic.com/api) that named no origin |

## Operations

| Operation | Description |
|-----------|-------------|
| Upload | Create a new deployment from files |
| List | All deployments on your account |
| Get | Details of a specific deployment |
| Set | Update labels |
| Delete | Delete a deployment and its files |