AI SPACE

View saved version →

---
name: deploy-existing-code
description: Check code the user already wrote against Cafe24 AI SPACE's platform constraints, fix what would break, then deploy or update it. Use when the user brings existing code — from another AI tool, a local folder, or a GitHub repository — and wants it published or wants an existing AI SPACE project updated. Do not use when the app should be written from scratch (use deploy-new-app).
---

# Deploy code the user already has

Code written elsewhere usually violates one or two platform rules. **Check first,
fix, then deploy.** Deploying straight away wastes a build — and on a free trial
builds are a limited resource.

Reply in the user's language.

## Expected input

Files the user attached, a GitHub repository, or a public Git URL. If it is not
clear which, ask once.

## Step 1 — Pre-flight check

Work through `references/preflight-checklist.md`. Then show the user two lists
before you deploy anything:

```
Fixed
  • server.js now listens on 0.0.0.0:3000 (was 127.0.0.1:8080)
  • database config now reads DB_USER instead of a hard-coded password
  • removed Dockerfile

Left as-is
  • the SQLite file path — tell me if this data must survive redeploys
```

If the stack is Go, Java or Rust, stop here. Those runtimes do not exist on the
platform. Say so plainly and describe what rewriting would involve.

## Step 2 — Choose the path

### The user is deploying something new

Reserve a space first: `list_my_spaces`, and use one where `project_id` is
`null`. If none is free, stop and say so.

**Files attached in chat.** ChatGPT has no shell, so always use the JSON upload
path: `project_upload` with `action: "create_session"` and `mode: "json"`, then
`upload_json`, then `project_upload` with `action: "finalize"`, `deploy: true`
and the `space_id`. Limits are 3 MB per file, 10 files per request, 5 MB total.

**Too large for those limits, or a real repository.** Do not shard the upload.
Use `external_repo` with `repo_connect` to link the user's GitHub account, then
`repo_deploy`. For a public repository with no account linking, `deploy_project`
with the HTTPS Git URL works.

### The user is updating an existing project

**Always call `get_project_status` first and read the `source` field.** Calling
the wrong update tool returns `SOURCE_MISMATCH`.

| `source` | How the project was created | What to call |
|---|---|---|
| `internal` | uploaded files, or a public Git URL | `project_upload` with `update: true`, then `update_project` |
| `github` | linked GitHub repository | `external_repo` → `repo_update`, or `repo_write_file` for a single file |

`update_project` accepts only `project_id`, `rebuild` and `wait`. Parameters like
`mode` or `reset` do not exist.

When one repository is deployed to more than one project, `external_repo` returns
`AMBIGUOUS_PROJECT`. Call `list_my_projects` and pass the exact `project_name`.

## Step 3 — Watch and verify

Call with `wait: false`, poll `get_project_status`, and tick only the steps you
have actually seen succeed. Then call `site_verify` on the project URL — a
successful build is not proof that the site answers.

If the build fails, hand off to the troubleshooting workflow rather than
retrying. Read the logs before changing anything.

## Rules you must not break

- **Stop after two identical failures.** Never retry in a loop.
- **Do not use `force: true`.** If the target space is occupied, offer a
  different project name, an update of the existing project, or deletion through
  the web console.
- An update recreates the application container. Database contents and
  `/app/user_data/` are preserved; anything else in the app directory is not.
- Rollback, deletion, power control and billing are not available here. Direct
  the user to the Cafe24 web console.

## Do not infer

Plan limits, prices and free-trial build quotas change. Do not quote them from
memory — point the user to `https://aispacedocs-docs.mycafe24.ai`.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: deploy-new-app
description: Build a web application from the user's description and deploy it live on Cafe24 AI SPACE. Use when the user wants a new site, page, or app created and published — for example "make me a coffee shop homepage and put it online", "build a simple booking form and deploy it", or "I need a landing page for my product". Do not use when the user already has code to upload (use deploy-existing-code) or when a deployment has already failed (use troubleshoot-deploy).
---

# Deploy a new app on Cafe24 AI SPACE

You write the code, then publish it with the AI SPACE tools. The platform handles
the container, the domain and the SSL certificate. Reply in the user's language.

## Expected input

A description of what the user wants. If the description is one line, do not
interrogate them — pick sensible defaults, build it, and let them refine it after
they can see the live site.

## Steps

### 1. Reserve a space

Call `list_my_spaces`. A space is deployable when `project_id` is `null`.

- No empty space → stop. Tell the user to free one or add a space in the Cafe24
  web console. Do not try to deploy into an occupied space.
- Exactly one empty space → use it.
- More than one → ask which one, then pass its `space_id`.

### 2. Choose the runtime yourself

Decide from what the user asked for. Do not ask them.

| What they want | Runtime | Entry file that must exist at the repo root | Port your code must listen on |
|---|---|---|---|
| Landing page, brochure site, portfolio | Static (Nginx) | `index.html` | n/a |
| API, Express or Next.js app | Node.js 20 | `package.json` | **3000**, host `0.0.0.0` |
| FastAPI, Flask or Django app | Python 3.11 | `requirements.txt` | **8000**, host `0.0.0.0` |
| PHP app, board, WordPress-style site | PHP 8.2 (Apache) | `composer.json` or `index.php` | n/a |

Go, Java and Rust are **not supported**. If asked, say so and offer one of the
four above.

### 3. Write the code under the platform's rules

Read `references/runtime-rules.md` before writing files. The four rules that
break deployments most often:

1. Never create `Dockerfile`, `docker-compose.yml`, or Nginx/Apache config files.
2. Never write database credentials. The server injects `DB_HOST`, `DB_PORT`,
   `DB_NAME`, **`DB_USER`** (not `DB_USERNAME`), `DB_PASSWORD`. Read them only.
3. Anything that must survive a redeploy goes under `/app/user_data/`.
4. Node listens on 3000, Python on 8000, both on `0.0.0.0`.

Pick a `project_name` that describes the site only — for example `coffeeshop`.
Never put the user's account ID in it; the server prefixes it automatically.

### 4. Upload the files

**You are running inside ChatGPT, which has no shell. Always use the JSON path.**

1. `project_upload` with `action: "create_session"`, `mode: "json"`, the file list
   and the repo name. The mode is locked at this moment and cannot be changed
   afterwards — a new session is required to switch.
2. `upload_json` with the returned `batch_id`. Limits: **3 MB per file, 10 files
   per request, 5 MB total.** Send text files as plain text with no `encoding`
   field. Only binary files get `encoding: "base64"`.
3. `project_upload` with `action: "finalize"`, `deploy: true`, and the `space_id`
   from step 1.

If the project is larger than those limits, do not try to split it endlessly.
Tell the user and offer the two alternatives: connect a GitHub repository with
`external_repo`, or deploy from a public Git URL with `deploy_project`.

On a failed upload: a 4xx means stop immediately, a 5xx is worth one or two
retries, a timeout is worth one. **Every retry starts from a new
`create_session`** — never reuse a `batch_id` whose first attempt failed.

### 5. Report progress honestly

Call with `wait: false` and poll `get_project_status` every 5–10 seconds. Show a
checklist and tick only what you have actually observed in a response. Never mark
a step complete because you assume it finished.

```
[AI SPACE deploy — coffeeshop]
✅ 1/4 files uploaded
✅ 2/4 runtime detected: Node.js 20
⏳ 3/4 building and starting…
⬜ 4/4 domain and SSL
```

### 6. Confirm it is actually reachable

A successful deployment is not the same as a reachable site. Call `site_verify`
on `https://{account}-{project}.mycafe24.ai` before you tell the user it is live.
Then give them the URL.

## Rules you must not break

- **Stop after two identical failures.** If the same call fails the same way
  twice, stop and report. Never loop — on a free trial each build consumes one of
  a limited number of builds.
- **Do not use `force: true`.** If a space is occupied, offer a different project
  name, an update of the existing project, or deletion in the web console.
- Never put an API key or any secret into client-side JavaScript on a static
  site. Every visitor can read it. Use a server runtime and environment variables.
- Rollback, project deletion, power control and billing are **not available
  through this connector.** Direct the user to the Cafe24 web console.

## Do not infer

Free-trial limits, prices, plan quotas and refund policy change. Do not state
them from memory — point the user to `https://aispacedocs-docs.mycafe24.ai`.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: operate-project
description: Run day-to-day operations on a project already deployed on Cafe24 AI SPACE — review status and spaces, set or remove environment variables, create a backup, restrict access by IP or country, and add or remove Redis and Memcached. Use when the user asks what they have running, wants to change a setting, take a backup, or block traffic. Do not use for deploying or updating code, or for diagnosing a failure.
---

# Operate a deployed project

Reply in the user's language.

## Find the project first

`list_my_projects` shows what the user has. `list_my_spaces` shows their spaces
with specification, quota, connection limit and whether each one is occupied.
`get_project_status` gives runtime, resource usage and deployment history for a
single project.

If the user names a project ambiguously, list what exists and ask. Never guess
which project a destructive setting applies to.

## Confirm before you change anything

Read-only calls go straight through. **Anything that changes state follows the
same three beats every time:**

1. Name the project explicitly.
2. Summarise what will change.
3. Ask "shall I go ahead?" and wait.

## What you can do here

### Environment variables — `project_env`

`get` lists them, `set` creates or updates, `delete` removes one key.

These are the application's own configuration values. Database and Redis
credentials are injected and protected by the server — do not try to set them,
and tell the user they are already available to their code.

A change restarts the container in place. It takes effect in seconds and does not
require a redeploy.

### Backups — `backup_project`

The project must be in `success` state. The backup contains the application
files, everything under `/app/user_data/`, and an automatic dump of any MySQL or
PostgreSQL database attached to the project.

The response carries `backup_download_url`. **Give that URL to the user as-is and
tell them it expires** — retention differs between free and paid plans, so point
them at the documentation rather than quoting a number.

### Access control — `project_acl`

| Action | Effect |
|---|---|
| `set_ip` with `mode: "deny"` | blocks that IP or CIDR range |
| `set_ip` with `mode: "allow"` | blocks **everyone except** that IP |
| `set_geo` | blocks a country by ISO 3166-1 code, either all requests or POST only |
| `clear_ip` / `clear_geo` | removes the rules |
| `get_acl` | shows what is currently in force |

**Warn before an allow rule.** Whitelist mode blocks every address that is not
listed — including the user's own, if their address changes or they are on
mobile. Confirm they understand they may lock themselves out, and tell them
`clear_ip` is the way back.

### Add-ons — `project_option`

Adds or removes Redis and Memcached on Pod-mode projects.

**Removing an add-on deletes everything stored in it, and re-adding gives an
empty instance.** Say that before you call it, and confirm.

### Importing a database — `import_database` then `finalize_db_import`

`import_database` opens an upload session and returns a URL. Nothing is written
yet. After the `.sql` or `.sql.gz` file is uploaded, `finalize_db_import` applies
it.

**Applying a dump can drop and overwrite existing tables. It cannot be undone.**
Offer to take a backup first, then get explicit confirmation.

### Custom domains

Available on paid plans. SSL is issued free and automatically when the domain is
connected — the user does not buy a certificate. DNS propagation can take up to
48 hours. For the current limits per account and per project, point to the
documentation.

## What is not available through this connector

Rollback, project deletion, power on/off, plan changes and payment are not
exposed here. Do not attempt a workaround. Direct the user to the Cafe24 web
console: Hosting → My Service Management → AI SPACE console.

## Do not infer

Prices, plan quotas, backup retention periods, free-trial limits and domain
counts all change. Never state them from memory. Point the user to
`https://aispacedocs-docs.mycafe24.ai`.

## Stop rule

If the same call fails the same way twice, stop and report it. Do not retry in a
loop.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: troubleshoot-deploy
description: Diagnose a Cafe24 AI SPACE deployment that failed, a site that returns an error or will not open, or a connector that reports an authorization error. Use when the user says the build failed, the page is blank or 500, the database will not connect, uploaded files disappeared, or a tool call keeps failing. Do not use for a first deployment that has not been attempted yet.
---

# Diagnose a failed deployment

**Read the evidence before you change anything.** Most failures here have a
known cause, and a blind retry costs the user one of a limited number of builds.

Reply in the user's language.

## The stop rule comes first

If the same call has already failed the same way twice, do not call it a third
time. Stop, report what you saw, and work out the cause with the user.

Never treat an authorization error as a code problem. Fixing code will not fix
authentication, and you will burn build quota discovering that.

## Step 1 — Gather

1. `get_project_status` — is the state `success`, `failed`, or still building?
   Note the `runtime` and the `source` field.
2. `get_project_logs` — the build and runtime log. This is where the real cause
   is. Read it before forming a theory.
3. `site_verify` on the project URL if the deployment reports success but the
   user says the page does not load.

Deployment success and site reachability are two different things. Check them
separately.

## Step 2 — Match against the known causes

Work through `references/failure-catalog.md`. In order of how often each one is
the actual answer:

1. A `Dockerfile` or `docker-compose.yml` in the repository
2. The app bound to `127.0.0.1`, or to the wrong port (Node must use 3000,
   Python 8000, both on `0.0.0.0`)
3. `DB_USERNAME` used instead of `DB_USER`
4. A missing entry file at the repository root, so the runtime was misdetected
5. A dependency that fails to install, or a syntax error — visible in the log
6. Files written outside `/app/user_data/`, so they vanished on redeploy
7. Memory exhausted during the build

## Step 3 — Explain, fix, redeploy once

Tell the user what the log actually said, in plain language, before proposing a
fix. Then make the change and redeploy **once**. If it fails again for a
different reason, repeat this workflow. If it fails again for the same reason,
stop.

Before any redeploy of an existing project, check `source` with
`get_project_status`:

- `source: "internal"` → `project_upload` with `update: true`, then
  `update_project`
- `source: "github"` → `external_repo` with `repo_update` or `repo_write_file`

Calling the wrong one returns `SOURCE_MISMATCH`.

## Authorization errors

If a tool call returns an authorization or re-authorization error, this is not a
deployment problem and there is nothing to fix in the code.

Tell the user to reconnect the AI SPACE plugin in ChatGPT's settings and sign in
to their Cafe24 account again. Do not send them to a login page inside the
product — the connector's own authorization flow is what needs to run.

After two consecutive authorization failures, stop and report rather than
retrying.

## The build failed but the site still works

That is expected. A failed build leaves the previous version running. The user
has not lost their live site — say so, because the failure message alone reads
as though everything is down.

## What you cannot do here

Rollback, project deletion and power control are not available through this
connector. If recovery needs one of those, direct the user to the Cafe24 web
console: Hosting → My Service Management → AI SPACE console.

## Do not infer

Build quotas, plan limits and retention periods change. Do not quote numbers from
memory — point the user to `https://aispacedocs-docs.mycafe24.ai`.

Referenced files: 2 — file references are metadata, not package contents.