Skip to content
Docs

Quickstart

This guide takes you from a fresh machine to running your first agent end-to-end.

Expected time: about fifteen minutes (a few extra for the first Docker pull).

0. Download and install

Section titled “0. Download and install”

Set up a new Cinatra instance from scratch with the published CLI (npm @cinatra-ai/cinatra) — no separate clone step required:

Terminal window
npx @cinatra-ai/cinatra install

That single, idempotent command checks your prerequisites first (Node.js 24+, git, pnpm via Corepack, Docker with the Compose plugin, free ports), clones Cinatra into a cinatra/ directory, creates your .env.local, brings up the local Docker services (Postgres, Redis, Nango, and others), installs dependencies, and runs first-time setup — cloning only the extension repos your instance declares as dependencies, never an org-wide enumeration. It is re-runnable: running it again on the same checkout reconciles it in place instead of cloning again. Add --dry-run to preview the steps without changing anything, or --resume to finish an install that was interrupted.

Use --mode prod instead of the default --mode dev for a production instance — see Installation § Dev vs prod for how the two differ.

After it completes, cd cinatra and continue from Step 1 below. From inside the checkout, npx @cinatra-ai/cinatra status and npx @cinatra-ai/cinatra doctor give you a quick read on instance health.

Prefer to manage the clone yourself, or contributing to the platform? Installation documents the equivalent manual, git clone-first flow — the CLI runs those same steps for you.

1. Create the admin account

Section titled “1. Create the admin account”

Open http://localhost:3000 in a browser. You will be redirected to a sign-up form. Register with an email and password.

The first user to register becomes the platform admin and the owner of the default workspace organization. Every subsequent sign-up creates a regular user account. Admins are the only users who can install agent extensions, manage network/registry settings, and access cross-organization administration.

2. Complete the setup wizard

Section titled “2. Complete the setup wizard”

After registering you land in the setup wizard at /setup. It walks through a few one-time decisions:

  1. Encryption key. Cinatra encrypts provider API keys and connector credentials at rest. In development the wizard generates a key and persists it to .env.local. In production this is provided as an environment variable instead.
  2. Instance identity. A display name (e.g. “Acme Demo”) and a short namespace slug (e.g. acme-demo). The namespace is used as part of agent package names you publish from this instance.
  3. large language model (LLM) provider. Paste an OpenAI API key. OpenAI is the default provider; you can connect Anthropic and Google Gemini later from Administration → LLM Providers (/configuration/llm).

Each step has its own page; the wizard skips steps you have already completed if you re-enter it.

3. Connect at least one LLM provider

Section titled “3. Connect at least one LLM provider”

If you skipped the LLM step in the wizard, visit Administration → LLM Providers (/configuration/llm) and connect a provider. You need at least one to run any agent.

For the rest of this guide, OpenAI is enough.

4. Install a sample agent

Section titled “4. Install a sample agent”

Visit Administration → Marketplace (/configuration/marketplace). The marketplace installs the full set of extension kinds — agents, connectors, skills, artifacts, and workflows — not just agents. For this walkthrough we install an agent. Pick one that looks simple — for example, Blog Idea Generator Agent (a stateless agent that turns a short brief into a batch of blog post ideas; no external credentials required) or Company Discovery Agent (turns a company name or domain into a normalized CRM account).

Click Install. The platform downloads the agent extension, validates its oas.json, persists it locally, and makes it available under Agents (/agents).

Behind the scenes: the installation creates an agent_templates row, copies the package contents to extensions/<vendor>/<slug>/, and registers the agent’s Model Context Protocol (MCP) primitive so it becomes callable like any other capability.

5. Run it

Section titled “5. Run it”

Open the Agents sidebar group. The top-level /agents route is now an interactive dashboard of recently used and recently run agents, and is the installed-agents surface. Click the agent you just installed and use its Run action.

Two patterns appear here, both backed by the same runtime:

  • Setup-step human-in-the-loop (HITL). Before the agent starts, it asks for the inputs declared in its Open Agent Specification (OAS) file (a URL, a topic, recipient list, etc.) via a form rendered from the agent’s declared HITL screens.
  • Mid-run HITL. During the run, the agent may pause for a review (a recipient list to approve, a draft email to edit) and ask you to confirm before continuing.

Fill in the inputs, click Start, and watch the run page — you will see typed Agent-User Interaction Protocol (AG-UI) events streaming in real time: tool calls, text chunks, state snapshots, eventually a completion or interrupt event. Reload the page if you like; the stream resumes from the durable Redis-backed event log via the Last-Event-ID header.

6. Watch the standards in action

Section titled “6. Watch the standards in action”

While the run is happening:

  • OAS — the agent definition came from a oas.json file in the installed package; the platform compiled it into the runtime representation when the package was installed.
  • agent-to-agent (A2A) protocol — the run is being executed inside the WayFlow (Cinatra’s OAS Flow agent runtime) container. The Next.js app reached it over an A2A call.
  • AG-UI — the events you see in the run page (tool calls, message chunks, state snapshots) are AG-UI typed events delivered over Server-Sent Events.
  • agent-to-UI (A2UI) protocol — if the run paused for HITL, the form you saw was rendered from an A2UI surface payload published in parallel to the AG-UI lifecycle stream.

See Open standards in Cinatra for the full breakdown.

7. Let your edits teach the next run (optional)

Section titled “7. Let your edits teach the next run (optional)”

If your admin has enabled skill autosave at /configuration/skills, every prompt edit you make inside a HITL surface during a run is captured at the end of that run and turned into a custom skill scoped to you and the agent you just ran. The next time you run the same agent, the platform’s skill-matching engine injects that custom skill back into the agent’s prompt context — the agent already knows your preferences. See Continuous learning and custom skills for the full picture; nothing here is on by default.

8. Try the chat assistant

Section titled “8. Try the chat assistant”

The chat surface at /chat (linked from the main nav) is a built-in AI assistant that can drive every capability of the platform via MCP. Try:

“Create a new agent that summarizes a URL using the page title and the first paragraph.”

The assistant walks through the OAS Flow scaffolding interactively, validates the result, and offers to publish it to your local registry. You can install and run the new agent the same way as any other.

The chat needs the public MCP URL set — see MCP public URL & tunnels. The same /api/mcp endpoint lets external MCP clients (Claude Desktop, Codex, Claude.ai, ChatGPT) drive Cinatra; see Connect MCP clients.

What to do next

Section titled “What to do next”

Docs content licensed under CC-BY-4.0; embedded code snippets under Apache-2.0.