Deployments

A deployment is an immutable, versioned snapshot of your project served from Tebstack's edge network. Every teb deploy produces a fresh, atomic build you can preview, promote, or roll back to in seconds.

Overview#

When you run the CLI, Tebstack uploads your source, runs your build in an isolated container, and distributes the output to every edge region. Each deployment gets a unique, permanent URL — so a deploy is never overwritten, only superseded. You can read more in the Edge runtime guide or jump straight to the platform status page.

New to Tebstack?

Run teb init in any project directory to generate a starter config and link it to your team. The CLI walks you through framework detection.

The deployment lifecycle#

Every deployment moves through five states. The CLI streams each transition to your terminal:

Queued — source is uploaded and a build slot is reserved.
Building — your install and build commands run in an isolated container.
Uploading — build output is hashed and pushed to edge storage.
Ready — the deployment is live at its unique preview URL.
Promoted — assigned to a production or custom domain alias.

Creating a deployment#

From the root of a linked project, deploy the current directory:

$ teb deploy --prod↑ Uploading 248 files (1.2 MB)✓ Build completed in 14.8s✓ Assigned to production · acme.tebstack.app→ https://acme-3f9a2b.tebstack.app

The first positional argument can also be an explicit path. Common flags are shown below — run teb deploy --help for the full list.

Flag	Description
`--prod`	Promote this build to the production alias once it is ready.
`--env <name>`	Inject variables from the named environment (e.g. `preview`).
`--build-env KEY=val`	Pass a one-off variable to the build step only.
`--prebuilt`	Skip the remote build and upload a local output directory.
`--yes`	Skip interactive confirmation prompts (useful in CI).

Linking is required

A directory must be linked to a project before it can deploy. If you see Error: not linked, run teb link first.

Configuring builds#

Build behavior is controlled by teb.config.ts at your project root. The highlighted lines below are the two fields most teams customize:

teb.config.tsts

import { defineConfig } from "@tebstack/cli";export default defineConfig({  framework: "auto",  buildCommand: "pnpm build",  outputDirectory: "dist",  regions: ["iad1", "fra1", "sin1"],  env: {    API_URL: process.env.API_URL ?? "https://api.acme.dev",  },});

Build options#

Each field maps to a column in the deployment record:

Option	Type	Default
`framework`	string	`"auto"`
`buildCommand`	string	detected
`outputDirectory`	string	detected
`regions`	string[]	`["iad1"]`

Atomic & immutable#

A deployment is never mutated after it goes live. Promoting simply re-points an alias — so rollbacks are instant and risk-free.
— Tebstack platform guarantees

Figure 1 — the production alias points at the newest “Ready” deployment; older builds stay reachable at their immutable URLs.

Promoting & rolling back#

Because every build is retained, rolling back is a metadata change — no rebuild required. Promote any past deployment by its URL or ID:

$ teb rollback dpl_3f9a2b --prod✓ production now points to dpl_3f9a2b (built 4h ago)

Production aliases are shared

Promoting affects everyone hitting your production domain immediately. In CI, gate promotions behind a manual approval step.

Destructive: teb deployment rm

Deleting a deployment is permanent and breaks any links pointing at its immutable URL. There is no undo. Prefer teb rollback over deletion.

Deployments API#

Everything the CLI does is available over HTTPS. All requests are authenticated with a bearer token — see Authentication. The base URL is https://api.tebstack.app/v2.

Create a deployment#

POST/v2/deployments

Creates and queues a new deployment for the given project.

Parameter	Type	Description
`project` required	string	The project ID or slug to deploy into.
`files` required	File[]	Array of file descriptors with SHA-1 hashes and sizes.
`target`	enum default: `"preview"`	Either `"preview"` or `"production"`.
`meta`	object	Arbitrary key/value metadata attached to the deployment.

create-deployment.shbash

$ curl -X POST https://api.tebstack.app/v2/deployments \  -H "Authorization: Bearer $TEB_TOKEN" \  -H "Content-Type: application/json" \  -d '{ "project": "acme-web", "target": "production" }'

Retrieve a deployment#

GET/v2/deployments/:id

Returns the full deployment record, including its current state and edge regions.

200 OKjson

{  "id": "dpl_3f9a2b",  "url": "acme-3f9a2b.tebstack.app",  "target": "production",  "state": "READY",  "regions": ["iad1", "fra1", "sin1"],  "createdAt": 1717372800000}

Troubleshooting#

Common failures and what they mean:

Symptom	Likely cause	Fix
Build exits with `code 127`	A command isn't on PATH inside the build container.	Pin it in `buildCommand` or add a `devDependency`.
`Error: not linked`	Directory isn't associated with a project.	Run `teb link`.
Stuck in “Queued”	Team build concurrency limit reached.	Wait, or upgrade the plan's concurrency.

Still stuck? Stream live build logs with teb logs --follow, or reach the team in the community Discord.

Last updated June 3, 2026Edit this page