Koiship Documentation

Welcome to Koiship! This guide walks you from zero to a running backend.

1. Create an account at /register. 2. Open the dashboard and click 'New Backend'. 3. Pick a runtime (Node.js, Python, Discord Bot or Static), choose a template or upload a ZIP, and hit Create.

Koiship automatically creates your isolated workspace, provisions a container on a hosting node, installs dependencies, starts your process and runs a health check. When everything is green, your backend is ONLINE.

Free accounts can run 2 backends with 256 MB RAM each — enough to test most projects. Upgrade anytime from Billing.

The creation wizard collects: backend name, runtime, runtime version, region, startup command, port and a resource plan.

The startup command is executed inside your container with your workspace mounted at /app. Examples: `node index.js`, `python main.py`, `npm start`.

If you configure a port, Koiship performs a TCP health check after starting; a backend that never listens still counts as ONLINE if it keeps running (useful for Discord bots, which don't bind ports).

Optional extras during creation: environment variables, a starting template and a free yourproject.koiship.com subdomain.

Deployments run through a pipeline with explicit stages: UPLOAD → VALIDATE → EXTRACT → DETECT RUNTIME → INSTALL DEPENDENCIES → BUILD → START → HEALTH CHECK → ONLINE.

To deploy code, open your backend and click REDEPLOY, or upload a ZIP from the Files tab. Archives are extracted securely — path traversal attempts are rejected.

Every deployment records status (QUEUED, RUNNING, SUCCESS, FAILED, CANCELLED), logs, start/end time and duration. Open Deployments → any entry to inspect its full log.

If a deploy fails, the backend is marked CRASHED with the failure reason shown on the overview tab. Fix the code and redeploy — previous workspace state is replaced only after a successful extraction.

The Files tab is a full file manager: browse directories with breadcrumbs, upload files or ZIP archives, extract, download, delete, rename, move, create folders and edit code in the built-in editor.

Supported text formats include .js, .ts, .json, .py, .txt, .md, .html, .css, .env, .yml and .yaml. Binary files can be uploaded and downloaded but not edited inline.

Security: every operation is validated against your backend's isolated storage root. Paths containing '..' or absolute paths are rejected. Host filesystem paths are never exposed to the browser.

The Environment tab manages secrets for your backend: add, edit, delete, search, bulk-import (KEY=VALUE lines) and reveal values.

Values are masked by default and are only returned to your browser when you explicitly reveal them. They are injected into your container's environment at start time and never written into logs.

After changing variables, click RESTART so the running process picks them up.

Every backend can get a free subdomain: yourproject.koiship.com. Create it during backend creation or from the Domains page.

Custom domains: add your hostname, then create the DNS records shown on the domain card (an A/CNAME record pointing at our proxy plus a TXT verification record `_koiship-verify.yourdomain.com`). Click Verify — we check the TXT record in real DNS.

Once verified, routing is handled by our reverse proxy. SSL certificates are provisioned automatically for all koiship.com subdomains and verified custom domains (see the Domains tab for current SSL status).

Templates are prebuilt projects (Node.js API, Python FastAPI, Discord bot, Next.js, static site, and more) with ready-made files and startup commands.

Pick one in the backend creation wizard, or browse /templates. After creation the files appear in your file manager — they are yours to modify.

The marketplace hosts community templates. Search, filter by runtime, sort by popularity or rating, and install with one click.

Publishing: submit a listing from your dashboard → Marketplace. Submissions go through moderation (PENDING → APPROVED / REJECTED) before appearing publicly. Approved listings can be reviewed and rated by other users.

Marketplace code is never executed outside an isolated environment — it only materializes inside a backend workspace when a user installs it.

The Settings tab of a backend lets you create a full ZIP snapshot of its workspace. Backups run as background jobs and appear once complete.

Restore replaces the current workspace with the backup's contents. Download stores the archive locally. Restoring does not auto-restart your process — redeploy to apply.

Backend immediately CRASHED: open the Console tab — startup errors stream there in real time. The most common causes are a wrong startup command, a missing dependency file, or a crashing port conflict.

Health check failed: your app may not listen on the configured port. Make sure it binds 0.0.0.0 and uses the PORT environment variable.

Dependency install failed: check the deployment logs (Deployments tab → latest run). Ensure package-lock.json or requirements.txt is present.

Can't connect a domain: DNS can take minutes to hours to propagate; use the Verify button after records are in place.

Still stuck? Open a ticket at Dashboard → Support — include your backend name and the error text.