# Cogny Sites: a briefing for your coding agent Paste this into Claude Code, Codex or Cursor when it works on a repo that Cogny Sites hosts: how builds and deploys run, how environment variables and secrets reach the site, and how the agent checks deploy status itself. **Author:** Cogny Team **Published:** 2026-11-03 **Updated:** 2026-11-03 **Canonical:** https://cogny.com/docs/cogny-sites-for-agents This page is written for an AI coding agent. If your site is hosted on Cogny Sites, tell your agent: **"Read https://cogny.com/sites.md before you change anything about hosting, deploys or environment variables."** Or paste this page into the chat. ## The short version - This repository is deployed by **Cogny Sites**, not Vercel, Netlify or another host. Don't suggest "add it in Vercel" or add host-specific config files (`vercel.json`, `netlify.toml`); they do nothing here. - **Production deploys on every push to the production branch** (usually `main`). Every pull request gets its own **preview deployment**, and its address is posted on the pull request. - **Environment variables are set in Cogny**, not in the repo: Settings → Cogny Code → Sites → the site → Environment Variables. Owners and admins can change them. - **A changed variable reaches the site only on the next deploy.** Saving doesn't redeploy. Push a commit or press **Deploy** on the site's page. - You can **check the deploy and which variables are set yourself** with the Cogny CLI: `list_sites` and `get_site`, below. Values are never shown, only names. ## How a build runs 1. Cogny clones the production branch (or the pull request's branch for a preview). 2. It runs `npm ci && npm run build` on Node (the version is set per site, Node 20 by default), in the site's root directory if one is set. Your environment variables are present during this step. 3. It packages the output in a container. If the repo has its own `Dockerfile`, that is used. Otherwise Cogny generates one for the framework: - **Next.js**: `npm start` on port 3000, with production dependencies and the `.next` output. - **Remix**: `npm start` on port 3000, with `build/`. - **Astro (server output)**: `node ./dist/server/entry.mjs` on port 3000. - **Static sites**: the first of `dist/`, `build/`, `out/` or `public/` is served as static files, with `index.html` as the fallback for client-side routes. 4. The container goes live and the site's address switches to it. A failed build never replaces the live site; the previous deployment keeps serving. What this means for code: - The app must listen on the `PORT` environment variable (3000). `next start` does by default. - The filesystem is not persistent. Don't write uploads or state to disk; use a database or object storage. - The site scales to zero when idle unless the site is set to Always Warm, so the first request after a quiet period can be slower. Don't rely on in-memory state between requests. - If your build needs files outside the generated Dockerfile's copy list (a custom server, extra folders), add your own `Dockerfile`. ## Environment variables and secrets There are two kinds, both set on the site in Cogny: - **Variables** are available during the build and to the running site. - **Secrets** are kept out of Cogny's database and given only to the running site, never to the build. Use them for API keys, signing secrets and passwords. The lock icon next to a saved variable turns it into a secret. Rules worth knowing: - **Browser-visible variables must be plain variables.** `NEXT_PUBLIC_`, `VITE_`, `PUBLIC_`, `REACT_APP_`, `EXPO_PUBLIC_`, `NUXT_PUBLIC_` and `GATSBY_` values are compiled into the JavaScript at build time. They can't be secrets, and a change needs a new build (a deploy), not just a restart. - **Server-only values** (`STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, database URLs) should be secrets. - Read them in code with `process.env.NAME` as usual. Don't commit `.env` files with real values; the repo doesn't need them for Cogny Sites. - The values themselves never come back out of Cogny, not to the dashboard and not to an agent. To check that a value is right, test the behaviour on the live site. ## Check the site from your agent The Cogny CLI reaches the workspace the site belongs to. You need an API key for **that** workspace: ask its owner or an admin (Settings → Data & Integrations → Connect AI Clients). Don't run `cogny init`; it signs up a new free workspace, which won't see this site. Then: ```bash npx @cogny/cli login --api-key # or export COGNY_API_KEY= for one shell npx @cogny/cli tools call list_sites npx @cogny/cli tools call get_site --input '{"site":"owner/repo"}' ``` The same tools are on Cogny's MCP server (`https://app.cogny.com/mcp`) if your agent connects that way. - **`list_sites`**: each site's repository and branch, its address, the live deployment (commit and time), and whether a newer production build is running or failed. - **`get_site`**: every variable and secret by name, whether the **running** site has it, and a note when something needs attention: saved but waiting for a deploy, left over from an earlier deploy, a newer secret version not live yet, a credential stored as a plain variable, or an empty value. Plus the recent production and preview deployments with their build errors. `site` takes the site id, the repository (`owner/repo`) or the domain, and can be left out when the workspace has one site. So "is `STRIPE_SECRET_KEY` set on the live site?" is one `get_site` call. If it says *saved in Cogny but not on the running site yet*, the fix is a deploy, not a new value. The agent can't change variables, add secrets or start a deploy through these tools. Those stay with an owner or admin in Cogny, so secret values don't pass through a chat. ## Domains - A custom domain is connected on the site in Cogny (Domain Configuration). With Cloudflare connected, Cogny writes the DNS records itself; otherwise it shows the records to add. - When both `example.com` and `www.example.com` are connected, one redirects to the other. **Point webhooks (Stripe, GitHub, anything that POSTs) at the address that doesn't redirect.** Most webhook senders treat a redirect as a failed delivery. `curl -s -o /dev/null -w "%{http_code} %{redirect_url}" -X POST https:///` shows which one it is. - Cloudflare's proxy (orange cloud) must be off for the site's records, or visitors get a redirect loop and the certificate can't renew. ## When something is wrong - **Build failed**: `get_site` shows the error. Fix it in a pull request; the preview build tells you whether it works before it reaches production. Cogny's coding agent can also fix failed builds on its own pull requests (Settings → Cogny Code → Fix Builds). - **A feature says it isn't configured on the live site**: run `get_site`. Either the variable is missing, it's waiting for a deploy, or it is a build-time variable that was added after the live build. - **Anything you can't see from here**: file it with the Cogny CLI (`npx @cogny/cli tools call contact_support --input '{"subject":"...","message":"..."}'`) and the Cogny team answers in the same thread. --- In this section: - Set Up Cogny Cloud for Success: https://cogny.com/docs/cloud-setup-guide - Before Your Onboarding: Checklist and Wizard: https://cogny.com/docs/cloud-onboarding-checklist - Connect Your Data Sources: https://cogny.com/docs/connect-your-data-sources - Context and Growth Strategy: https://cogny.com/docs/context-and-growth-strategy - Core Metrics: https://cogny.com/docs/core-metrics - Reports and Templates: https://cogny.com/docs/reports-and-templates - Tickets and Approvals: https://cogny.com/docs/tickets-and-approvals - Automations and Content Loops: https://cogny.com/docs/automations-and-content-loops - Connect Your Own App to Cogny Automations: https://cogny.com/docs/connect-your-own-app-to-automations - Coding Agent, GitHub and Cogny Sites: https://cogny.com/docs/coding-agent-and-cogny-sites - **Cogny Sites: a briefing for your coding agent** (this page): https://cogny.com/docs/cogny-sites-for-agents - Use Cogny from Your Own Agent: https://cogny.com/docs/bring-your-own-agent - Credits and Plans: https://cogny.com/docs/credits-and-plans - Buying Guide for Agents: https://cogny.com/docs/buying-guide - Team, Governance and Privacy: https://cogny.com/docs/team-governance-and-privacy - Cogny Cloud FAQ: https://cogny.com/docs/cloud-faq Source page: https://cogny.com/docs/cogny-sites-for-agents All documentation: https://cogny.com/docs Cogny for agents: https://cogny.com/llms.txt