Koo Docs
View as Markdown

Quickstart

Go from sign-up to a live, publicly showcased app in about ten minutes. This guide deploys a prebuilt container image; deploying from Git works the same way from a repository instead. Deploying with AI Coming soon will join the same flow.

You'll need a public container image that listens on a port — something like ghcr.io/you/app:latest. No credit card required.

1. Sign up

Sign up with your email or a Google account. Your login identifies you across every account you'll ever belong to — see Introduction for how accounts, apps, and services fit together.

2. Claim your handle

Pick your handle. It's your public identity on Koo: your profile lives at koo.io/@handle, and every app you showcase lives under it.

Handles are unique and claimed on a first-come basis.

3. Create your first app

Choose what to deploy. Pick container image as the source, name your app, and optionally tick the free Postgres and free Redis to add them alongside your web service.

The free Postgres and Redis aren't a trial. Your first (primary) account includes one web service, one Postgres, and one Redis — each 0.5 vCPU / 1 GiB — free forever, no card. See Free tier for how the allowance works when you resize.

4. Verify your phone

Koo requires MFA for every account. Verify your phone with a one-time code (SMS, or a voice call if you prefer), then save your recovery codes.

Recovery codes are shown once, at this step only. Store them somewhere safe — if you lose both your phone and your recovery codes, account recovery goes through support with manual identity verification.

Once verified, the console unlocks.

5. Deploy

Paste your image reference and the port your server listens on:

text
Image  ghcr.io/you/app:latestPort   8080

The image must be publicly pullable. Koo snapshots it as an immutable deployment and ships it — see Deploy a container for registries, tags, and private images.

6. Watch the deploy timeline

Every deployment streams an ordered timeline as it moves through the pipeline:

  1. enforce-started — Koo's hosting layer begins applying your image.
  2. applied — the new version is in place.
  3. ready — the deployment pipeline is complete.

ready means the image was applied, not that your app is healthy — after ready, the service's live status takes over and walks from not healthy to healthy as your container boots.

7. Visit your live URL

Your web service gets a public HTTPS URL, shown on the service in the console:

bash
curl -i https://<your-service-url>

8. Tail your logs

Open the service's Logs to watch your app's output live — useful right now if step 7 didn't return what you expected. See Logs.

9. Talk to your free Postgres or Redis (optional)

If you ticked them in step 3, the connection details are already injected into your web service as environment variables — DATABASE_URL for Postgres, REDIS_URL for Redis. Your code reads them like any other env var; see Environment and secrets.

10. Show the world

Your app has a public page at koo.io/@handle/app-slug — description, links, media, comments, and upvotes. Polish it up and it can surface in discovery, where other builders can find and follow your work. See App pages.

Next steps