# Set this repo up on InstaCloud These are the official setup instructions from InstaCloud, served at `https://instacloud.com/prompt.md`. If you are an AI coding agent, complete the steps below yourself by running the commands directly — only stop where a step explicitly needs the human (approving a sign-in, or choosing between creating and linking a project). ## What to use InstaCloud for If you were sent here to work out whether InstaCloud fits a repository, start with this section. If you already know what you are deploying, skip to step 1. Start with the cases InstaCloud is not built for. **A repository that matches one of these is out even when it also matches a direction further down**, and many of them will: a static frontend can have CI, and an app that needs several containers side by side can still own a Postgres database. Name the row and stop. | Not a fit | Why | | --- | --- | | GPU training or large model inference | we do not offer GPUs | | Multi-container docker compose apps | tenant compute has no Docker-in-Docker and no nested virtualization, so containers that must run side by side cannot. This row is about what the app needs at RUNTIME, not about a `compose.yaml` being present: a compose file whose only other services are databases InstaCloud runs managed (postgres, redis, mysql, mongodb) is not this row. That is the last direction below, and the app itself is a single container | | An interactive shell someone keeps pivoting inside | that shell is `insta compute ssh`, gated behind approval, and it lands on the guest root rather than inside a container. This row is not about `insta compute exec`, and it is not about branch environments: a branch per agent is the supported way to isolate work, and it is one of the directions below | | A script that runs once and exits, deployed as a service | the health gate expects something that stays up and answers. When a service already exists, run the script inside it with `insta compute exec`, which is built for one-shot commands and bounded at 180s | | A static frontend whose only backend lives elsewhere | nothing in the repo runs a server, so there is no environment to fork and no state to keep, and a static host does this better. If that backend is also yours, judge its repository instead | If the repository is empty there is nothing to classify yet. Ask what is being built, or take it from the prompt that sent you here, then scaffold the smallest thing that has an app and a database and carry on from step 1. If the repository has code but nothing in it runs as a service, a library or a CLI tool with no server, say so and stop. CI alone is not a service: a library with a GitHub Actions workflow still has nothing to put behind a URL, and the directions below all assume something is running. Otherwise read the repository and check it against these four directions. Each one has something concrete in the code that points to it, so this is a matching exercise rather than a guess. | Direction | What in the repo points to it | What you would build | | --- | --- | --- | | An environment per PR or per agent | CI, PR review, or more than one coding agent working on this repository's own source at once | a branch with its own URL. If the repo has a database of its own, the branch also gets its own copy of it, carrying the parent's data | | State that survives a restart | uploads, a cache on disk, a sqlite file, anything written to local disk. Files the app serves back over HTTP belong here too. State that only ever lives in memory does not: put that in Postgres instead of on a volume | a volume, so a restart does not wipe it | | Scheduled and background work | cron entries, a worker process, or a queue of any kind, including one that only exists inside the process. What decides it is whether work already in flight is lost when the process restarts | the worker running as its own service next to the app | | An app and its database as one unit | app code plus a Postgres connection string the app owns. A read-only connection into a database owned by something else does not count | both running together behind one hostname, with no database to install | Name the ones this repository actually hits, in order of how much they would change, and base that on the code in front of you rather than on what you already believe about InstaCloud. If none of them apply either, say so and stop. That is a real answer and it is worth more than a forced demo. ## 1. Install the CLI + agent skill ```bash npx -y insta@latest setup agent ``` One command, every OS and shell (Node 18+): installs the `insta` CLI globally, the InstaCloud skill for every coding agent on this machine, and the remote MCP server — and it always targets **production**, even if this machine was previously switched to staging. Idempotent — safe to re-run. Fallback if the npx command fails or the machine has no Node — macOS/Linux **only** (never run it on native Windows, where PowerShell's `curl` alias and the WSL `bash` shim break it; there, fix Node and use the npx command above): ```bash curl -fsSL agents.instacloud.com | sh ``` If the prompt that sent you here targets the **staging** deployment, use its explicit form instead — `npx -y insta@latest setup agent --env staging` — or run that prompt's exact curl command (the install host selects the environment). ## 2. Sign in Check first — you may already be signed in: ```bash insta status ``` If not: ```bash insta login --claim # the prompt that sent you here named the account insta login --oauth github # machine with a browser — opens it (or --oauth google) insta login --device # headless (VM, SSH, CI) — prints a link + code ``` **Prefer `--claim` whenever the prompt that sent you here names the person's address.** Its link tells the human *which account to sign in as*, which the device flow does not, and it mints a fresh code when one expires. A device code binds to the first account that opens the page, so on a machine whose browser is signed in elsewhere it is refused with "this code was opened by a different account first" and the whole flow has to start over. With `--device`, relay the printed link and code to the human immediately and verbatim, then let the CLI poll until they approve. `https://instacloud.com/agents.md` is the source of truth for authentication — API keys, the raw device-flow endpoints, and more. ## 3. Create or link a project **First check whether this directory is already bound:** ```bash insta status ``` If it names a project, stop: this directory is linked and you must not create another one. A second project is a second copy of the same app, with its own services to pay for and its own URL that nothing points at. Make your own branch environment instead, so your work gets its own URL and its own copy of the database without touching what the team is running: ```bash insta branch create # name it after the git branch you are working on ``` Confirm with `insta status` that it switched, then skip to step 4. Everything below is for a directory that names no project. If the prompt that sent you here included a project id, link it: ```bash insta project link ``` Otherwise, ask the human whether to **create a new project** or **link an existing one**, then run the matching command: ```bash insta project create # new project — named after the repo folder (pass a name to override) insta project link # existing project — find the id with `insta project list` ``` Either way the choice persists to `./.insta/project.json`; commit it so teammates and CI inherit the binding. ### If you were sent here with a credit code Redeem it now, **after** the project exists: ```bash insta billing redeem ``` The credits land on the organization that owns this project, and the receipt names that organization, the amount, and when the credits expire. The order matters. A code is redeemed against an organization, and with no project linked the CLI has no organization to resolve, so redeeming before step 3 fails with a message about linking a project rather than anything about credits. If the credits belong somewhere else, name it explicitly with `insta billing redeem --org `, which skips project resolution entirely (`insta org list` prints the ids). ## 4. Add services and deploy Follow the InstaCloud agent skill installed in step 1 — it documents the service kinds and the deploy flow. Decide the services from the repository itself, using the directions at the top of this page: a database the app owns, a worker for durable background work, a volume for state on disk. Ask only where the code leaves it genuinely ambiguous, because the preamble promises the human just two stops and this is not meant to be a third. Then add each one: ```bash insta services add # e.g. postgres main-db, storage assets, compute api insta secrets bind DATABASE_URL postgres/main-db --to compute/api # give compute its service credentials insta deploy . # build remotely and ship (compute services need a Dockerfile) ``` Spell out kind and name: bare `insta services add` opens an interactive picker only in a human terminal — in a non-interactive agent shell it exits with a usage error instead. A volume belongs to one compute service. Add it with `--volume ` on `insta services add compute `, or attach it later with `insta compute volume --size `. It mounts at `/data` unless you pass `--mount-path `, and the image's own `VOLUME` line does not change that. Mount it on the directory the app writes its data to, or point the app's data directory at `/data`. `insta deploy .` builds the directory you give it, so the `Dockerfile` it reads is the one at that directory's root. Repositories that keep theirs somewhere else (`scripts/Dockerfile`, `docker/Dockerfile`) will not build as-is, and some of them also expect a frontend to be built first. Check before you deploy rather than after the build fails. When the project already publishes an image, deploy that instead and skip the build: ```bash insta deploy --image --port ``` That is usually the right move for an experiment: it removes the whole build from the loop, and it ships exactly the artifact the project's own users run, so a result says something about InstaCloud rather than about your Dockerfile. Credentials follow the skill's rules, not this page: service credentials reach compute through `insta secrets bind`, and local commands that need user-defined secrets run under `insta run -- `, which injects them into that process only. Do not write a `.env` file as a setup step — the skill covers the one case where a file is genuinely needed. ## 5. Verify and report ```bash insta status ``` Confirm it shows the expected environment, a logged-in user, and the linked project, then tell the human the project is set up and where each service is running (`insta agent manifest` prints every branch and its URLs).