Publish your first site
By the end of this page you will have a static site live at your-slug.edge.deca-dev.com, and you will have seen it on a preview URL before any visitor could reach it. The hosts for this environment are in Environments and domains.
There are three ways to work, and this tutorial shows them at every step:
- With an agent — you describe what you want; a coding agent or DECA Agent calls the MCP tools. This is how most sites get published.
- With the CLI — you run
edgein a terminal. Install it once with Install the CLI. - With the API — you make the HTTP calls yourself, from a script or the terminal.
They are the same operations. Each MCP tool and its HTTP route run the same handler with the same permission check, and the CLI calls those routes for you, so you can start in one and finish in the other.
Before you start
Working with an agent, that means the agent is connected to the Edge MCP server — see Connect your agent if you have not done that yet. Working with the CLI, that means edge is installed and you have signed in (edge login). Working directly with the API, it means a bearer token for https://api.edge.deca-dev.com.
Your organization comes from the token and is never passed. If you belong to more than one workspace you may name one; otherwise Edge uses your organization's default workspace.
You also need a folder of files to publish with an index.html at its top level. This tutorial assumes ./public.
1. Pick a name
The slug decides your URL, so check it is free first. mcp, api, www, preview and ip are reserved and never available.
Check whether the slug "acme-marketing" is available on Edge.edge distributions slug-check acme-marketingcurl -s https://api.edge.deca-dev.com/v1/slugs/acme-marketing \
-H "Authorization: Bearer $EDGE_TOKEN"Either way the answer is the same:
{ "slug": "acme-marketing", "available": true }The agent runs edge_slug_check. Checking does not reserve the name, so a slug can still be taken between your check and your create.
2. Create the distribution
A distribution is the site itself — the name, the settings, and the URL. It persists; deployments come and go inside it.
Create a static distribution on Edge with the slug "acme-marketing",
using the static-site template.edge distributions create --slug acme-marketing --template static-sitecurl -s -X POST https://api.edge.deca-dev.com/v1/distributions \
-H "Authorization: Bearer $EDGE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"slug": "acme-marketing",
"distribution_type": "static",
"template": "static-site"
}'{
"id": "d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38",
"slug": "acme-marketing",
"live_deployment_id": null,
…
}static-site is the template for ordinary HTML pages. The others are embed-script and strict-security. The new distribution's type is site unless you set another one — see Distribution types. The agent runs edge_distribution_create.
Keep that id — everything below uses it. If you are working with an agent it will track the id for you; ask for it if you want to follow along.
The response also contains a deployment id. Ignore it.
Creating a distribution makes a bookkeeping deployment row with no files attached and no work queued. Committing it does nothing and will confuse you. The deployment you care about is the one created in the next step.
A well-behaved agent knows this. If yours commits the wrong id and nothing happens, this is why.
3. Open a deployment and upload your files
A deployment is one version of the site's contents.
Create a new deployment on the acme-marketing distribution and upload
the contents of ./public to it.edge link --distribution acme-marketing --dir public
edge deploy# 1. open the deployment
curl -s -X POST \
https://api.edge.deca-dev.com/v1/distributions/d3f7a1c4-90b2-4e6a-8f15-6c2b7e0a9d38/deployments \
-H "Authorization: Bearer $EDGE_TOKEN"
# 2. build the archive from INSIDE the folder, then upload it
COPYFILE_DISABLE=1 tar -czf ../bundle.tar.gz -C ./public .
curl -s -X PUT --upload-file ../bundle.tar.gz "$UPLOAD_URL"Opening the deployment returns its id and a presigned upload_url:
{
"id": "01M2QB6JJJS99B7B09VZJ8RST2",
"status": "pending",
"upload_url": "https://deca-edge-uploads-….s3.ap-northeast-1.amazonaws.com/…?X-Amz-Algorithm=AWS4-HMAC-SHA256&…"
}The agent runs edge_deployment_create and then PUTs the archive to that URL. The CLI's edge deploy packs the folder, creates the deployment, uploads, commits, and waits for the preview — so with the CLI you can skip the separate commit and poll steps below. The upload URL points at S3, is valid for one hour, and is not inspected by the firewall in front of the MCP server. Size caps and what to do when a file does not fit an inline write are in Upload content.
It must be a gzipped tar with files at the root
Edge reads .tar.gz only — a .zip uploads happily and then fails during processing. And the archive root must be the site files themselves, so index.html sits at the top of the tarball rather than under public/. That is what -C ./public . achieves. edge deploy builds that archive for you.
4. Commit it
Committing hands the bundle to a worker, which unpacks it and publishes a preview. This does not touch your live site — and at this point you do not have one yet.
Commit that deployment.# Already done by edge deploy in step 3. To commit a pending deployment by hand:
edge deployments commit 01M2QB6JJJS99B7B09VZJ8RST2curl -s -X POST \
https://api.edge.deca-dev.com/v1/deployments/01M2QB6JJJS99B7B09VZJ8RST2/commit \
-H "Authorization: Bearer $EDGE_TOKEN"Use the deployment id from step 3, not the one from step 2. The agent runs edge_deployment_commit.
5. Wait for it to be ready
Poll that deployment until it is ready, then give me the preview URL.# edge deploy already waited. To check by hand:
edge deployments get 01M2QB6JJJS99B7B09VZJ8RST2curl -s https://api.edge.deca-dev.com/v1/deployments/01M2QB6JJJS99B7B09VZJ8RST2 \
-H "Authorization: Bearer $EDGE_TOKEN"{
"id": "01M2QB6JJJS99B7B09VZJ8RST2",
"status": "ready",
"preview_published": true,
"preview_url": "https://01m2qb6jjjs99b7b09vzj8rst2.preview.edge.deca-dev.com"
}Wait for status: ready and preview_published: true. If status becomes failed, the response explains why; fix the bundle and start again from step 3. The agent runs edge_deployment_get.
You can also watch this on the Deployments page in the console at https://app.edge.deca-dev.com/edge/{workspaceId}/deployments.
Give the preview a moment
preview_published: true means Edge has written the preview pointer, not that every edge location has picked it up yet. For the first few seconds the preview URL can still return 404, and individual pages can come up slightly apart. If that happens, wait and reload rather than re-committing — the deployment is fine.
6. Look at the preview
Open the preview_url in a browser. This is your site, served exactly as it will be served live, on a URL nobody else has.
Check it yourself, properly. This is the step that makes promoting safe, and it is the one step an agent cannot do for you.
7. Promote
The preview looks right. Promote it.edge deployments promote 01M2QB6JJJS99B7B09VZJ8RST2curl -s -X POST \
https://api.edge.deca-dev.com/v1/deployments/01M2QB6JJJS99B7B09VZJ8RST2/promote \
-H "Authorization: Bearer $EDGE_TOKEN"This is the step that moves live traffic. Your site is now at https://acme-marketing.edge.deca-dev.com. The agent runs edge_deployment_promote.
If it turns out to be wrong, you can put the previous deployment back — see Patch, promote, and roll back.
What you built
- A distribution,
acme-marketing, which owns the URL and outlives any single deployment. - A deployment inside it, previewed and then promoted to live.
Next
- Install the CLI — sign in and publish from a terminal
- Deployment lifecycle — why commit and promote are separate
- Add an endpoint — run your own code on
/_api, or serve a data object / proxy a backend - Patch, promote, and roll back — shipping a second version, and undoing it
- Attach a custom domain — serving it on your own hostname
- Read analytics and conversions — understand what visitors do next
- Upload content — inline writes, bundles, and files that exceed the cap
- Limits