# Build your first app

A step-by-step walkthrough, from describing your app to trying it in COHO.

:::tip[Try it on Playground first]
This walkthrough creates the app in your **real** COHO organisation. To build and test against demo data first, start with [Try it safely on Playground](../playground/).
:::

This walkthrough builds a private app that COHO hosts for you. Copy each prompt into your AI tool, adding your own details where it says so. Each prompt block has a copy button in its top-right corner.

<Steps>

1. **Check you're connected**

   Make sure your AI tool is [connected to COHO](../what-you-need/) and is working on the right organisation.

2. **Give your AI the Atrium ADK**

   The ADK is the rulebook for Atrium apps: the spec, the rules and the design system in one file. Your AI needs it to build an app COHO will accept. You can also [download it as ADK.md](../../adk/).

   ```text title="Prompt" wrap
   Read the COHO Atrium ADK in full:
   https://docs.coho.life/atrium-developer/llms-full.txt
   For any screens, use the Atrium design system:
   https://docs.coho.life/atrium-design/llms-full.txt

   We'll build an Atrium app together. Start from the hello-go sample in
   https://github.com/CompanyForLife/atrium-app-samples/tree/main/samples/hello-go
   (it already has the Dockerfile COHO Hosting needs) and keep to the ADK exactly,
   especially signature verification (section 3). Don't do anything yet; tell me when you've read it.
   ```

3. **Describe your app**

   Say what it should do in plain words: when it runs, what it does, and whether managers need a screen or settings.

   ```text title="Prompt" wrap
   Here's the app I want: [describe it, for example: "when a tenancy starts,
   send the tenant a welcome message", "a panel that lists tenancies that
   started this week"].

   Before writing any code, explain in plain English:
   - which COHO events or schedules it will use
   - what it will read or change in COHO, and which capabilities that needs
   - whether it needs a panel inside COHO or a settings form
   Then wait for me to agree.
   ```

4. **Let your AI build it**

   ```text title="Prompt" wrap
   Go ahead and build it from the hello-go sample. Keep the health check,
   setup, disconnect and signature code from the sample. Check the signature
   code against the test vectors in section 3.1.1 of the spec and show me the result.
   ```

5. **Ask your AI to host it on COHO**

   Your AI packages the app and asks COHO to build and run it. COHO's tools make it show you a **preview first**: once for the permissions your app asks for, then for the app itself. It should only go ahead after you say yes each time.

   ```text title="Prompt" wrap
   Package the app as a zip for COHO Hosting: include the Dockerfile, leave out
   anything that isn't source (dependencies folders, .git), and make the app listen
   on the port in the PORT environment variable.
   Then use the COHO MCP tools to create it as a PRIVATE hosted app
   (requestPublicListing: false). Follow the tools' own instructions: show me the
   permissions preview and the registration preview, and wait for my yes before
   confirming each one.
   ```

   :::caution[Always read the preview]
   Your AI should never confirm a create or update without asking you. If it tries to, stop it and say no.
   :::

6. **Wait until it's ready**

   COHO builds your app. The stages are *queued → fetching → building → pushing image → deploying → ready*.

   ```text title="Prompt" wrap
   Using the COHO MCP tools, check my app's provisioning state every minute or so
   until it's ready or failed. If it fails, tell me why in plain English.
   ```

7. **Connect it in the COHO Store**

   Your AI can't do this step for you yet. In COHO, open the **Store**, go to **My apps**, find your app and choose **Connect**.

   If connecting fails, COHO rolls it back. See [Get help](../get-help/) for what to try.

8. **Try it out**

   - Use **Run test** in the Store to send your app a test event.
   - Check your app's **logs** in the Store. Warnings and errors show as needing attention.
   - If your app has a panel, open it from the Store.

</Steps>

## Changing your app later

```text title="Prompt" wrap
I want to change my Atrium app: [describe the change].
Make the change, package a new zip, and use the COHO MCP tools to update the hosted
app (this rebuilds it). If only the name or description changes, update the listing
instead, which doesn't need a rebuild. Show me the preview and wait for my yes.
```

More ready-made prompts: [Prompts to copy](../prompts/).