# Getting started

This walks you from zero to one published site in about 15 minutes. No prior StaticOwl knowledge assumed.

# Prerequisites

If you're integrating against a hosted StaticOwl CMS rather than running one, you don't need any of this — go to HTTP API and the @staticowl/mcp-client typed SDK.

# Install

git clone <repo>
cd cms
npm install
npm run build

This builds every package in the workspace (@staticowl/core, @staticowl/server, @staticowl/build, @staticowl/cli, @staticowl/mcp, @staticowl/ui, @staticowl/ui-next).

# Configure

Set the environment variables the server needs. For local dev, drop them in a .env at the repo root or export them in your shell:

# Engine connection — required
export GRAPHIQUITY_ENDPOINT=https://invariantdb.com   # was api.graphiquity.com pre-2026-06-02
export GRAPHIQUITY_API_KEY=gq_yourkey                # graph-level engine key

# Cognito — required for the admin UI auth flow
export USER_POOL_ID=us-east-1_xxxxxx
export USER_POOL_CLIENT_ID=yyyyyyyyy
export AWS_REGION=us-east-1

# Deploy target — defaults to static-paths
export STATICOWL_DEPLOY_TARGET=static-paths          # or 'github', 'manifest-pointer', 'both'
export STATICOWL_DEPLOYMENT_MODEL=new                # or 'legacy', 'dual'

# AI providers — optional but unlocks the AI features
export ANTHROPIC_API_KEY=sk-ant-xxxxx
export REPLICATE_API_TOKEN=r8_xxxxx

See operations.md for the full env var reference.

# Run the admin server

npm run cms -- serve --port 5000

This boots the Express admin server on port 5000, serving:

The MCP server is not mounted on this server. It's a separate, stdio-only process that talks to this HTTP API — launch it as a subprocess from your agent client. See MCP.

# First site

  1. Sign in at http://localhost:5000/admin/login.html (creates a Cognito-backed user; the first user becomes platform owner automatically)
  2. Create a site from the sites picker (POST /api/sites under the hood)
  3. Pick a starter kit based on your persona — developer, author, designer, or none. The starter seeds your site's graph with a content type or two and a default template.
  4. Add content — go to the Content tab, pick a type, hit "New".
  5. Save — the content node is written to the graph.
  6. Publish — hit the Publish button or POST /api/build. The site compiles to static files and (depending on STATICOWL_DEPLOY_TARGET) writes to S3 / a GitHub repo / the manifest layer.
  7. Visit the site — your bound public URL or the auto-provisioned <site>.staticowl.com preview.

# Verify it built

# Static-paths target → S3
aws s3 ls s3://staticowl-sites/<site-id>/dev/

# GitHub target → your repo
git -C /tmp/your-clone log --oneline | head

# Manifest-pointer target → check the deployment fact
curl http://localhost:5000/api/releases/replay?envId=dev \
  -H "Authorization: Bearer $TOKEN" -H "X-Site-Id: site:..."

# Where to go next

# Common gotchas