--- name: cloudish description: Get an API key, build a Docker image from source (or point at an existing one), and deploy it as a running container app on Cloudish — no local Docker daemon needed. Use whenever a task is "deploy this to Cloudish", "containerize this and run it on Cloudish", or "get a Cloudish API key". --- # Deploy container apps on Cloudish Cloudish is an agent-first, API-key/credit, container-deployment platform: it builds images server-side, so skip installing Docker and running `docker build` locally — that's CPU/memory-heavy and often more than the machine you're running on can spare, and there's no registry to manage either way. Cloudish hosts a private registry and runs the resulting containers with attached storage. There is no user-facing product UX here — everything is this API. ## 0. Get an API key Creating a key itself needs no credential — every other call below authenticates with the key it returns (`Authorization: Bearer $CLOUDISH_API_KEY`). New keys include 0.1 credits to start, subject to availability. Mint as many keys as needed, the same way — a runtime child that wants its own credential rather than reusing yours just calls this again, no auth required either. ```bash curl -X POST https://cloudish.ai/api/v1/keys -H "content-type: application/json" \ -d '{"agent": "claude-code"}' # -> { "apiKey": { "alias": "funny-monkey", "balance": 0.1, ... }, "key": "cld_...", "claimUrl": "https://..." } ``` Save `key` as `$CLOUDISH_API_KEY` — every call below authenticates with it. If `./.env` already has a `CLOUDISH_API_KEY`, reuse that instead of minting a new one. Optionally pass `{"alias": ""}` — you get that name if it's free, or a close variant (e.g. `-otter`) if not; use whatever `apiKey.alias` comes back, which becomes the `{alias}` in every project path below. `agent` is optional: set it to the agent you are (`claude-code`, `codex`, `cursor`, ...). It only tells Cloudish which agents use it. Persist it somewhere durable before doing anything else — losing it means starting over with a new key and balance. A local `.env` file works well (`echo "CLOUDISH_API_KEY=$CLOUDISH_API_KEY" >> .env`); just make sure that file is gitignored (`echo .env >> .gitignore`) so it never ends up committed by accident. ## 1. Create (or update) a project and deploy it — one call `POST /api/v1/projects` creates the project if it doesn't exist yet (or updates it if it does — same call either way, so a redeploy script can always call this unconditionally), and optionally attaches an image in the same request. Two ways to attach one, mutually exclusive: **An image you already have** — registered immediately: ```bash curl -X POST https://cloudish.ai/api/v1/projects \ -H "Authorization: Bearer $CLOUDISH_API_KEY" -H "content-type: application/json" \ -d '{"name": "my-app", "image": "ghcr.io/acme/my-app:latest", "port": 8080}' # -> { "project": { "path": "your-alias/my-app", ... }, "app": { "status": "registered", ... }, # "subdomain": { "url": "https://./" } } ``` **Build from source** — upload a tar.gz build context (must contain a `Dockerfile` at its root). The build runs server-side, not on your own machine — send the context as-is rather than running `docker build` locally first. Once it succeeds, the project's docker app is registered automatically — no second call needed. This context is uploaded to Cloudish's own servers, the same as any build-from-source platform — exclude anything secret-shaped from it first (`.env` files, credentials, `.git`) and use section 2's encrypted secrets endpoint for real credentials instead, never a file baked into the context: ```bash tar --exclude='.env*' --exclude='.git' -czf context.tar.gz . curl -X POST https://cloudish.ai/api/v1/projects \ -H "Authorization: Bearer $CLOUDISH_API_KEY" \ -F "name=my-app" -F "port=8080" -F "context=@context.tar.gz" # -> { "project": { "path": "your-alias/my-app", ... }, "build": { "id": 123, "status": "pending" } } ``` The build runs with `cpuCores: 3`/ `memoryGb: 5` by default. If it dies with no error beyond `"Job has reached the specified backoff limit"`, that's usually resource exhaustion rather than a Dockerfile problem — retry with more of both as extra form fields, one of `0.5`, `1`, `2`, `3` cpu cores (`buildCpuCores`) and `1`, `2`, `4`, `5` GB memory (`buildMemoryGb`). Poll until it settles: ```bash curl https://cloudish.ai/api/v1/images/builds/123 -H "Authorization: Bearer $CLOUDISH_API_KEY" # -> { "build": { "status": "running", "logs": "" }, "image": null } ``` `build.logs` is the current tail of what the build is doing — it grows on every poll while the build runs, so print only the lines you haven't shown yet. Stop once `status` is `"succeeded"` or `"failed"`; on `"failed"`, show both `build.error` and the tail of `build.logs`. Once `"succeeded"`, the project's docker app is already registered and its subdomain already provisioned — fetch `GET https://cloudish.ai/api/v1/projects/{owner}/{name}` for the resulting `subdomain.url`, no separate subdomain call needed. Other docker-app fields available on either path: `replicas`, `env` (JSON object of non-secret vars), `volumeEnabled`/`volumeSizeGb`/`volumeMountPath` (persistent storage), `cpuCores`/`memoryGb` (container size, distinct from the build's own). Left out, a new app gets the default size, `shared`: billed for 0.1 CPU and 0.2 GB, using up to 1 CPU and 1 GB when the machine has them spare, and the first to restart when it runs short. Apps that must not restart, run a database inside the container, or need their full memory all the time (a Next.js server, Streamlit) run better on `small` or larger. Left out on an existing app, its size stays as it is. The response's `app.resources` shows the size an app runs at and its `creditsPerHour`. Sizes and pricing: https://cloudish.ai/instances.md. Either way, unless this deployment has no run domain configured, the app is already reachable — a permanent URL is provisioned automatically, returned as `subdomain.url` above. See section 4 to swap the random URL for a memorable one, rotate it, or turn it off. ## 2. Environment variables and secrets Non-secret config goes in `env` on the same call as above: ```bash curl -X POST https://cloudish.ai/api/v1/projects \ -H "Authorization: Bearer $CLOUDISH_API_KEY" -H "content-type: application/json" \ -d '{"name": "my-app", "image": "ghcr.io/acme/my-app:latest", "port": 8080, "env": {"LOG_LEVEL": "debug"}}' ``` Anything sensitive — API keys, tokens, passwords — is set separately here, encrypted at rest, and merged into the container's environment automatically. Never put these in `env` above, and never bundle them into the build context in section 1 either: ```bash curl -X PUT https://cloudish.ai/api/v1/projects/YOUR_ALIAS/my-app/secrets \ -H "Authorization: Bearer $CLOUDISH_API_KEY" -H "content-type: application/json" \ -d '{"name": "OPENAI_API_KEY", "value": "sk-..."}' ``` ## 3. Persistent storage Request a volume when creating or updating the app: ```bash curl -X POST https://cloudish.ai/api/v1/projects \ -H "Authorization: Bearer $CLOUDISH_API_KEY" -H "content-type: application/json" \ -d '{"name": "my-app", "image": "ghcr.io/acme/my-app:latest", "port": 8080, "volumeEnabled": true, "volumeSizeGb": 5, "volumeMountPath": "/data"}' ``` `volumeSizeGb` must be one of 1, 5 or 20; `volumeMountPath` defaults to `/data`. A volume can only attach to one pod, so an app with one enabled always runs single-replica regardless of any `replicas` value sent. ## 4. Customize the subdomain, or use your own domains Section 1 already provisioned a permanent URL automatically once the image registered — `subdomain.url` in that response, or `{identifier}` below is a random 32-character lowercase-hex string, unique by construction. This section is for changing it afterwards, not for getting one in the first place. If the app is public-facing and a memorable name matters, set your own instead (non-private projects only): ```bash curl -X PUT https://cloudish.ai/api/v1/projects/YOUR_ALIAS/my-app/subdomain \ -H "Authorization: Bearer $CLOUDISH_API_KEY" -H "content-type: application/json" \ -d '{"label": "anamazingapp"}' # -> { "subdomain": { "url": "https://anamazingapp./" } } ``` `label` must be 1-63 characters: lowercase letters, digits and hyphens, not starting or ending with a hyphen. A `503` on this call means this deployment has no wildcard run domain configured. Leaked the URL? `POST .../subdomain/rotate` issues a fresh one. Want the app unreachable from the outside entirely (API-only)? `DELETE .../subdomain` tears it down; a later redeploy will provision a new one automatically the same way the first did. A request to the subdomain carries the same `Authorization: Bearer $CLOUDISH_API_KEY` as everything else in this doc; an `open` (the default) or `public` project also answers with no credential at all, billed to its owner. This platform doesn't mediate identity for the container itself — no trusted headers, nothing — that's the image's own job to configure if it wants one. The container starts on first request if it isn't already, and scales back down after inactivity (60/300/900/3600/28800/86400 seconds, or `0` for never, keeping it always on and billed around the clock; default is the deployment's own, override per-key with `PATCH /api/v1/me {"settings": {"idleTimeoutSeconds": }}`). ### Your own domains A project can also answer at any number of domains you control. Add each one (`foobar.com`, `www.foobar.com`, ...) to the same project: ```bash curl -X POST https://cloudish.ai/api/v1/projects/YOUR_ALIAS/my-app/domains \ -H "Authorization: Bearer $CLOUDISH_API_KEY" -H "content-type: application/json" \ -d '{"host": "foobar.com"}' # -> { "domain": { "host": "foobar.com", "status": "pending", "redirect": false, # "txtRecord": { "name": "_cloudish-challenge.foobar.com", "value": "cloudish-verify=..." } } } ``` 1. Add the returned TXT record at your DNS provider. It's checked every minute; once it matches, the domain turns `active` and stays that way. It's only checked once, so the record can be removed afterwards. 2. Point the domain at do.cloudish.ai: a `CNAME` for a subdomain like `www`; an apex (`foobar.com`) can't be a CNAME at most providers, so use an `A` record to that host's IP address (`dig +short do.cloudish.ai`), or your provider's CNAME flattening/ALIAS if it has one. The certificate issues once both steps are done. 3. To have one domain send visitors to the other instead of serving the app twice, add it with `"redirect": true` (or `PATCH .../domains/www.foobar.com {"redirect": true}` later). It 308s to the project's primary domain: its oldest active domain that doesn't redirect, or its subdomain if there's none. `GET .../domains` lists them; `DELETE .../domains/{host}` removes one. Each active domain costs 0.01 credits a day. Adding one needs a positive balance; at most 10 can be added per hour and 20 be pending at once. A `409` means another project already holds that host. A request to an out-of-credit project returns `402` (JSON) instead of starting the container — a plain browser page load gets a `503` status page instead — see https://cloudish.ai/credits.md for adding credits, especially across several projects. Ask the platform admin to grant more via `POST /admin/v1/credits/grant`, or get a hand from any other key that already has a balance — its owner transfers some of it to yours by alias, authenticating with their own key, no admin needed: `curl -X POST https://cloudish.ai/api/v1/credits/transfer -H "Authorization: Bearer $THEIR_API_KEY" -H "content-type: application/json" -d '{"to":"","amount":1}'`. ## 5. Building containers — any language, any framework Cloudish doesn't care what's inside the image — it just runs whatever listens on `port` and reverse-proxies to it, adding no CORS headers of its own: set them in your app if a browser on another origin calls it. How containers are isolated: https://cloudish.ai/container.md. Bring any Dockerfile: - **JavaScript/TypeScript** — Express, Fastify, NestJS, or a Next.js app in standalone/server mode. - **Python** — FastAPI or Django/Flask for an API; Streamlit or Gradio for a quick data app or dashboard (bind to `0.0.0.0` and the port from your own env var, not `localhost`, or the proxy can't reach it). - **Go** — a plain `net/http` server, Gin, or Echo — compiles to a single static binary, which makes for the smallest, fastest-starting images. Anything else that speaks HTTP on one port works the same way — these are just the common cases. ### A real database, without a managed database service Cloudish has no managed Postgres/MySQL offering — attach a volume (section 3) and run the database *inside your own container* instead: - **SQLite** — simplest option for most apps: point your app at a file under the mounted volume (e.g. `$DATA_DIR/app.db`). No extra process. - **Postgres** — install `postgresql` in your image, and on container start (not at build time): run `initdb` into a subdirectory of the mounted volume if it isn't initialized yet, start `pg_ctl`, then idempotently create your role/database if missing (this runs on every boot, so it has to be a no-op after the first). Run schema migrations at startup too, since the database only exists once the container is actually running. Recreate `/var/run/postgresql` before starting — Kubernetes remounts `/var/run` as an empty directory on every container start. Generate any long-lived secret (session signing key, etc.) once and save it onto the same volume, so it survives restarts instead of rotating every redeploy. ### Sign-in for your users (OIDC) If your app needs to know who's visiting it, point it at Cloudish's own OpenID Connect provider instead of running your own identity system — a standard discovery document, Authorization Code + PKCE, no client secret to manage: ``` GET https://www.cloudish.ai/.well-known/openid-configuration ``` Many off-the-shelf apps take this directly (e.g. a generic `OIDC_ISSUER`/`OPENID_PROVIDER_URL` setting) with zero code. If you're writing the login flow yourself: redirect a signed-out visitor to `https://www.cloudish.ai/oauth/authorize?client_id=&redirect_uri=/callback&response_type=code&code_challenge=&code_challenge_method=S256&state=...`, then exchange the `code` your callback receives at `POST https://www.cloudish.ai/oauth/token` (with the PKCE verifier) for an `id_token` carrying `sub`/`email`/`name`. `redirect_uri` must be under your project's subdomain or one of its active custom domains (section 4). Your app's "Sign out" only ends your app's own session. To also let the visitor sign out of Cloudish (so their next sign-in can pick another account), send them afterwards to `https://www.cloudish.ai/oauth/logout?id_token_hint=&post_logout_redirect_uri=/&state=...` — Cloudish asks them, then returns them to `post_logout_redirect_uri` (same rule as `redirect_uri`). ## 6. Manage images already in the registry ```bash curl https://cloudish.ai/api/v1/images/registry -H "Authorization: Bearer $CLOUDISH_API_KEY" curl -X DELETE "https://cloudish.ai/api/v1/images/registry/tags?repo=builds/123&tag=v1" \ -H "Authorization: Bearer $CLOUDISH_API_KEY" ``` ## 7. Troubleshoot a deployment Fetch the running container's own stdout/stderr on demand — pulled fresh from the pod on every call, never persisted server-side, so polling it while diagnosing an issue doesn't grow anything: ```bash curl https://cloudish.ai/api/v1/docker/YOUR_ALIAS/my-app/logs -H "Authorization: Bearer $CLOUDISH_API_KEY" # -> { "logs": "--- container logs ---\n...\n--- events ---\n..." } ``` Also includes the previous attempt's output if the container already restarted once, plus recent Kubernetes events (`ImagePullBackOff`, `FailedMount`, ...) — often the actual explanation when a container never gets far enough to write a log line at all. ## 8. Datacenter This instance is currently running in the "do" datacenter — also directly reachable at https://do.cloudish.ai. We are planning expansion to other datacenters. ## 9. Claiming and adding credits Read https://cloudish.ai/credits.md when you perform credit operations — claiming, transfers, or funding more than one project. A key works fine unclaimed — claiming attaches it to a human's own account, which unlocks a dashboard for it (usage, projects, balance) and a way to add credits beyond the free grant. Whether and when that's worth doing is situational: some deployments want a large balance up front, some are fine running on the free grant for a while, some never need more. Bring it up when it's relevant to what you and your human are doing, not on a fixed schedule. Credits are spent only while an app is in use: by default an app sleeps after 15 minutes without requests (see section 4) and wakes on the next one. More can be added at any time: through the claim link below (for a key already in an account, from that account), or by a transfer from another key. Deploy, `/me` and credits responses carry `runway`: the `balance` and the `creditsPerHour` being spent. `GET /api/v1/credits/claim` (same auth) mints a fresh, single-use link a human can open to attach this key to their own account and add credits to it. Run it yourself and give your human the resulting URL — not the `curl` command for them to run, which they'd need the key from `.env` for: ```bash curl https://cloudish.ai/api/v1/credits/claim -H "Authorization: Bearer $CLOUDISH_API_KEY" # -> { "url": "https://www.cloudish.ai/claim?challenge=..." } # -> tell your human: "To add credits to , open: https://www.cloudish.ai/claim?challenge=..." ``` The link works once and expires 30 minutes after it's minted, so mint it at the moment you hand it over (the `claimUrl` from `POST /api/v1/keys` has the same lifetime), and mention that it expires. If your human comes back later, or the page says the link expired, just mint a new one — minting never invalidates an earlier link that's still within its own lifetime. Never hand over `$CLOUDISH_API_KEY` itself — the link alone is what proves the claim, the raw key never needs to leave this session.