Sheet 00 · Start-up procedure

Get Synthonic running.

synthonic init scaffolds a folder; your coding agent fills it in from your description; synthonic deploy turns it into a live app with a database and a URL you share with your team. Here's the whole procedure.

RequiresA Mac — macOS on Apple Silicon or Intel. The CLI is a single native binary; other platforms aren't supported yet.

You needA coding agent you already use: Claude Code, Codex, or any harness. It runs the CLI for you and edits the app folder.

BetaThis is an early, rough beta. The CLI can break. You deploy as a guest, no signup. When something breaks, tell us: hello@synthonic.app.

Procedure

Six steps, mostly run by your agent.

00 · INSTALL

Get the CLI

macOS only. One native binary, no dependencies.

One line. It grabs the macOS binary for your Mac, drops it on your PATH, and points it at the hosted control plane — no Node, no dependencies.

your mac · terminal

curl -fsSL https://synthonic.app/install.sh | sh
  → installing synthonic (darwin-arm64)…
  ✓ installed  synthonic → ~/.local/bin/synthonic
  next:  synthonic init my-app

01 · SCAFFOLD

Create a starter app

A tiny folder + an AGENTS.md your agent reads.

synthonic init writes a minimal, node-free app that already deploys, plus an AGENTS.md authoring guide your coding agent reads to learn the whole contract.

your mac · terminal

synthonic init my-app
  ✓ Created my-app — a starter Synthonic app.
    cd my-app
    open the folder in your coding agent (it reads AGENTS.md), describe your tool
    synthonic deploy

02 · DESCRIBE

Tell your agent what to build

It edits a small TypeScript folder, not a stuck artifact.

In Claude Code or any harness, describe the tool in plain language. Guided by AGENTS.md, your agent edits the folder: your data, who can do what, and the screens.

you → a feedback board: posts with a status, members vote, drag between columns
agent → edited schema/ access/ app/surfaces/ server/actions/  (2 collections, 2 actions)

synthonic.config.ts   app name → subdomain
schema/*.ts            your data — collections + fields
access/roles.ts        who-can-do-what — default-deny (admin · editor · viewer · agent)
app/surfaces/*.tsx     the screens — free React with the client SDK
server/actions/*.ts    governed backend rules (optional)
seed/*.json           starter rows
AGENTS.md             the authoring guide your agent follows

03 · DEPLOY

Ship the folder, get a live URL

Guest by default. No signup.

Your agent runs synthonic deploy. Synthonic type-checks and builds the folder into a real app with a database, deploys it, and prints the live URL.

your project · terminal

synthonic deploy
  → building artifact…
  built my-app  (2 collections, 2 actions)
  → started a temporary builder (guest)
  ✓ Live  https://my-app.synthonic.app
  live within ~30s (first hit provisions its TLS cert)

04 · ITERATE

Change it, redeploy

A failed build is the gate. Preview locally if you like.

React to the running app: "posts need an author." Your agent edits the folder and redeploys; if a build fails, it reports the errors to fix. Want to see changes before you ship? synthonic dev serves the app locally.

your project · terminal

synthonic dev .
  ✓ serving  http://127.0.0.1:8090   the maker console
  # edit the folder, save, and it reloads. then: synthonic deploy

05 · KEEP

Save your work

Guest by default. Save it when you want to keep it.

You deploy as a guest — nothing to sign up for. When you want your apps to stick around, run synthonic save with your email. We send a link; click it and your work is recoverable on any machine, forever — same apps, same URLs, now yours.

your project · terminal

synthonic save you@work.com
  → we emailed a link to you@work.com. Click it to keep your work.
  # open your inbox, click "Keep my work"
  ✓ Saved. your work is recoverable on a new machine or after a reinstall — always yours.

06 · SHARE

Run it together, people and AI

The deployed app is login-gated: only emails in seed/members.json can sign in, each with a role. Add your teammates. The AI operator is just another role — agent — least-privilege by default, so you grant only what it may do.

[
  { "email": "you@work.com",      "role": "admin"  },
  { "email": "teammate@work.com", "role": "editor" }
]
# admin · editor · viewer · agent — access is default-deny, granted per role

Legend

Command reference

The whole CLI. Your agent runs these; you rarely type them yourself.

synthonic init <dir>Scaffold a new app — a starter folder plus an AGENTS.md authoring guide for your coding agent.

synthonic dev <dir>Serve the app locally (the maker console) at 127.0.0.1:8090, reloading as you edit.

synthonic build <dir>Type-check and compile the folder into a shippable artifact under <dir>/dist.

synthonic deploy [dir]Build the artifact and push it to the cloud (defaults to the current directory), then print the live URL.

synthonic save [email]Keep your work: we email a link, you click it, and your guest apps become recoverable under your email — on any machine, forever.

synthonic console [dir]Reprint a deployed app's live URL and maker console links, without redeploying.

synthonic spine <dir>Extract and print the app's declarative spine — the shape the engine reads.

Config lives at ~/.synthonic/config.json. Point the CLI at another control plane with SYNTHONIC_CONTROL_PLANE, and reuse the same guest builder across deploys by setting SYNTHONIC_TOKEN.

Field note

When it breaks

It will, sometimes. That's the deal with a rough beta. Send us what you ran and what happened, and we'll fix it fast.

Report a break Back to the overview