---
title: Quickstart
description: Sign in with croche login and let your coding agent create a project and run a first turn.
---

[!nav:main](/nav/main.md)

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:

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

**Codex**, in your terminal:

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

Public marketplace installation is pending verification; see the [plugin guide](plugin.md).
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](hackathon.md) for the separate development and Runtime allowances.

Before asking you to sign in to the CLI, your coding agent installs the [Croche CLI](cli.md) 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](https://studio.croche.ai) 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:

```sh
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](cli.md#connect-your-studio-account) 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:

```sh
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/croche@0.5.0` | [TypeScript](sdks/typescript.md) |
| React Native 0.76+, New Architecture | `npm install @h1r-ai/croche@0.5.0 @h1r-ai/croche-react-native@0.5.0`, then `cd ios && pod install` | [React Native](sdks/react-native.md) |

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](sdks/ios.md) and [Android](sdks/android.md) 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:

```js
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:

```sh
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](concepts/config.md). 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](sdks/react-native.md).

### 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:

```sh
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](concepts/config.md) for more detail.

## Next steps

- Use the [coding-agent plugin](plugin.md) and [CLI](cli.md) for guided integration and project commands.

- Add an app action with [tools](concepts/tools.md), keeping permission checks in your app.
- Understand [messages and activity](concepts/messages.md) before building a streaming UI.
- Review [balance, limits, and errors](concepts/credits.md).
- In Studio, **Project overview → Connect coding agent** provides your coding agent with the project's public setup.