SiteOps Installation Guide

1. Preparation

Prepare the following before starting the installation.

Information to have on hand

Directory layout

The dedicated SiteOps folder can be created anywhere. It is fully independent of the existing site's folder, and the single placement constraint is to keep it out of the existing site's project. The commands below assume the distribution file is placed as follows.

work/                    ← any working folder (location is up to you)
├─ vendor/
│   └─ siteops.tgz       ← place the received distribution file under this name
└─ company-siteops/      ← the dedicated SiteOps folder you will create next

2. Setup

Create the dedicated SiteOps project. Run the commands in the working folder that holds the distribution file (vendor/), separate from the existing site's folder.

Verifying the distribution file

Compare the output of the following command against the SHA-512 value listed in the release.

shasum -a 512 vendor/siteops.tgz
# Windows (PowerShell) — paste the value from the release notes to get True/False:
(Get-FileHash vendor\siteops.tgz -Algorithm SHA512).Hash -eq "<SHA-512 from the release notes>"

Running setup

mkdir company-siteops
cd company-siteops
npm init -y
npm install ../vendor/siteops.tgz
npx siteops setup .

# In non-interactive environments, pass the two values as arguments
npx siteops setup . --yes --name "Example Inc." --admin-email admin@example.com

Files created in the dedicated SiteOps project

3. Deployment

Place the SiteOps runtime (Worker, D1, R2, and the admin console) on the company Cloudflare account. Run the command in the dedicated SiteOps folder (company-siteops/).

# Run in: company-siteops/
npm run siteops:deploy

On success, the command prints SiteOps deployed, the Administration URL, and the site data initialization result. Once initialization completes, the public API is immediately available. Open the printed URL (/login on the SiteOps URL) and confirm that the saved administrator token signs you in.

If the process stops partway, npm run siteops:status shows the current progress and the next command to run.

4. Connecting the existing site

SiteOps and the existing site share no code; they connect over the public API. Proceed in this order: fetch the connection details, register the public URL, then implement the existing-site side.

1. Fetch the connection detailsnpx siteops website manifest --json returns the SiteOps URL, the SiteOps ID ({siteKey} in API paths), and the URLs of the article, image, and form APIs. Only public information reaches the browser.
2. Register the public URL and publishing modeRegister with npx siteops connect live --origin, then run npm run siteops:deploy again to apply it. There are three modes: live for SSR and dynamic sites that render at request time, webhook for static sites that generate HTML at build time, and manual for workflows with an approval step (publishing mode details). For staging environments without a build hook, or during migration, start with manual and switch later by rerunning connect webhook and redeploying. Staging URLs such as http://127.0.0.1:8788 can also be registered. On success, the publishing mode and allowed origins are printed.
3. Implement in the existing siteWire the public API below into the existing site's data fetching and forms. After the implementation, deploy the existing site with your usual procedure and continue to "5. Verification".

# Run in: company-siteops/
npx siteops website manifest --json                             # Step 1
npx siteops connect live --origin "https://www.example.com"     # Step 2
npx siteops doctor                                              # Configuration check (optional)
npm run siteops:deploy                                          # Applies step 2
# Step 3: implement the code below → deploy the existing site with your usual procedure
npm run siteops:verify

Replace https://www.example.com with the actual public URL. See article publishing modes for static sites, and mail connection when using email.

Public API endpoints

website manifest --json returns this list expanded to the actual URLs. It reaches published data and form intake without an admin token.

Default resources available right after setup

The following content types and forms are provided from the start. Fields can be added and changed in the admin console.

Article entry structure

The list returns {entries: [...]} and the detail returns {entry: {...}}. In the default editor, the body is stored as plain text (paragraphs separated by blank lines), so the site side converts it to HTML.

{
  "entries": [
    {
      "slug": "sakura-no-ie-open-house",
      "publishedAt": "2026-07-17T03:25:00.000Z",
      "updatedAt": "2026-07-17T03:25:00.000Z",
      "data": {
        "title": "Open house at the new model home",
        "displayDate": "2026-07-20",
        "category": "Events",
        "excerpt": "Summary shown in lists and search results",
        "body": "The body is returned as plain text.\n\nParagraphs are separated by blank lines.",
        "seoTitle": "SEO title (optional)",
        "seoDescription": "SEO description (optional)"
      }
    }
  ]
}

Implementing the article list and detail

Fetch the public API on the server side (SSR or the build process) and emit title, meta description, canonical, and structured data into the existing site's HTML. "news" is a content type (an ID for the kind of article); match it to the article settings in the admin console.

const SITEOPS_URL = "https://siteops-xxxxx.workers.dev"; // SITEOPS_URL from the manifest
const SITE_KEY = "main";                                  // SITEOPS_SITE_KEY from the manifest
const api = SITEOPS_URL + "/api/public/sites/" + SITE_KEY;

const list = await fetch(api + "/content/news/entries");
const { entries } = await list.json();

const detail = await fetch(api + "/content/news/entries/" + slug);
if (detail.status === 404) {
  // connect to the existing site's 404 handling
}
const { entry } = await detail.json();

Implementing the contact form

The form posts directly from the browser to the public API. Allowed-origin validation, rate limiting, size limits, and Turnstile verification run on the SiteOps side. contact is a form ID created in the admin console, and each JSON key matches an accepted field key. For creating the Turnstile widget and registering the secret key, see form security settings.

const response = await fetch(api + "/forms/contact/submissions", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name,
    email,
    message,
    turnstileToken // when form protection is Turnstile; omit when protection is none
  })
});

const result = await response.json();
if (!response.ok || result.accepted !== true) {
  throw new Error(result.error || "inquiry_submission_failed");
}

1. Read the form security settingsFetch the Turnstile public key and action from GET .../forms/security and pass them to the widget.
2. Post directly to the public APISiteOps validates the allowed origin, size, and Turnstile, then saves the submission to the inquiry list.
3. Show completion from the stored resultTreat accepted: true as a completed intake. Email notification results come back separately in the delivery field of the response.

Allowed-origin validation applies to browser submissions (requests with an Origin header). Server-to-server requests without an Origin header fall outside this validation; the actual bot countermeasure is Turnstile.

5. Verification

Before going live, check the SiteOps runtime, the existing site, the forms, and mail (if configured).

npx siteops doctor --remote
npm run siteops:verify
npx siteops backup create
npx siteops backup verify backups/<created directory>

backup create prints the destination (backups/<timestamp> by default); pass that value to backup verify.

Example commands for the checklist

# Drafts stay off the public API (an unpublished slug returns 404)
curl -i {SITEOPS_URL}/api/public/sites/{siteKey}/content/news/entries/draft-slug

# Browser submissions from a non-allowed origin are rejected (403)
curl -i -H "Origin: https://evil.example.com" {SITEOPS_URL}/api/public/sites/{siteKey}/forms/security

Output of a successful siteops verify

PASS  runtime          SiteOps本体へ接続できました (312 ms)。
PASS  website          公開APIが https://www.example.com からの接続を許可しています(フォーム保護: turnstile)。ページ表示とフォームは既存サイト側で確認します。

The CLI currently reports in Japanese. A single FAIL stops the run with exit code 1 and prints the location of the cause and the next action.

Mail connection

The basic setup stores form inquiries in the admin console. Connect a sending service at the stage where you use internal notifications, acknowledgment emails, or replies from the admin console.

npx siteops mail setup disabled
npx siteops deploy

npx siteops cloudflare connect \
  --from-email no-reply@example.com \
  --from-name "Example Company" \
  --reply-to contact@example.com \
  --notification-emails team@example.com \
  --forms-only

npx siteops cloudflare connect \
  --from-email no-reply@example.com \
  --from-name "Example Company" \
  --reply-to contact@example.com \
  --notification-emails team@example.com \
  --addresses contact@example.com,support@example.com

npx siteops mail setup sendgrid \
  --from-email no-reply@example.com \
  --from-name "Example Company" \
  --reply-to contact@example.com
npx siteops secret set SITEOPS_SENDGRID_API_KEY
npx siteops deploy

npx siteops mail setup ses \
  --from-email no-reply@example.com \
  --from-name "Example Company" \
  --reply-to contact@example.com \
  --region ap-northeast-1
npx siteops secret set SITEOPS_AWS_ACCESS_KEY_ID
npx siteops secret set SITEOPS_AWS_SECRET_ACCESS_KEY
npx siteops deploy

npx siteops mail setup agentic-inbox \
  --from-email support@example.com \
  --from-name "Example Company" \
  --base-url https://inbox.example.com \
  --mailbox support@example.com
npx siteops secret set SITEOPS_AGENTIC_INBOX_ACCESS_CLIENT_ID
npx siteops secret set SITEOPS_AGENTIC_INBOX_ACCESS_CLIENT_SECRET
npx siteops deploy

Troubleshooting

Installation can resume from any stage.