Quickstart

Your only setup is to sign up in Studio, create one developer key, and run croche login once in your own terminal. Your coding agent handles the project, SDK debug key, integration, and first-turn check.

Croche 0.5.0 is a beta. For the hackathon, start with TypeScript or React Native on a simulator, emulator, a local browser, or Node. Real-device setup comes later.

0.5.0 package release pending verification. The install commands below target the planned release. TODO verify: complete this walkthrough against the published packages before treating it as a release-tested checklist.

Install the coding-agent plugin

If the plugin is not installed yet, use the public H1R-AI/croche marketplace:

Claude Code, in your terminal:

claude plugin marketplace add H1R-AI/croche
claude plugin install croche@croche

Codex, in your terminal:

codex plugin marketplace add H1R-AI/croche
codex plugin add croche@croche

Public marketplace installation is pending verification; see the plugin guide. Once installed, ask your agent to “build this with Croche.” If already installed, skip this step. The account setup below remains yours; the agent handles the app integration.

What you need

• Your emailed invite code. It works once; keep it private.
• For JavaScript or React Native: Node.js 22+ on macOS/Linux. Windows verification pending.
• For React Native: 0.76+ with the New Architecture, plus an iOS 15.1+ simulator or Android API 26+ emulator.

See the hackathon guide for the separate development and Runtime allowances.

Before asking you to sign in to the CLI, your coding agent installs the Croche CLI with the appropriate permission: npm install --global @h1r-ai/croche-cli. Public package availability and the new login command are pending verification. The agent must not ask you to run an unavailable command.

1. Sign in and activate your account

Open Croche Studio and sign in with Google, GitHub, or email. Enter your invite code to activate the account and unlock Studio. The link in your invitation email already has the code filled in.

Do not share the code or put it in a repository, presentation, or screenshot.

2. Create one developer key

In the account area, open Account → CLI keys (under Personal) and choose Create CLI key. This account developer key starts with dk_. Copy it privately when it is shown; do not paste it into your coding-agent chat.

You do not need to create a project or copy an SDK debug key in Studio. Your coding agent will do that through the CLI.

3. Run login yourself

In any private terminal on the same machine and OS user account as your coding agent, run:

croche login

Paste your developer key into the hidden prompt, not into chat or the command line. This command is user-run only: the agent must never run it for you or receive the key. It validates the key before saving it and prints the signed-in account. Tell the agent only that login is complete; it can check croche auth whoami --json without displaying the secret. No per-shell export or agent restart is needed for stored login.

Planned login — TODO verify: installation, hidden input, validation, protected storage, and reuse from another terminal must be checked against the matching released CLI. If unavailable, report the release blocker rather than sending a key to the agent. Windows verification is still pending.

That is your setup: sign up, create one developer key, run croche login. Ask your coding agent to add Croche to the app and run the first-turn check. The remaining steps describe the work it does for you. See CLI authentication for logout, storage, and CI behavior.

The agent creates the project and debug key

Planned CLI workflow — TODO verify: the new debug-key commands and private .env handling must be verified against the matching released CLI. If the commands are unavailable, stop and report the pending release; do not ask the user to paste a debug key or print one as a workaround.

With the requested installation and project-creation permissions, the agent checks the intended account after your login, and runs:

croche auth whoami --json
croche projects create --name "My app" --json
croche debug-keys create --project PROJECT_ID --json

Before creating the debug key, the agent checks that the destination env file is not already tracked by Git; adding an ignore rule does not untrack an existing file.

PROJECT_ID is the ID returned by project creation, not a credential. Project creation also returns the public project key, which the agent can put in app configuration; it is safe to include in the app. Reuse an existing intended project rather than creating duplicates.

The planned debug-key command writes CROCHE_DEBUG_KEY (cdt_) directly into ./.env, not into its default output. Output contains only the key ID/prefix and where it was written. It creates the file with 0600 permissions on supported systems and adds .env to .gitignore in a Git repository. --env-file PATH selects another file; the agent must check that the selected file is ignored too.

An existing different value is refused unless --force is used. The agent must stop and ask before replacing it, not force a reset automatically. It must not print the file, echo the key, use a secret-print mode, or include secrets in chat. Windows file-protection behavior remains unverified.

A debug key is an SDK development credential passed as debugKey, not the account developer key used by the CLI. The account key never goes into app code.

Studio drafts can replace code config. With Croche.open(...) in TypeScript and React Native, every debug key follows drafts by default, with no toggle. A draft replaces the whole code config and applies on the next open after a sync. Include every tool your app uses in the draft: the agent loses access to omitted tools on that next open, even if their handlers remain registered.

The agent installs the SDK

Your app	Intended 0.5.0 installation	Guide
TypeScript / JavaScript	npm install @h1r-ai/[email protected]	TypeScript
React Native 0.76+, New Architecture	npm install @h1r-ai/[email protected] @h1r-ai/[email protected], then cd ios && pod install	React Native

No Rust toolchain is needed to install these SDKs. Public package availability is still pending verification. Do not substitute an unrelated package if the registry does not resolve the intended package.

Native Swift and Kotlin setup is pending API review. For the hackathon, start with TypeScript or React Native. See the iOS and Android pages for the remaining native documentation TODOs.

The agent runs the first turn

The fastest check is a Node script. The agent inserts the public key returned by project creation and saves this as first-turn.mjs. The debug key stays in the CLI-created .env file:

import { Croche } from '@h1r-ai/croche';
import { FileStorage } from '@h1r-ai/croche/node';

if (!process.env.CROCHE_DEBUG_KEY) throw new Error('Load the private CLI-created env file.');
const croche = await Croche.open({
  language: 'en', // The demo user's language, not the config's authored language.
  projectKey: '<public project key returned by CLI>',
  debugKey: process.env.CROCHE_DEBUG_KEY, // Development only; never ship it.
  storage: new FileStorage('./croche-state'),
  config: {
    model: 'deepseek/deepseek-v4.1-flash',
    instructions: 'You are a friendly guide. Keep replies to one or two sentences.',
  },
});
try {
  const agent = await croche.agent();
  const result = await agent.request({ id: crypto.randomUUID(), text: 'What can you do?' });
  const reply = result.messages.at(-1);
  if (result.status !== 'answered' || reply?.status !== 'completed' || !reply.text?.trim()) {
    console.error('First turn did not complete:', result.status, reply?.error?.code ?? 'no_reply');
    process.exitCode = 1;
  } else {
    console.log(reply.text);
  }
} finally {
  await croche.close();
}

The agent checks syntax first, then runs one small live request when authorized:

node --check first-turn.mjs
node --env-file=.env first-turn.mjs

Node does not load .env automatically: plain node first-turn.mjs does not load the CLI-created file. The --env-file flag exists from Node 20.6; Croche still requires Node 22+. Your project’s existing dotenv setup is an alternative if it loads the chosen file before Croche.open; no new loader dependency is needed. CLI login does not populate the SDK key.

These Node commands are also valid command forms in PowerShell, but Windows verification pending still applies. Node loads the file directly; nobody needs to display its contents. Use the chosen file path if the CLI wrote somewhere else. Do not source the file into shell commands or copy the secret into the prompt. Ignore croche-state/ as private app data too.

A completed, nonempty reply confirms that the first SDK request finished; a queued receipt does not. Give every new input a unique id. Replace the demo language with the user’s BCP-47 tag; see app config and language. The agent reports the actual result and any remaining blocker, never a made-up success.

React Native

Use the same Croche.open(...) API, imported from @h1r-ai/croche-react-native, with debugKey: __DEV__ ? developmentKey : undefined. The SDK supplies storage; do not copy the Node FileStorage setup. See the React Native guide.

Shipping a web app

Never put a debug key or server key in the browser, including local development. Run Croche.open on your backend and let the browser call your app endpoint. Load the CLI-created .env only into the local server process using --env-file or the project’s existing server-side dotenv setup. Do not use public-prefixed frontend environment variables. For production, use a server key from Settings → Keys → Server keys on the backend only.

Check the turn in Studio

• Open the project’s Monitoring → Logs. It includes debug-key turn reports. Under Filters, set Usage type to Development · Subscription to show development usage. Reports arrive in the background, so allow a little time after the turn.
• Go back to the account area and open Billing → Studio plan to see development allowance usage. These requests use the development allowance.
• Monitoring → Activity shows only production traffic. It stays empty while you use a debug key; this does not mean your development turn failed.

Missing reports are not a confirmed zero or proof that an app is healthy. Check the reply and the reported evidence separately.

Next: have your agent save a draft

This step is for TypeScript and React Native using Croche.open(...), the recommended hackathon path. Native Swift and Kotlin setup remains pending API review.

The coding agent reads and edits the config, then saves a Cloud draft through the CLI:

croche config get --project PROJECT_ID --output croche.config.json
# Edit croche.config.json, preserving the complete config and every required tool.
croche config save croche.config.json --project PROJECT_ID

Read before saving: get records the base revision used by save to detect conflicts. Keep the complete project document. If no draft exists, prepare a document with schema: 2 and the app’s complete config in config; do not save the returned null value. Saving a draft is not a production release. On a conflict, preserve the local edit and reconcile the latest draft rather than overwriting someone else’s changes.

1. Run the app with a debug key. Every debug key follows the draft automatically.
2. Reopen after the config sync. Changes apply on the next open after that sync, never mid-session. If the download has not finished, allow sync and reopen again.
3. Test the changed behavior and inspect Monitoring → Logs.
4. A human opens Build → AI config → Running config, reviews the current draft’s readable cards and diff against the released config, and chooses Release…. Type the project name to approve, then choose Approve and publish.
5. Production installs receive the released config on their next open after sync. Releasing alone does not prove that an install has applied it.

Keep these rules in mind:

• A Studio draft or release replaces the entire code config; it does not merge. Include all required instructions, tool declarations, and agents. Tool handlers stay in code.
• Drafts reach only debug-key (debugKey) installations. Every debug key follows drafts by default; there is no toggle. Verified production installations receive released config, not unreleased drafts.
• A config declaring a tool your app has not registered is not delivered; the app keeps its own config.
• CrocheRuntime.create(...) never uses Cloud config. Studio-delivered config requires Croche.open(...), available in TypeScript and React Native.

Warning: a draft must include every tool your app uses. If you omit a tool, the agent loses access to it on the next open after a sync, even if the handler remains registered in the app.

See app config and language for more detail.

Next steps

• Use the coding-agent plugin and CLI for guided integration and project commands.

• Add an app action with tools, keeping permission checks in your app.

• Understand messages and activity before building a streaming UI.

• Review balance, limits, and errors.

• In Studio, Project overview → Connect coding agent provides your coding agent with the project’s public setup.