Coverage

Which agents this is for

Some agents (Claude Code, Cursor, Codex, Gemini, Kiro, Factory, Junie, Letta) auto-load the Tuploy skill — for those, the simpler Claude Code guide is enough.

For every other shell-capable agent, the prompt template below gives the agent the same rules the skill enforces. No plugins required.

bash

# Auto-loaded skill (zero extra setup)
Claude Code, Cursor, Codex, Gemini, Kiro, Factory, Junie, Letta

# Shell-capable, no auto-skill (use the prompt template)
Aider, Windsurf, OpenHands, Continue, Roo Code, Amp, OpenCode

# Anything else that can run a terminal command
Custom scripts, CI pipelines, Plandex, etc.

Step 0

What you need

A Tuploy account with the welcome credit applied. Sign up at tuploy.com.
An agent with shell access — any agent that can execute terminal commands and read their output works.
A project to deploy — Node.js, Python, Go, PHP, static HTML or any framework Tuploy detects.

Walkthrough

One prompt, one URL

Install Tuploy through the agent

Paste this into your agent — it'll run the install command in your shell and store a temporary token in ~/.tuploy/credentials.

text

I'd like you to set up Tuploy.

curl -fsSL https://tuploy.com/install.sh | bash

On Windows (PowerShell):
iwr -useb https://tuploy.com/install.ps1 | iex

The installer opens your browser to tuploy.com/activate where you finish OAuth. Once you approve, the CLI claims a real API key and you're ready.

Browser-based activation is intentional

The CLI never gets to see your password. The activation flow hands the agent a short-lived token (5 min TTL) that the server only releases after you OAuth in person. The temporary token is stored hashed in the database; the real API key comes back encrypted with AES-256-GCM and is deleted from the server's store the moment the CLI claims it.

Hand the agent the deploy rules

Paste the template below verbatim. The rules mirror the enforced skill so an agent without auto-skill behaves the same way — no surprise overwrites, no fake Dockerfiles.

text

You're going to deploy this project to Tuploy. Here are the rules:

1. Install the Tuploy CLI if it's not already on PATH:
   curl -fsSL https://tuploy.com/install.sh | bash
   (Windows PowerShell: iwr -useb https://tuploy.com/install.ps1 | iex)

2. Read .tuploy.json if it exists. If it has a "projectSlug", run
   `tuploy applications` to verify the project still exists. If deleted,
   treat as a new deploy.

3. Inspect the project: package.json, .env.example, any prisma/ folder.
   If the project uses a database (Prisma, DATABASE_URL in .env, pg/mysql
   driver) AND .tuploy.json has no databaseId, run `tuploy databases`
   and ASK ME which database to use or to create a new one. Never pick
   automatically.

4. Run: tuploy deploy . [--env KEY=VALUE ...]
   - Pass production env vars with --env, never edit my .env file.
   - Use --name only on the very first deploy.

5. If the deploy fails on a plan limit, run `tuploy billing` to print
   the upgrade link and STOP. Don't delete apps to free a slot.

6. When done, share the live URL from the output.

Approve database choice if asked

When the agent finds a Prisma schema or a DATABASE_URL in your .env, the rules require it to ask you which database to use. Answer with either an existing id from tuploy databases or "create a new postgresql/mysql/mariadb/redis/mongodb".

Match the type to the project

--type mysql for PHP/Laravel/WordPress, --type mongodb for MERN/Mongoose, --type redis for caches and queues. Default is PostgreSQL.

Verify the deploy

When the deploy finishes, the agent prints the live URL. Open it in the browser to confirm. Future redeploys reuse .tuploy.json written into the project root, so they're a one-liner.

Sanity check

Confirm the agent has it wired

If something looks off, ask the agent to run these three things and paste back the output:

bash

# Inside your agent, ask it to:
1. Run `tuploy version` and paste the output
2. Run `tuploy applications` to confirm auth works
3. Confirm where ~/.tuploy/config.json is stored

tuploy version should print a version and the API URL it points to (default: https://tuploy.com/api). tuploy applications should list your apps without authentication errors.

Hardening

Rules to enforce on agents you don't fully trust

Agents differ in how rigorously they obey instructions. If you're running an agent that has free reign over your file system, keep these constraints explicit:

Non-negotiable defaults

No agent should ever edit your .env — it belongs to your local development setup. Production env vars travel via --env KEY=VALUE.
No agent should delete or rename existing apps to free a plan slot. tuploy delete doesn't exist for a reason — destructive moves must go through the dashboard with explicit confirmation.
No agent should modify your project to bypass a build error. If the deploy fails, the cause is in your code or in the environment — fixing it by adding a fake Dockerfile or swapping the runtime is the wrong move and will hide problems for next time.

Troubleshooting

Common failure modes

"Command not found: tuploy"

The agent installed the binary but didn't reload your shell PATH. Ask it to source ~/.bashrc (or open a new terminal) and try again.

Activation timed out

The browser flow has a 5-minute TTL. If you didn't finish OAuth in time, re-run the install command — a fresh token is generated each time the install script is fetched.

Agent picked a database without asking

The prompt template explicitly says "ASK ME" — if the agent skipped it, the rules weren't enforced. Tighten the template, repeat the deploy with the right database id, and consider switching to a skill-aware agent.

Where to next

Deploy with any AI agent