Instant Sites

For project-level setup — enabling Instant Sites, setting a production subdomain, and configuring a custom domain — see Instant Sites and custom domains.

Command overview

Instant Sites has four CLI entry points:

Command	What it does
`cos deploy <folder>`	Upload a static site folder and create a preview deployment
`cos deploy list`	List recent Instant Sites deployments for the current project
`cos deploy promote <deployment-id>`	Move an existing deployment to the project’s production URL
`cos deploy config`	Show the project’s current Instant Sites production configuration

Before you deploy

Make sure you have:

signed in with cos login
initialized the folder as a Cosine project, or you know the --team and --project values you want to use
a directory that contains your built static site files, usually including index.html

If Cosine can detect the project from your repository, you usually do not need to pass --team or --project.

If the current folder is not set up as a Cosine project yet, cos deploy can guide you through setup. In an interactive terminal, it asks:

No Cosine project is configured. Run `cos project init` now? [Y/n]:

Press Enter to run project setup with the default answer. If the folder does not have a GitHub remote, Cosine can also prompt to create one with gh repo create, choose private or public visibility, commit the current project, push it, and then continue the deploy.

You can also run setup yourself before deploying:

cos project init

For most projects, Instant Sites is already enabled by default. If deploy requests fail with Instant Sites is not enabled for this project, open the dashboard for that project and go to Project Settings → Deployments, then turn on Enable Instant Sites.

The CLI deploy command uploads a directory. If you only have a single HTML file, put it in a folder first.

Deploy a site

Run cos deploy with the folder you want to publish:

cos deploy dist

You can also deploy a specific folder by path:

cos deploy ./apps/website/out

If you are already inside the built folder, you can also deploy the current directory:

cos deploy

When the deploy succeeds, Cosine shows:

a deployment ID
a preview URL
the current deployment status

If the preview is already live by the time the command finishes, the output is reported as a completed deployment. If the preview is still processing in a non-interactive environment, Cosine reports it as queued and gives you the deployment ID and preview URL so you can check again later.

What happens in the CLI

In an interactive terminal, the deploy flow stays open while the preview is being prepared.

You will see a live progress view for:

Create deployment archive
Upload archive
Publish preview

During Publish preview, the status updates as the deployment moves through preview processing until it becomes live.

If you also pass naming or promotion flags, Cosine adds extra steps after the preview is live:

Update production name
Assign custom preview name
Promote deployment

When the preview becomes live

When the preview is ready in an interactive terminal, Cosine prompts you to:

press Enter to open the preview URL in your browser
press q or Esc to finish without opening it

This browser prompt only appears in interactive terminals.

If you run cos deploy in CI, scripts, or any other non-interactive environment, Cosine does not wait for key input and does not try to open a browser window.

Preview URLs, custom preview names, and production URLs

Instant Sites uses three related concepts:

Name	Meaning
Preview URL	The deployment-specific URL created for every deploy
Custom preview name	An optional readable subdomain for one deployment
Production name	The stable project-level name used for the production URL

The preview URL is temporary and tied to one deployment. The production name belongs to the project and is what you promote deployments into.

Common workflows

Deploy a preview build

cos deploy dist

Use this when you want a quick live URL for a build artifact such as a docs site or frontend prototype.

Give one deployment a readable preview name

cos deploy --name marketing-site dist

This assigns a readable preview subdomain to that deployment once it is live.

Preview names must use lowercase letters, numbers, and dashes, and must be 64 characters or less.

Set the project’s production name

cos deploy --production-name docs-site dist

This updates the project’s production naming configuration and deploys the new preview.

Deploy and promote in one command

cos deploy --promote dist

If you want to set the production name at the same time:

cos deploy --production-name docs-site --promote dist

In an interactive terminal, Cosine waits for the preview to become live before it runs the promote step.

If the deployment is still processing in a non-interactive environment, Cosine reports that promotion has not been applied yet. You can then run cos deploy promote <deployment-id> later if you still want to move production to that deployment.

Check deployment status later

Use:

cos deploy list

This shows recent Instant Sites deployments for the current project, including:

deployment ID
status
created time
preview URL
custom preview name
whether it is live in production

Promote an existing deployment later

In Instant Sites, promote means taking one existing deployment and making it the project’s live production site.

Before promotion, a deployment only has its own preview URL. After promotion, the project’s stable production URL points to that deployment instead.

Use this when you have already reviewed a preview and want to switch the live site over without uploading a new build.

cos deploy promote dep_123

You can also set the production name during promotion:

cos deploy promote dep_123 --production-name docs-site

View or update production settings

Show the current Instant Sites configuration for the project:

cos deploy config

Update the production name without doing a new deploy:

cos deploy config --production-name docs-site

Build output expectations

cos deploy does not build your app for you. It uploads the folder you point it at.

Build the site first, then deploy the generated static output directory:

pnpm build
cos deploy dist

This works for plain HTML/CSS/JS and static builds from frameworks like React, Vue, Svelte, Astro, and Vite.

It does not run server-side code or SSR. If your framework emits a different folder name, deploy that directory instead.

If you include a 404.html file at the root of the deployed folder, Instant Sites can serve it as the custom 404 page for that site.

Troubleshooting

The source is a file, not a folder

The CLI deploy command requires a directory. If you pass a file path, Cosine returns:

deploy source must be a directory

Put the file in a folder and deploy the folder instead.

The deploy folder is empty

Cosine only uploads non-empty directories. Build the site first, then point cos deploy at the generated output folder.

The command says the deployment is still processing

That means the preview has been accepted but is not live yet.

In an interactive terminal, Cosine will keep updating the status until the preview is ready.

In a non-interactive environment, rerun:

cos deploy list

to check the latest status.

The browser did not open automatically

Cosine only offers the Enter-to-open prompt in interactive terminals.

You can always copy the preview URL from the CLI output and open it manually.

Cosine cannot detect the project

In an interactive terminal, run:

cos project init

If you already have the GitHub CLI installed and authenticated, this can create a GitHub repository for the folder, commit and push the current project, and save the Cosine project selection.

Pass the project explicitly:

cos deploy --team my-team --project my-project dist

A preview or production name is rejected

Preview and production names must:

use lowercase letters, numbers, and dashes only
be 64 characters or less

Examples:

valid: docs-site
valid: marketing-site-2
invalid: DocsSite
invalid: marketing_site