# Galon Deploy

> Put a site online from a folder or a GitHub commit: an isolated build, a private preview, then production on your domain.

## Before you start

- A Galon account, a **test** project and a **test** key with `deploy:create` and `job:read`. Previews are made with test keys only; a live key sees no preview (`404`).
- Production (your own domain) needs a **live** key and a production plan.

## Quickstart

Every example reads `GALON_API_BASE` (`https://api.galon.ai/v1`) and `GALON_API_KEY` from the environment and prints the HTTP status and the JSON body.

**1. Set your key.** Export the base URL and your test key.

**curl**

```bash
export GALON_API_BASE="https://api.galon.ai/v1"
export GALON_API_KEY="gln_test_..."
```

**2. Upload your site.** Send the files as JSON (`files`: path → text) or the raw archive (zip, tar or tar.gz). `index.html` is required at the root. The `Idempotency-Key` must have 16 to 128 characters. The answer is `201` with a preview **journey**.

**curl**

```bash
curl -sS -X POST "$GALON_API_BASE/deploy/archives" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Idempotency-Key: quickstart-site-000001" \
  -H "Content-Type: application/json" \
  -d '{"files": {"index.html": "<!doctype html><title>Hello</title><h1>Hello from Galon</h1>"}}' \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/deploy/archives",
    data=json.dumps({"files": {"index.html": "<!doctype html><title>Hello</title><h1>Hello from Galon</h1>"}}).encode(),
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"],
             "Idempotency-Key": "quickstart-site-000001",
             "Content-Type": "application/json"},
    method="POST",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/deploy/archives`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}`, "Idempotency-Key": "quickstart-site-000001", "Content-Type": "application/json" },
  body: JSON.stringify({files: {"index.html": "<!doctype html><title>Hello</title><h1>Hello from Galon</h1>"}}),
});
console.log(res.status, JSON.stringify(await res.json()));
```

**MCP (JSON-RPC over HTTP)**

```bash
curl -sS -X POST "$GALON_API_BASE/mcp" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "deploy_archive", "arguments": {"idempotency_key": "quickstart-site-000001", "files": {"index.html": "<!doctype html><title>Hello</title><h1>Hello from Galon</h1>"}}}}' \
  -w '\n%{http_code}\n'
```

**3. Advance it to a live preview.** Each `resume` runs one step (build, scan, preview…). `202` with `Retry-After` means the step is still running: call again after the delay, until `journey.status` is `ready` (or `failed`, with `journey.error`). The answer that reaches `ready` carries `preview_access_token`, **once**.

**curl**

```bash
curl -sS -X POST "$GALON_API_BASE/deploy/journeys/${GALON_JOURNEY_ID}/resume" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -w '\n%{http_code}\n'   # repeat while it answers 202
```

**Python 3 (standard library)**

```python
import json, os, time, urllib.error, urllib.request

url = os.environ["GALON_API_BASE"] + "/deploy/journeys/" + os.environ["GALON_JOURNEY_ID"] + "/resume"
for _ in range(30):  # one step per call; 202 means the step is still running
    req = urllib.request.Request(url, method="POST",
                                 headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]})
    try:
        with urllib.request.urlopen(req) as res:
            status, body = res.status, json.load(res)
            wait = int(res.headers.get("Retry-After") or 1)
    except urllib.error.HTTPError as err:
        print(err.code, json.load(err))
        break
    journey = body["journey"]
    if journey["status"] in ("ready", "failed"):
        print(status, body)  # keep preview_access_token: it is shown once
        break
    time.sleep(wait)
```

**Node.js 18+ (fetch)**

```js
const url = `${process.env.GALON_API_BASE}/deploy/journeys/${process.env.GALON_JOURNEY_ID}/resume`;
for (let i = 0; i < 30; i++) { // one step per call; 202 means the step is still running
  const res = await fetch(url, { method: "POST", headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}` } });
  const body = await res.json();
  if (!res.ok || ["ready", "failed"].includes(body.journey?.status)) {
    console.log(res.status, JSON.stringify(body)); // keep preview_access_token: shown once
    break;
  }
  await new Promise((r) => setTimeout(r, 1000 * Number(res.headers.get("retry-after") || 1)));
}
```

**MCP (JSON-RPC over HTTP)**

```bash
curl -sS -X POST "$GALON_API_BASE/mcp" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "advance_deploy", "arguments": {"id": "'"$GALON_JOURNEY_ID"'"}}}' \
  -w '\n%{http_code}\n'
```

**4. Open the preview.** `journey.preview.url` is private: send the token as `Authorization: Bearer <preview_access_token>` (or as the password of Basic authentication in a browser). It expires at `journey.preview.expires_at`.

**curl**

```bash
curl -sS -X GET "$GALON_API_BASE/deploy/journeys/${GALON_JOURNEY_ID}" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/deploy/journeys/" + os.environ["GALON_JOURNEY_ID"],
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]},
    method="GET",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/deploy/journeys/${process.env.GALON_JOURNEY_ID}`, {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}` },
});
console.log(res.status, JSON.stringify(await res.json()));
```

**MCP (JSON-RPC over HTTP)**

```bash
curl -sS -X POST "$GALON_API_BASE/mcp" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_deploy", "arguments": {"id": "'"$GALON_JOURNEY_ID"'"}}}' \
  -w '\n%{http_code}\n'
```

## Concepts

**Journeys.** A deploy is a journey of steps: source, plan, build, scan, preview (then domain and cost). `status` is `pending`, `ready`, `failed`, `exported` or `deleted`; `current_stage` and `steps` say where it is. Nothing advances by itself: you (or the CLI, or your agent) call `resume`.

**Two sources.** **Archive**: `POST /v1/deploy/archives`, no repository needed (CLI: `galon deploy ./dist`). **GitHub**: connect the repository in the console (it gives an `ins_…` id), then `POST /v1/deploy/journeys` with `intention: {installation_ref, repository, commit_sha (40 hex), root_path, domain}` and `expires_at`. Both then advance with `resume`.

**Previews are private.** A preview answers only with its token. Its lifetime is at most 7 days (`expires_at`); an archive defaults to 00:00 UTC four days later.

**Production.** With a **live** key and a plan: `POST /v1/deploy/production/plan`, add a domain (`POST /v1/deploy/production/domains`, then publish the TXT proof and the CNAME or A records it returns, then `…/verify`), `POST /v1/deploy/production/promote` with the verified preview `journey_id`, and `POST /v1/deploy/production/rollback` to switch back to the previous release.

**Idempotency.** `POST /v1/deploy/archives` and `POST /v1/deploy/journeys` require an `Idempotency-Key` (16 to 128 characters): the same key and content return the same journey (`200`, `replayed: true`).

**One call.** Send `Prefer: wait=20` on `POST /v1/deploy/archives` or `/journeys`: the steps run inside the request (20 s at most) and the response carries the preview, its `preview_access_token` and `wait.outcome`; if `outcome` is not `ready`, continue with `…/resume`.

## API reference

Derived from the OpenAPI 3.1 contract at each request: every operation of Galon Deploy you can reach today, with its full page (parameters, bodies, responses, examples). Base URL: the public API endpoint, `$GALON_API_BASE`.

| Method | Path | Summary |
|---|---|---|
| POST | [`/v1/builds`](/cloud/docs/api/builds) | Build a web application |
| GET | [`/v1/builds/{job_id}`](/cloud/docs/api/builds-job_id) | Get a build |
| POST | [`/v1/builds/{job_id}/cancel`](/cloud/docs/api/builds-job_id-cancel) | Cancel a build before it starts |
| GET | [`/v1/builds/{job_id}/artifacts`](/cloud/docs/api/builds-job_id-artifacts) | List a build's artefacts |
| POST | [`/v1/deploy/archives`](/cloud/docs/api/deploy-archives) | Deploy a static site from an archive (preview) |
| GET | [`/v1/deploy/journeys`](/cloud/docs/api/deploy-journeys) | List preview deployments |
| POST | [`/v1/deploy/journeys`](/cloud/docs/api/deploy-journeys) | Start a preview deployment |
| GET | [`/v1/deploy/journeys/{journey_id}`](/cloud/docs/api/deploy-journeys-journey_id) | Get a deployment |
| POST | [`/v1/deploy/journeys/{journey_id}/resume`](/cloud/docs/api/deploy-journeys-journey_id-resume) | Advance a deployment by one step |
| GET | [`/v1/deploy/journeys/{journey_id}/build-logs`](/cloud/docs/api/deploy-journeys-journey_id-build-logs) | Get the build log |
| GET | [`/v1/deploy/runtime/{instance_id}/logs`](/cloud/docs/api/deploy-runtime-instance_id-logs) | Get the runtime log (server rendering) |
| GET | [`/v1/deploy/env`](/cloud/docs/api/deploy-env) | Get environment variables |
| GET | [`/v1/deploy/production/plans`](/cloud/docs/api/deploy-production-plans) | List production plans |
| GET | [`/v1/deploy/production/status`](/cloud/docs/api/deploy-production-status) | Get the production status |
| POST | [`/v1/deploy/production/plan`](/cloud/docs/api/deploy-production-plan) | Choose a production plan |
| POST | [`/v1/deploy/production/domains`](/cloud/docs/api/deploy-production-domains) | Attach a custom domain |
| POST | [`/v1/deploy/production/domains/{domain}/verify`](/cloud/docs/api/deploy-production-domains-domain-verify) | Verify a custom domain |
| DELETE | [`/v1/deploy/production/domains/{domain}`](/cloud/docs/api/deploy-production-domains-domain) | Detach a custom domain |
| POST | [`/v1/deploy/production/promote`](/cloud/docs/api/deploy-production-promote) | Promote a preview to production |
| POST | [`/v1/deploy/production/rollback`](/cloud/docs/api/deploy-production-rollback) | Roll back to the previous release |
| DELETE | [`/v1/deploy/journeys/{journey_id}/preview`](/cloud/docs/api/deploy-journeys-journey_id-preview) | Delete a preview |

## Errors

Every error is JSON: `{"detail": {"code", "message", "next_action"}}`. `next_action.code` is stable, `next_action.hint` says what to do next, and `console_url` is added when a person must act. The codes below are those this service returns.

| Status | Code | When | next_action |
|---|---|---|---|
| 404 | `not_found` | A live key on a preview route, or Deploy not open to the account. | `check_resource_id` |
| 403 | `scope_missing` | The key lacks `deploy:create` (writes) or `job:read` (reads). | `add_missing_scope` |
| 403 | `deploy_tenant_not_allowed` | Deploy is not open to this account. | `check_project_access` |
| 400 | `idempotency_key_invalid` | Missing key, or not 16 to 128 characters of `[A-Za-z0-9._:-]`. | `fix_request` |
| 400 | `body_fields_invalid` | Not exactly one of `files` / `archive_base64`, or an unknown field. | `fix_request` |
| 400 | `query_invalid` | A query parameter other than `expires_at` (raw archive only). | `fix_request` |
| 415 | `content_type_invalid` | Neither JSON nor an archive type. | `fix_request` |
| 413 | `deploy_archive_too_large` | Over 25 MiB uploaded (1 MiB for a JSON body). | `fix_request` |
| 413 | `deploy_archive_too_many_files` | More than 512 files. | `fix_request` |
| 413 | `deploy_archive_file_too_large` | One file over 2 MiB. | `fix_request` |
| 422 | `deploy_archive_index_missing` | No `index.html` at the root. | `fix_request` |
| 422 | `deploy_archive_path_invalid` | An absolute path, `..`, `\` or a `.git` segment. | `fix_request` |
| 422 | `deploy_archive_link_refused` | A symbolic or hard link in the archive. | `fix_request` |
| 422 | `deploy_archive_format_invalid` | Not a readable zip, tar or tar.gz. | `fix_request` |
| 422 | `journey_preview_expiry_invalid` | `expires_at` in the past or more than 7 days ahead. | `fix_request` |
| 429 | `deploy_archive_quota_exceeded` | Too many archives for this project (retry after the delay). | `raise_limit_or_plan` |
| 429 | `deploy_quota_daily_exceeded` | The free previews of the UTC day are used. | `raise_limit_or_plan` |
| 409 | `idempotency_conflict` | Same key, different content. | `resolve_conflict` |
| 404 | `deploy_journey_not_found` | No journey with this id for this key. | `check_resource_id` |
| 403 | `deploy_production_live_key_required` | A production write with a test key. | `check_project_access` |
| 402 | `deploy_plan_required` | Production without a plan. | `choose_plan` |
| 402 | `deploy_plan_balance_insufficient` | The balance does not cover the plan. | `top_up_balance` |
| 409 | `deploy_production_preview_not_verified` | Promoting a preview that is not verified. | `resolve_conflict` |
| 403 | `deploy_domain_pending_limit_reached` | Too many domains waiting for verification. | `raise_limit_or_plan` |
| 503 | `deploy_temporarily_unavailable` | Temporary: retry with the same Idempotency-Key. | `retry_later` |

| next_action | What to do |
|---|---|
| `check_resource_id` | Nothing with this id is visible to this key. List the resources to get a valid id, and check that the key belongs to the right project and environment (test or live). |
| `add_missing_scope` | This key does not have the scope this call needs. Create a key with that scope in the console, then retry the same call with the new key. |
| `check_project_access` | This project or key is not allowed to do this. Its owner must review the project, its key and its account in the console. |
| `fix_request` | The request is invalid. Fix it as 'message' and 'field' say, using the OpenAPI contract, then send it again. Do not retry it unchanged. |
| `raise_limit_or_plan` | A plan quota or a spending limit is reached. Raise the limit or change the plan in the console, or wait for the next period, then retry. |
| `resolve_conflict` | The request conflicts with the resource state or with an earlier request under the same Idempotency-Key. Read the resource first; for a new intent, use a new Idempotency-Key. |
| `choose_plan` | This service needs a paid plan. Choose a plan in the console, then retry. |
| `top_up_balance` | The project balance does not cover this call. Top up the balance in USD in the console, then retry with the same Idempotency-Key. |
| `retry_later` | Temporary error on Galon's side. Retry with exponential backoff and the same Idempotency-Key; if it lasts, contact support with the X-Request-Id header. |

## Limits, free tier and pricing

Read from the platform code each time this page is served.

| Limit | Value |
|---|---|
| Free preview deploys per account and UTC day | **10** |
| Free preview builds running at once per account (the next one waits) | **1** |
| Builds running at once on the shared builders (first come, first served) | **2** |
| Dependency install time | **10 min** |
| Build time | **15 min** |
| Total time of a build | **20 min** |
| CPU per build | **2 vCPU** |
| Memory per build | **3 GiB** |
| Workspace per build (counted in memory) | **1,536 MiB** |
| Processes per build | **512** |
| Dependency cache per project (emptied beyond) | **1 GiB** |
| Build log lines kept | **20,000** |
| Archive uploaded | **25 MiB** |
| Files per archive | **512** |
| One file in an archive | **2 MiB** |
| Content of an archive, in total | **10 MiB** |

Preview deploys are free (within the limits above). Production needs a plan, paid from your prepaid balance every 30 days, in USD:

| Plan | Price | Domains | Traffic | Builds |
|---|---|---|---|---|
| `site` | 3.00 USD | 1 | 100 GB | 300 |
| `pro` | 15.00 USD | 10 | 1000 GB | unlimited |

Usage beyond a plan is billed to your balance as you go: 0.11 USD per GB and 0.011 USD per build (USD). Your site stays online; without balance the amount waits.

`GET /v1/deploy/production/plans` returns this same grid.

## FAQ

**Do I need a GitHub repository?**

No. Upload a folder (`galon deploy ./dist`) or a zip, tar or tar.gz with `POST /v1/deploy/archives`.

**Why does my live key get 404 on previews?**

Previews belong to test projects: use a test key. Live keys are for production writes.

**Why is my preview not public?**

Previews are private by design: open them with the preview access token.

**Can I deploy a server-side app?**

Yes, from a repository build: a Next.js app (server rendering, API routes, middleware) runs as a Node server when the server runtime is on for your account. A folder or an archive is served as a static site.

**How do I roll back?**

`POST /v1/deploy/production/rollback` switches production back to the previous release without a new build.

## More

- [Authentication](/cloud/docs/platform/authentication)
- [Projects: live and test](/cloud/docs/platform/environments)
- [Prepaid balance](/cloud/docs/platform/balance)
- [Quotas and rate limits](/cloud/docs/platform/quotas)
- [Terms of Service](/legal/terms-of-service)
- [Acceptable Use Policy](/legal/acceptable-use-policy)
- [Privacy Policy](/legal/privacy-policy)
- [Refunds and prepaid balance](/legal/prepaid-balance-and-refund-policy)
- [Legal Notice](/legal/legal-notice)
- [All legal documents](/legal)
