Getting Started

Go from a GitHub repo to a running app with database and custom domain.

Prerequisites

• A GitHub account with a repository
• An AI coding tool: Claude Code, Cursor, or Codex (or the CLI)

1. Connect PromptShip

Add the PromptShip MCP server to your AI coding tool. See MCP setup for tool-specific instructions. This lets your AI assistant deploy and manage apps on your behalf.

2. Connect GitHub

Install the PromptShip GitHub App on your account or organization. This gives PromptShip read access to clone your repos during builds.

You can also view the PromptShip GitHub App on the GitHub Marketplace to review permissions before installing.

install_github

Follow the link to authorize the GitHub App. You can scope it to specific repositories.

3. Create an App

Create an app by providing a name and the GitHub repo URL.

create_app(
  name: "my-api",
  github_repo: "https://github.com/your-org/your-repo",
  app_tier: "app-1"
)

app_tier sets the compute resources for your app. See Pricing for what each tier includes.

The response includes platform_env_vars per environment — these are the environment variables PromptShip will inject at deploy time.

4. Configure Runtime & Process

Choose how to build your app. Pick a supported runtime and PromptShip generates the Dockerfile for you — no Docker knowledge needed:

configure_app(
  app_name: "my-api",
  runtime: "python:3.12",
  port: 8000
)

Supported runtimes: python:3.12, python:3.11, node:22, node:20, go:1.22, go:1.21, bun:1, static. Or use dockerfile (the default) to provide your own — see Dockerfile Templates.

Then set the command for your web process. This is the shell command that starts your app:

configure_process(
  app_name: "my-api",
  process_name: "web",
  process_type: "web",
  command: "gunicorn app:app --bind 0.0.0.0:$PORT"
)

Your app must listen on 0.0.0.0:$PORT. See Processes to add workers and cron jobs.

5. Deploy

Trigger a deploy from any branch. The default environment is dev.

deploy_app(
  app_name: "my-api",
  branch: "main",
  env: "dev"
)

PromptShip clones your repo, builds the Docker image, and deploys it. You can check progress with get_deploy_status.

Once deployed, your app is live at https://my-api-your-team-dev.promptship.dev.

6. Attach a Database

Add a dedicated PostgreSQL database or Valkey (Redis-compatible) cache to any environment. Attach runs asynchronously: the call returns immediately with a pending job, and you poll get_db_attach_status until it reaches succeeded or failed.

attach_postgres(
  app_name: "my-api",
  environment: "dev",
  tier: "pg-1"
)
# Poll every ~10s until status is "succeeded":
get_db_attach_status(
  app_name: "my-api",
  environment: "dev",
  db_type: "postgres"
)

After success, DATABASE_URL is automatically injected on the next deploy. See Environment Variables for details. See Pricing for available Postgres tiers.

attach_valkey(
  app_name: "my-api",
  environment: "dev",
  tier: "valkey-1"
)

Same pattern — poll get_db_attach_status with db_type: "valkey". On success, REDIS_URL and VALKEY_URL are injected on the next deploy. See Pricing for available Valkey tiers.

7. Set Secrets

Add environment-specific secrets that are encrypted at rest and injected at deploy time.

set_secret(
  app_name: "my-api",
  environment: "dev",
  key: "STRIPE_API_KEY",
  value: "sk_test_..."
)

Secrets are available as environment variables in your app. Redeploy after setting secrets for them to take effect.

8. Custom Domains

Point your own domain to your app. HTTPS certificates are issued and renewed automatically via Cloudflare.

set_domain(
  app_name: "my-api",
  environment: "prod",
  domain: "api.example.com"
)

The response includes DNS records you need to add at your domain registrar:

1. CNAME record — point your domain (e.g. api.example.com) to the cname_target returned by set_domain
2. Ownership TXT record — add a TXT record with the txt_name and txt_value from the response to prove you own the domain
3. SSL validation TXT record — add a TXT record with ssl_validation_txt_name and ssl_validation_txt_value to provision the HTTPS certificate

Once the DNS records are in place, call verify_domain to check verification status. When verified, HTTPS is active and your domain is live.

Next Steps