# Cobonaut Full Documentation (Combined)

---
# Section: Deployment Basics (Web) (Podstawy wdrożenia (Web))
Category: user
ID: intro-web

## English Version
# Deployment Basics from the Web Dashboard

Cobonaut allows you to instantly deploy your projects to a production server using our integrated CapRover system. The entire process is fully automated.

### Quickstart in 3 steps:
1. Navigate to your selected project in the Workspace.
2. In the top right corner of the "Versions" section, click the rocket icon button (Deploy).
3. Enter a unique subdomain name and click "Deploy". Your app will be automatically installed and assigned a secure SSL connection.

## Deployment Limits
Each user is limited to a maximum of 10 active cloud deployments at the same time. If you reach this limit, you must delete older deployments in the Cloud dashboard to free up slot space.

## Managing Applications in the Cloud Dashboard
In the main dashboard at /cloud you will see all your active applications. From there you can:
* Open the deployed application directly in a new tab.
* Navigate to the Details view to connect your own domain or check logs.
* Hide the deployment from the dashboard (it will keep running, but won't clutter your card view).
* Delete the application (this stops and completely removes the container on the CapRover cluster).

## Polish Version
# Podstawy wdrożenia z poziomu Panelu Web

Cobonaut umożliwia błyskawiczne wdrażanie Twoich projektów na serwer produkcyjny za pomocą zintegrowanego systemu CapRover. Cały proces jest w pełni zautomatyzowany.

### Szybki start w 3 krokach:
1. Przejdź do wybranego projektu w Workspace.
2. W prawym górnym rogu sekcji "Wersje" kliknij przycisk z ikoną rakiety (Wdróż).
3. Wpisz unikalną nazwę dla swojej subdomeny i kliknij przycisk "Wdróż". Aplikacja zostanie automatycznie zainstalowana i otrzyma bezpieczne połączenie SSL.

## Limit wdrożeń
Każdy użytkownik w systemie może mieć maksymalnie 10 aktywnych wdrożeń w chmurze jednocześnie. Jeśli osiągniesz limit, musisz usunąć starsze wdrożenia w panelu Cloud, aby zwolnić miejsce.

## Zarządzanie aplikacjami w sekcji Cloud
W głównym menu na stronie /cloud zobaczysz wszystkie swoje aktywne aplikacje jako kafelki. Możesz stamtąd:
* Otworzyć wdrożoną stronę bezpośrednio w nowej karcie.
* Przejść do widoku Szczegółów, by podpiąć własną domenę lub zobaczyć logi.
* Ukryć wdrożenie na liście (będzie nadal działać, lecz nie będzie widoczne na kafelkach).
* Usunąć aplikację (spowoduje to zatrzymanie i usunięcie kontenera na serwerze CapRover).


---
# Section: Custom Domain & SSL (Własna domena i SSL)
Category: user
ID: custom-domain

## English Version
# Connecting a Custom Domain

Every deployment gets an automatic subdomain (e.g. mojapogoda.cloud.cobonaut.com). However, you can easily connect your own custom domain name (e.g. portfolio.com).

## Step 1: Configure your DNS settings
Log in to your domain registrar (e.g. GoDaddy, Cloudflare, Namecheap) and create the following record:

| Type | Host/Name | Value |
| :--- | :--- | :--- |
| CNAME | @ (or subdomain, e.g. www) | [nazwa-aplikacji].cloud.cobonaut.com |

## Step 2: Connect the domain in Cobonaut
Navigate to your deployment Details page in the Cloud dashboard, enter your domain in the "Custom domain" section, and click "Connect". Our system will automatically:
* Register the domain on the CapRover cluster.
* Request Let's Encrypt to issue an automatic SSL certificate for your domain.
* Configure secure HTTPS redirection.

> **Note:** DNS propagation across the globe can take anywhere from 15 minutes to 24 hours. Make sure you complete the DNS setup before clicking the Connect button in Cobonaut.

## Polish Version
# Podłączanie własnej domeny

Każde wdrożenie otrzymuje automatyczną subdomenę (np. mojapogoda.cloud.cobonaut.com). Możesz jednak bardzo łatwo podłączyć swoją własną, zewnętrzną domenę (np. portfolio.pl).

## Krok 1: Konfiguracja rekordu DNS
Zaloguj się do panelu u swojego rejestratora domeny (np. OVH, Cloudflare, Nazwa.pl) i dodaj następujący rekord:

| Typ | Host/Nazwa | Wartość |
| :--- | :--- | :--- |
| CNAME | @ (lub subdomena, np. www) | [nazwa-aplikacji].cloud.cobonaut.com |

## Krok 2: Powiązanie domeny w panelu Cobonaut
Przejdź do Szczegółów wdrożenia w panelu Cloud, wklej swoją domenę w sekcji "Własna domena" i kliknij "Połącz". System automatycznie:
* Zarejestruje domenę na serwerze CapRover.
* Wystąpi do Let's Encrypt o automatyczny certyfikat SSL dla Twojej domeny.
* Uruchomi przekierowanie HTTPS, dzięki czemu Twoja strona będzie bezpieczna.

> **Uwaga:** Rozpropagowanie rekordów DNS w Internecie może zająć od 15 minut do 24 godzin. Kliknij przycisk weryfikacji dopiero po dodaniu rekordu DNS u rejestratora.


---
# Section: API Authentication (Uwierzytelnianie API)
Category: api
ID: api-auth

## English Version
# API Authentication

Cobonaut provides an external API (api.cobonaut.com) designed for external CLI tools, automation scripts, and third-party integrations. It uses a persistent API Token generated in settings.

### Authorization Header Format
```http
Authorization: Bearer cobo_live_[token]
```

### How to acquire your API key?
Navigate to Settings (/settings), check the box "Chcę używać Cobonaut przez zewnętrzne API" and copy the generated token. You can regenerate it at any time.

## Polish Version
# Uwierzytelnianie API

Cobonaut udostępnia zewnętrzne API (api.cobonaut.com) przeznaczone dla zewnętrznych narzędzi CLI, skryptów automatyzacji oraz integracji zewnętrznych. Używa ono trwałego tokenu API generowanego w ustawieniach.

### Format nagłówka autoryzacji
```http
Authorization: Bearer cobo_live_[token]
```

### Jak pozyskać klucz?
Przejdź do zakładki Ustawienia (/settings), zaznacz checkbox "Chcę używać Cobonaut przez zewnętrzne API" i skopiuj wygenerowany token. Możesz go w każdej chwili zresetować.


---
# Section: Dedicated Deploy API (Dedykowany API Deploy)
Category: api
ID: api-deploy

## English Version
# Dedicated REST API (api.cobonaut.com)

Cobonaut provides a set of public REST endpoints to facilitate integration with external CI/CD pipelines, AI agents (such as Antigravity), and scripts.

All requests must be authenticated using the following header:
```http
Authorization: Bearer cobo_live_[token]
```

---

## 1. List Projects
Returns the list of all your projects.

* **Method:** `GET`
* **URL:** `https://api.cobonaut.com/v1/projects`

### Example Response
```json
{
  "success": true,
  "projects": [
    {
      "id": "uuid-project-1",
      "name": "My Application",
      "templateKey": "nextjs-basic-app",
      "createdAt": "2026-06-12T16:00:00.000Z",
      "updatedAt": "2026-06-12T16:00:00.000Z"
    }
  ]
}
```

---

## 2. Create Project
Creates a new project and seeds its Git repository from the selected template. Also returns the Gitea repository URL.

* **Method:** `POST`
* **URL:** `https://api.cobonaut.com/v1/projects`
* **Content-Type:** `application/json`

### Request Body Parameters:
* `name` (string, required) - Project name.
* `templateKey` (string, required) - Template key (e.g., `nextjs-basic-app`, `wordpress`).

### Example Response
```json
{
  "success": true,
  "project": {
    "id": "uuid-project",
    "name": "New Project",
    "templateKey": "nextjs-basic-app",
    "createdAt": "2026-06-12T16:00:00.000Z",
    "updatedAt": "2026-06-12T16:00:00.000Z"
  },
  "repoUrl": "https://git.cobonaut.com/username/uuid-project.git"
}
```

---

## 3. Trigger Deployment (Deploy)
Triggers the code update and build procedure on the CapRover cluster.

* **Method:** `POST`
* **URL:** `https://api.cobonaut.com/v1/deploy`
* **Content-Type:** `application/json`

### Request Body Parameters:
* `appName` (string, optional/required interchangeably with projectId) - Name of the CapRover application subdomain (e.g. "my-app").
* `projectId` (string, optional/required interchangeably with appName) - ID of the project.
* `commitSha` (string, optional) - SHA of the commit to deploy. If omitted, the endpoint retrieves the latest HEAD commit from the Gitea repository main branch.

### Example curl Request
```bash
curl -X POST https://api.cobonaut.com/v1/deploy \
  -H "Authorization: Bearer cobo_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "my-app"
  }'
```

### Example Response (HTTP 202 Accepted)
```json
{
  "message": "Rozpoczęto procedurę wdrożenia",
  "deploymentId": "uuid-deployment",
  "appName": "my-app",
  "status": "deploying",
  "commitSha": "4ca52ba47e668858f1be467d216738fd410b0123",
  "commitMessage": "chore: updates index page",
  "statusUrl": "https://cobonaut.com/api/deployments/uuid-deployment/status"
}
```

---

## 4. API Server Status (Healthcheck)
Public diagnostic endpoint for API server health status.

* **Method:** `GET`
* **URL:** `https://api.cobonaut.com/v1/health`

## Polish Version
# Dedykowany Interfejs API (api.cobonaut.com)

Cobonaut udostępnia zestaw publicznych endpointów REST ułatwiających integrację z zewnętrznymi systemami CI/CD, agentami AI (np. Antigravity) oraz skryptami.

Wszystkie zapytania muszą być uwierzytelnione za pomocą nagłówka:
```http
Authorization: Bearer cobo_live_[token]
```

---

## 1. Pobieranie listy projektów
Zwraca listę wszystkich Twoich projektów.

* **Metoda:** `GET`
* **URL:** `https://api.cobonaut.com/v1/projects`

### Przykład odpowiedzi
```json
{
  "success": true,
  "projects": [
    {
      "id": "uuid-projektu-1",
      "name": "Moja Aplikacja",
      "templateKey": "nextjs-basic-app",
      "createdAt": "2026-06-12T16:00:00.000Z",
      "updatedAt": "2026-06-12T16:00:00.000Z"
    }
  ]
}
```

---

## 2. Tworzenie nowego projektu
Zakłada nowy projekt i automatycznie inicjalizuje repozytorium kodu z wybranego szablonu. Zwraca również adres URL do repozytorium Gitea.

* **Metoda:** `POST`
* **URL:** `https://api.cobonaut.com/v1/projects`
* **Content-Type:** `application/json`

### Parametry w body:
* `name` (string, wymagany) - Nazwa projektu.
* `templateKey` (string, wymagany) - Klucz szablonu (np. `nextjs-basic-app`, `wordpress`).

### Przykład odpowiedzi
```json
{
  "success": true,
  "project": {
    "id": "uuid-projektu",
    "name": "Nowy Projekt",
    "templateKey": "nextjs-basic-app",
    "createdAt": "2026-06-12T16:00:00.000Z",
    "updatedAt": "2026-06-12T16:00:00.000Z"
  },
  "repoUrl": "https://git.cobonaut.com/nazwa_uzytkownika/uuid-projektu.git"
}
```

---

## 3. Wywołanie wdrożenia (Deploy)
Wywołuje procedurę aktualizacji kodu na serwerze CapRover.

* **Metoda:** `POST`
* **URL:** `https://api.cobonaut.com/v1/deploy`
* **Content-Type:** `application/json`

### Parametry w body:
* `appName` (string, opcjonalny/wymagany zamiennie z projectId) - Nazwa subdomeny aplikacji (np. "moja-aplikacja").
* `projectId` (string, opcjonalny/wymagany zamiennie z appName) - ID projektu.
* `commitSha` (string, opcjonalny) - SHA commitu do wdrożenia. W przypadku braku – pobiera najnowszy commit HEAD z gałęzi main repozytorium Gitea.

### Przykład zapytania curl
```bash
curl -X POST https://api.cobonaut.com/v1/deploy \
  -H "Authorization: Bearer cobo_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "moja-aplikacja"
  }'
```

### Przykład odpowiedzi (HTTP 202 Accepted)
```json
{
  "message": "Rozpoczęto procedurę wdrożenia",
  "deploymentId": "uuid-wdrozenia",
  "appName": "moja-aplikacja",
  "status": "deploying",
  "commitSha": "4ca52ba47e668858f1be467d216738fd410b0123",
  "commitMessage": "chore: updates index page",
  "statusUrl": "https://cobonaut.com/api/deployments/uuid-wdrozenia/status"
}
```

---

## 4. Diagnostyka statusu serwera API (Healthcheck)
Publiczny endpoint diagnostyczny statusu serwera API.

* **Metoda:** `GET`
* **URL:** `https://api.cobonaut.com/v1/health`


---
# Section: Automation & AI Agents (Automatyzacja i Agenci AI)
Category: api
ID: agent-flow

## English Version
# AI Agent & CLI Integration

This process allows developers utilizing terminal CLI or coding agents (like Antigravity) to modify code locally, push it to Gitea, and remotely deploy it to production.

### 1. Clone the Gitea Repository
Fetch the project files locally from the Gitea server:
```bash
git clone https://git.cobonaut.com/user_cobonaut/[project-id].git
```

### 2. Modify & Push Changes
Make adjustments in your code (e.g. edit HTML/CSS). Create a commit and push to Gitea:
```bash
git add .
git commit -m "feat: updates hero section"
git push origin main
```

### 3. Trigger the Deployment via REST API
Call the dedicated REST API deploy endpoint on `api.cobonaut.com` with your API token to start building the container:
```http
POST https://api.cobonaut.com/v1/deploy
Authorization: Bearer cobo_live_[token]
Content-Type: application/json

{
  "appName": "tst-apka-nanan"
}
```

### 4. Track Build Status (Polling)
The CLI script or AI Agent periodically polls the status URL returned in the response under `statusUrl` (every 3-5s) until the build finishes:
```http
GET https://cobonaut.com/api/deployments/[deployment-id]/status
```

## Polish Version
# Integracja z Agentami AI i CLI

Zintegrowany proces pozwala programistom korzystającym z terminala oraz agentów AI (takich jak Antigravity) na modyfikowanie kodu lokalnie, wypychanie zmian bezpośrednio na Gitea i zdalne wdrażanie ich na środowisko produkcyjne.

### 1. Klonowanie repozytorium Gitea
Pobierz kod projektu lokalnie ze swojego serwera Gitea:
```bash
git clone https://git.cobonaut.com/user_cobonaut/[project-id].git
```

### 2. Edycja i wypchnięcie zmian
Wprowadź poprawki w kodzie (np. dodaj nowy element UI). Następnie utwórz commit i zrób push do Gitea:
```bash
git add .
git commit -m "feat: updates hero section"
git push origin main
```

### 3. Wywołanie API wdrożenia
Wywołaj dedykowany endpoint wdrożeń REST API na `api.cobonaut.com` przy użyciu swojego tokenu API, aby rozpocząć budowanie kontenera:
```http
POST https://api.cobonaut.com/v1/deploy
Authorization: Bearer cobo_live_[token]
Content-Type: application/json

{
  "appName": "tst-apka-nanan"
}
```

### 4. Odpytywanie o status (Polling)
Narzędzie CLI / Agent AI odpytuje cyklicznie URL statusu uzyskany z odpowiedzi `statusUrl` (co 3-5 sekund), aż do momentu ukończenia budowania kontenera:
```http
GET https://cobonaut.com/api/deployments/[deployment-id]/status
```