---
title: Hackathon guide
description: Sign in once, let your coding agent set up the SDK, and understand the event allowances.
---

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

Use Croche to build the AI features in your hackathon app while your team focuses on the experience.

Croche **0.5.0 is a beta**. Start with **TypeScript or React Native** and test on simulators, emulators, a local browser, or Node. Real-device setup comes later.

> **0.5.0 public package availability is pending verification.** The SDK guides target the planned release; check their notices before installation.

## Your three setup steps

1. Sign up or sign in at [Croche Studio](https://studio.croche.ai), redeeming your single-use invitation privately if needed.
2. Open **Account → CLI keys** (under **Personal**) and create **one developer key** (`dk_`).
3. After your agent installs the CLI, run `croche login` yourself in any private terminal on the same machine and OS account. Paste the key into its hidden prompt, **never into chat**. The agent must never run login. This login workflow is pending verification; follow the [quickstart](quickstart.md).

Your agent handles the rest: create a project with `croche projects create`, use its returned public project key, then run the **planned** `croche debug-keys create --project PROJECT_ID` command. It writes `CROCHE_DEBUG_KEY` (`cdt_`) directly into `.env` for the SDK's `debugKey` option; default output contains only metadata and a file location, not the secret. This new CLI workflow remains pending release verification.

You do not need to create or copy another key in Studio for onboarding. The agent installs the SDK, loads the private file without printing it, and verifies a real first reply. Keep `.env`, private app data, and the invitation out of commits and chat. Follow the [quickstart](quickstart.md) for the file-protection and existing-value safeguards.

## What's included

| Allowance | Amount | Meaning |
| --- | --- | --- |
| Development usage | $100 total | A total cap, not a weekly renewal |
| Runtime credit | $100 | Granted through the hackathon code for Runtime usage |
| Unverified usage cap | $100 | A limit within available Runtime credit, not an extra $100 |

Debug-key turns consume development usage, not Runtime credits. These are separate allowances, not one shared balance.

## Pick your platform

| Platform | Requirements | Configuration in 0.5.0 |
| --- | --- | --- |
| [TypeScript / JavaScript](sdks/typescript.md) | Node.js 22+ on macOS/Linux | `Croche.open(...)` can use Studio AI config |
| [React Native](sdks/react-native.md) | Node.js 22+ on macOS/Linux, React Native 0.76+, New Architecture | `Croche.open(...)` can use Studio AI config |

**Windows verification pending**; this guide does not claim Windows support. No Rust toolchain is needed to install these SDKs.

**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.

## Check your demo in Studio

1. Verify an actual reply in the app.
2. Open **Monitoring → Logs → Filters**, then set **Usage type** to **Development · Subscription**. Reports arrive in the background; allow a little time.
3. Return to the account area and check **Billing → Studio plan** for development allowance usage.

**Monitoring → Activity** is production-only, so it stays empty during debug-key testing. An empty production chart is not proof that your development turn failed.

## Try a different agent configuration

For TypeScript and React Native using `Croche.open(...)`, the coding agent gets the existing
config, edits the complete document, then saves a Cloud draft:

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

`get` must run before `save` so the CLI has the current base revision. See the
[quickstart](quickstart.md#next-have-your-agent-save-a-draft) for first-draft and conflict handling.
Saving does not publish a release. A human opens **Build → AI config → Running config**, reviews
the draft's cards and diff, and chooses **Release…**, confirming with the project name.
Production installs apply the released config on their next open after sync.

Every debug key follows drafts by default, with no toggle. A Studio config **replaces the whole code config; it does not merge**. It takes effect on the **next open after a sync**, never mid-session. Restart the app after saving; if the download has not finished and the old behavior remains, restart once more.

> **Include all the tools your app uses in the draft.** If you omit a tool, the agent loses access to it at the next open after sync, even if the app still registers its handler. A config declaring a tool the app does not register is not delivered.

See [app config and language](concepts/config.md). Use the `Croche.open(...)` project API for this workflow.

## Build safely

Keep development credentials in private local configuration. Never put a debug key or server key in the browser, even for local testing: run `Croche.open` on the backend and load the private file into that server process. To ship a web app, use a server key from **Settings → Keys → Server keys** on the backend; the browser talks only to that backend. Never send the server key to a browser or mobile app.

Start with one agent and a small app capability. Keep data access and permission checks in your tool handlers, and test what happens when an action is refused.