Senuto Hackathon 2026: handbook#

Wszystko, czego potrzebujesz, żeby od poniedziałku 14:00 budować, a w czwartek pokazać działający produkt. Pytania: kanał #hackaton na Slacku.

Harmonogram#

Start w 5 minut#

1. GitHub: zaakceptuj zaproszenie do organizacji Senuto-Hackathon. Twój zespół ma repo team-<n>.
2. Codespace: w repo zespołu: Code → Codespaces → Create codespace on main (4 rdzenie / 16 GB wystarczą). Instaluje się wszystko: Node 22, Python 3.12, Docker, GitHub CLI, Claude Code. Klucze API są już w środowisku.
3. Claude Code: w terminalu claude → zaloguj się swoim kontem. Pluginy hackathonu (/hackify:*) są włączone automatycznie.
4. Uruchom: npm run dev → otwórz port 3000. Strona startowa pokazuje, które klucze są podpięte.
5. Deploy: w Claude: /hackify:init, potem /hackify:deploy. Od tej chwili każdy git push na main wdraża aplikację.

Wolisz laptopa? git clone, npm ci, klucze do .env.local (lista nazw w .env.example; wartości weź z Codespaces albo od kapitana), a dla deployu COOLIFY_TOKEN=… w ~/.config/hackify/env. Pluginy: /plugin marketplace add Senuto-Hackathon/hackathon-skills, potem /plugin install hackify@senuto-hackathon.

Zatrzymuj Codespace, gdy z niego nie korzystasz (automatycznie po 30 min bezczynności). Godziny Codespaces są wspólne.

Starter#

Repo zespołu powstało z szablonu hackathon-starter:

• Next.js 16 (App Router, TypeScript, Tailwind 4)
• Senuto Design System: 60 komponentów w src/components/ui/, tokeny, Poppins, dark mode, dokumentacja w .senuto-ds/
• Klienty API w src/lib/hack.ts (tylko po stronie serwera): gateway, nodeshub, openrouter
• Healthcheck GET /api/health, Dockerfile (obraz produkcyjny), docker-compose.yml (lokalny test obrazu)
• CLAUDE.md z zasadami dla Claude'a (bezpieczeństwo kluczy, DS, kontrakt deployu)

Inny stack (np. Python/FastAPI)? Proszę bardzo: ważne, żeby był Dockerfile, aplikacja słuchała na 0.0.0.0:<port> i miała endpoint zdrowia. Ustaw port: i health: w .hackathon/app.yaml.

API i klucze#

Przegląd dla Claude'a: /hackify:apis.

Klucze OpenRouter: każdy uczestnik dostaje osobisty klucz (DM na Slacku), a zespół dodatkowo klucz aplikacji, na którym działa wdrożone demo. Razem $500 na zespół, każdy klucz ma twardy limit. Klucz osobisty wpisz jako user secret w Codespaces (OPENROUTER_API_KEY, Settings → Codespaces → Secrets → wybierz repo zespołu).

Web Unlocker: szybki test#

curl -s -H "Authorization: Bearer $HACK_GATEWAY_TOKEN" "$HACK_GATEWAY_URL/v1/me"
curl -s -H "Authorization: Bearer $HACK_GATEWAY_TOKEN" \
  "$HACK_GATEWAY_URL/v1/unlocker?url=https://example.com/&format=markdown&country=pl"

import { gateway, nodeshub, openrouter } from "@/lib/hack";
const page = await gateway.unlock(url, { format: "markdown", country: "pl" });     // 2–10 s, czasem do 2 min
const serp = await nodeshub.search({ keyword: "buty do biegania", gl: "pl", hl: "pl", num: 10, device: "desktop" });
const text = await openrouter.chat([{ role: "user", content: "Streść:\n" + page.body }]);

Cache'ujcie wszystko. Limity są dzienne i wspólne dla zespołu, a upstreamy bywają wolne. Na Demo Day pokazujcie dane przeliczone wcześniej, a wywołania na żywo traktujcie jako bonus.

Deploy i hosting#

• Każdy zespół ma własny serwer (8 vCPU / 16 GB) zarządzany przez Coolify: https://coolify.senuto.dev (login zespołu dostaje kapitan: t<n>@senuto.dev). W Coolify widzicie logi buildów i kontenerów, terminal i bazy danych.
• Adres aplikacji: https://<app>.t<n>.senuto.dev (HTTPS automatycznie, noindex dla wyszukiwarek).
• Pierwszy deploy: /hackify:init (sprawdza Dockerfile, port, healthcheck, sekrety; buduje obraz lokalnie), potem /hackify:deploy (tworzy aplikację, podpina zmienne zespołu, wdraża i pokazuje log). Zacommitujcie .hackathon/state.json, żeby cały zespół wdrażał tę samą aplikację.
• Kolejne: git push na main wdraża automatycznie. Status i logi: /hackify:status.
• Baza danych: hackify db create tworzy Postgresa 17 w waszym projekcie i ustawia DATABASE_URL.
• Zmienne: klucze API są zmiennymi zespołu w Coolify ({{team.KLUCZ}}). Własne zmienne ustawicie przez hackify env set KLUCZ -.

Zasady#

• Klucze tylko po stronie serwera. Nigdy w kodzie klienta, NEXT_PUBLIC_*, repo ani logach. Wyciek = koniec limitu zespołu i rotacja klucza. Każde wywołanie gatewaya jest logowane per zespół.
• Scraping: tylko publiczne strony. Nie zbieramy danych osobowych, nie logujemy się na cudze konta, nie obchodzimy paywalli, rozsądne wolumeny. Domeny Senuto i Nodeshub są zablokowane w gatewayu.
• Infrastruktura: nie atakujemy niczego, łącznie z naszą (inne zespoły, Coolify, gateway). Root na waszym serwerze jest po to, żebyście mogli debugować, a nie po to, żeby kopać kryptowaluty.
• Budżety: limity są twarde. Pętla bez limitu wywołań API to najszybszy sposób, żeby zostać bez danych na demo.
• Kod i prawa: zgodnie z dokumentami podpisanymi przy zgłoszeniu.
• Organizatorzy mają wyłącznik awaryjny dla każdego klucza i serwera. Używamy go tylko, gdy coś się pali.

Demo Day: checklista#

• ☐ Aplikacja działa pod https://<app>.t<n>.senuto.dev najpóźniej 2 h przed waszym slotem
• ☐ Deploy freeze 1 h przed: żadnych pushy na main (pracujcie na branchu)
• ☐ Dane demo przeliczone i w bazie/cache: demo nie zależy od 2-minutowego scrapowania na żywo
• ☐ Nagranie zapasowe 60–90 s (środa wieczorem)
• ☐ Sprawdźcie demo w trybie incognito na telefonie

FAQ#

Build pada w Coolify, a lokalnie działa. hackify check --build buduje dokładnie ten sam obraz. Najczęściej to błędy TypeScript w next build, brakujący plik w repo (nie w .gitignore?) albo za mało pamięci w buildzie.

502 / „Bad Gateway”. Aplikacja nie słucha na 0.0.0.0:3000 albo healthcheck /api/health nie zwraca 200. /hackify:status i hackify logs.

Przekierowanie na https://0.0.0.0:3000/…. Nie budujcie URL-i z request.nextUrl.origin; używajcie process.env.APP_URL albo względnych przekierowań.

429 z gatewaya. Dzienny limit zespołu wykorzystany (/v1/me). Reset o północy; w razie potrzeby piszcie na #hackaton.

403 z Nodeshub. Skończyły się tokeny na kluczu zespołu (nodeshub.balance()). Piszcie na #hackaton.

402 z OpenRouter. Klucz osiągnął limit $. Sprawdźcie, który klucz jest używany (osobisty czy aplikacji).

Nowy secret nie jest widoczny w Codespace. Codespaces: Rebuild Container albo nowy codespace.

npx shadcn add @senuto/… nie działa. Wszystkie 60 komponentów jest już w src/components/ui/. Jeśli brakuje czegoś spoza listy, użyjcie stockowego shadcn i dopasujcie tokeny (/hackify:design).

Kontakt#

• #hackaton na Slacku: wszystko, od kluczy po infrastrukturę
• Infrastruktura, Coolify, deploy: Michał