# InstaPods

> InstaPods is a web hosting platform that gets your app from localhost to a live URL in under 60 seconds. You built it with AI - now get it online. One command (`npx instapods deploy`) gives you a real Linux server with a subdomain, SSH access, and optional database. No Docker, no Kubernetes, no nginx config. Starts at $3/month.

InstaPods sits between Vercel/Netlify and a raw VPS. Each pod is a dedicated Linux server on bare metal - you get full SSH access, a web terminal, a web IDE, file sync, and GitHub auto-deploy. It also has an MCP server so AI agents (Claude Code, Cursor, Windsurf) can create and manage pods programmatically. Supports Static (HTML/CSS/JS), PHP 8.3, Node.js 20, and Python 3.12 runtimes with add-on MySQL, PostgreSQL, and Redis. A 1-Click App marketplace lets you deploy self-hosted tools like n8n, Uptime Kuma, and Beszel.

---

## Introduction

You built an app. Now get it online.

**InstaPods** gives you a cloud pod in under 2 seconds. Each pod is a persistent Linux server with its own domain, SSH access, and pre-installed stack. No Docker. No DevOps. No cold starts.

Works with apps built in Cursor, Claude Code, Lovable, Bolt, or any tool.

### Why InstaPods?

- **Live in Seconds**: Create a pod in under 2 seconds. Your app gets a public URL immediately - no build steps, no deploy pipeline.
- **Real Servers, Not Sandboxes**: Full Linux servers with SSH access. Install anything. Run any process. Your files persist across restarts.
- **Pick Your Stack**: Static, PHP, Node.js, or Python - each preset comes with the right packages pre-installed.
- **Databases Included**: Add MySQL, PostgreSQL, or Redis with a single command. Credentials auto-generated.

### How It Works

```bash
# Install the CLI
curl -fsSL https://instapods.com/install.sh | sh

# Create a pod
instapods pods create my-app -p nodejs

# Upload your code
instapods files sync my-app --local ./my-project

# Reload to install deps and start your app
instapods pods reload my-app

# That's it - your app is live
# → https://my-app.nbg1-1.instapods.app
```

Or use the dashboard at https://app.instapods.com - create a pod, upload files, and manage everything from the browser.

### Plans

| Plan | CPU | Memory | Storage | Price |
|------|-----|--------|---------|-------|
| **Launch** | 1 vCPU | 512 MB | 10 GB | $3/mo |
| **Build** | 2 vCPU | 2 GB | 25 GB | $7/mo |
| **Grow** | 2 vCPU | 4 GB | 50 GB | $15/mo |
| **Scale** | 4 vCPU | 8 GB | 100 GB | $25/mo |
| **Turbo** | 6 vCPU | 12 GB | 150 GB | $49/mo |

Flat monthly pricing. No usage fees. No cold starts. Your pod runs 24/7.

---

## Quickstart

Get a running pod with a public URL in just a few steps.

### Step 1: Create an Account

Go to https://app.instapods.com/register and sign up with your email address, or sign in with GitHub or Google.

### Step 2: Create a Pod

**Dashboard:**
1. Click **Create Pod** from the dashboard
2. Enter a name for your pod (e.g., `my-first-app`)
3. Select a preset: Static, PHP, Node.js, or Python
4. Choose a plan (Launch is fine to start)
5. Click **Create** - your pod will be ready in 1-2 seconds.

**CLI:**
```bash
# Install the CLI
curl -fsSL https://instapods.com/install.sh | sh

# Login
instapods login --email you@example.com

# Deploy in one command (creates pod + uploads code + installs deps)
instapods deploy my-first-app --local ./my-project
```

**API:**
```bash
curl -X POST https://app.instapods.com/api/pods \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-first-app", "preset": "nodejs", "plan": "launch"}'
```

### Step 3: Access Your Pod

Once created, your pod is accessible at: `https://my-first-app.nbg1-1.instapods.app`

Connect via SSH:
```bash
ssh instapod@nbg1-1.instapods.app -p YOUR_PORT
```

### Step 4: Deploy Your Code

**Git (Recommended):**
```bash
instapods git connect my-first-app --repo https://github.com/you/your-repo --deploy
```
From now on, every push to `main` auto-deploys.

**CLI Upload:**
```bash
instapods files sync my-first-app --local ./my-project
instapods pods reload my-first-app
```

For Node.js and Python presets, you must run `pods reload` after uploading code. This installs dependencies and restarts the app service.

### Step 5: Add a Database (Optional)

```bash
instapods services add my-first-app -s mysql -w
instapods services creds my-first-app -s mysql
```

Database services require the Build plan ($7/mo) or higher.

---

## Core Concepts

### Pods

A **pod** is a persistent Linux server running on InstaPods infrastructure. Unlike ephemeral sandboxes, pods are full system servers - all files, installed packages, and configurations survive restarts.

Each pod gets:
- A public URL (e.g., `my-app.nbg1-1.instapods.app`)
- A dedicated SSH port for remote access
- A pre-installed development stack based on its preset
- Its own filesystem at `/home/instapod/app`

### Presets

A **preset** defines the software stack pre-installed in a pod:

| Preset | Stack | App Port | Use Case |
|--------|-------|----------|----------|
| **Static** | nginx | 80 | HTML/CSS/JS sites, landing pages |
| **PHP** | nginx + PHP-FPM 8.3 + Composer | 80 | PHP applications, APIs |
| **Node.js** | Node.js 20 + npm + systemd service | 3000 | Express, Next.js, any Node app |
| **Python** | Python 3.12 + pip + venv + systemd service | 8000 | Django, Flask, FastAPI |

### Plans

| Plan | CPU | Memory | Storage | Price | Services |
|------|-----|--------|---------|-------|----------|
| **Launch** | 1 vCPU | 512 MB | 10 GB | $3/mo | No |
| **Build** | 2 vCPU | 2 GB | 25 GB | $7/mo | Yes |
| **Grow** | 2 vCPU | 4 GB | 50 GB | $15/mo | Yes |
| **Scale** | 4 vCPU | 8 GB | 100 GB | $25/mo | Yes |
| **Turbo** | 6 vCPU | 12 GB | 150 GB | $49/mo | Yes |

All plans include SSH access, custom domains, automatic SSL, and the web IDE. The Launch plan does not support database services.

### Regions

A **region** is a geographic location where your pods run. When creating a pod, you can optionally select a region - if you don't, InstaPods picks the closest server.

```bash
instapods regions
```

### Teams

A **team** is the organizational unit for billing and access control. Pods belong to teams, not individual users. Billing is per-team. You can create multiple teams and switch between them.

---

## Presets Overview

A preset defines the software stack pre-installed in your pod. Each preset uses a pre-built image, so pod creation takes just 1-2 seconds.

### Comparison Table

| | Static | PHP | Node.js | Python |
|---|--------|-----|---------|--------|
| **Web Server** | nginx | nginx + PHP-FPM | - | - |
| **Runtime** | - | PHP 8.3 (default) | Node.js 20 (default) | Python 3.12 (default) |
| **Available Versions** | - | 8.2, 8.3, 8.4 | 18, 20, 22 | 3.11, 3.12 |
| **Package Manager** | - | Composer | npm | pip |
| **App Port** | 80 | 80 | 3000 | 8000 |
| **App Root** | `/home/instapod/app` | `/home/instapod/app` | `/home/instapod/app` | `/home/instapod/app` |
| **Public Root** | `/home/instapod/app` | `/home/instapod/app/public` | `/home/instapod/app` | `/home/instapod/app` |

### Runtime Versions

PHP, Node.js, and Python presets support multiple runtime versions:
```bash
instapods pods create my-app -p php --version 8.4
instapods pods create my-app -p nodejs --version 22
instapods pods create my-app -p python --version 3.11
```

If you don't specify a version, the default is used (PHP 8.3, Node.js 20, Python 3.12). The version cannot be changed after creation.

---

## Static Preset

The Static preset serves files directly via nginx - ideal for HTML sites, single-page applications, documentation, and landing pages.

**What's Included:** nginx, git, SSH, plus curl, wget, vim, htop, unzip.

**Directory Structure:**
```
/home/instapod/app/
├── index.html
└── (your files here)
```

**Deploying:**
```bash
instapods files sync my-site --local ./dist
# Or
instapods deploy my-site --local ./dist
```

**SPA routing:** The default nginx config uses `try_files $uri $uri/ =404`. For SPAs with client-side routing, update the config:
```bash
sudo sed -i 's|try_files $uri $uri/ =404;|try_files $uri $uri/ /index.html;|' /etc/nginx/sites-available/default
sudo nginx -t && sudo systemctl reload nginx
```

**Use Cases:** Static HTML/CSS/JS websites, single-page applications (React, Vue, Svelte builds), documentation sites, landing pages.

---

## PHP Preset

PHP preset with nginx, PHP-FPM, and Composer. Versions 8.2, 8.3 (default), and 8.4 available.

**What's Included:** nginx, PHP-FPM (8.2/8.3/8.4), Composer, git, SSH. Pre-installed PHP extensions: mbstring, xml, curl, mysql, pgsql, redis, zip.

**Directory Structure:**
```
/home/instapod/app/
├── public/
│   └── index.php       # Web-accessible entry point
├── composer.json
└── vendor/
```

nginx is configured to serve from `/home/instapod/app/public`. Place your entry point (`index.php`) there. Application code, configs, and vendor directory go in the parent `/home/instapod/app`.

**Deploying:**
```bash
instapods deploy my-php-app --local ./my-laravel-project
```

**Routing:** The nginx config includes `try_files $uri $uri/ /index.php?$query_string`, which works out of the box for Laravel.

**File Permissions:** PHP-FPM runs as `www-data`. For writable directories:
```bash
instapods exec my-php-app -- chown -R www-data:www-data /home/instapod/app/storage
```

**Use Cases:** Laravel applications, custom PHP APIs, content management systems, PHP microservices.

---

## Node.js Preset

Node.js preset with npm and systemd process management. Versions 18, 20 (default), and 22 available.

**What's Included:** Node.js (18/20/22), npm, systemd, git, SSH.

**Directory Structure:**
```
/home/instapod/app/
├── package.json
├── index.js
└── node_modules/
```

- **App Port**: 3000 (your app must listen on this port)
- **Environment**: `NODE_ENV=production` is set by default

Your Node.js app runs as a systemd service called `app`. It runs `/usr/bin/node index.js` from `/home/instapod/app`, starts automatically on boot, restarts on crash, and runs as the `instapod` user.

**Important:** Your app must bind to `0.0.0.0` (not `localhost` or `127.0.0.1`) on port 3000.

**Deploying:**
```bash
instapods files sync my-node-app --local ./my-project
instapods pods reload my-node-app
```

`pods reload` automatically runs `npm install --production` when it detects a `package.json`.

**Example Express App:**
```javascript
const express = require('express');
const app = express();
app.get('/', (req, res) => res.send('Hello from InstaPods!'));
app.listen(3000, '0.0.0.0', () => console.log('Server running on port 3000'));
```

**Viewing Logs:**
```bash
instapods logs my-node-app -s app
```

**Use Cases:** Express/Fastify APIs, Next.js (standalone), GraphQL servers, WebSocket apps, background workers.

---

## Python Preset

Python preset with pip, venv, and systemd process management. Versions 3.11 and 3.12 (default) available.

**What's Included:** Python (3.11/3.12), pip, venv, systemd, git, SSH.

**Directory Structure:**
```
/home/instapod/app/
├── requirements.txt
├── app.py
└── venv/
```

- **App Port**: 8000 (your app must listen on this port)
- **Virtual environment**: Auto-created at `/home/instapod/app/venv`, auto-activated on SSH login

**Important:** Your app must bind to `0.0.0.0` (not `localhost`) on port 8000.

**Deploying:**
```bash
instapods files sync my-python-app --local ./my-project
instapods pods reload my-python-app
```

`pods reload` automatically runs `pip install -r requirements.txt`.

**Gunicorn Auto-Detection:** If `gunicorn` is in `requirements.txt`, reload auto-configures systemd to use `gunicorn -b 0.0.0.0:8000 app:app`. If a `wsgi.py` file exists, it uses `wsgi:app` (works for Django).

**Example Flask App:**
```python
from flask import Flask
app = Flask(__name__)

@app.route('/')
def hello():
    return 'Hello from InstaPods!'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8000)
```

**Use Cases:** Django, Flask/FastAPI APIs, data science dashboards (Streamlit, Dash), ML model serving.

---

## Services Overview

InstaPods lets you install database services directly inside your pods. Each service runs alongside your application, accessible via `localhost`.

| Service | Port | Version | Use Case |
|---------|------|---------|----------|
| MySQL | 3306 | 8.0 | Relational database, WordPress, Laravel |
| PostgreSQL | 5432 | 14 | Advanced relational database, Django, Rails |
| Redis | 6379 | 7 | Caching, sessions, queues, real-time data |

**Services require the Build plan ($7/mo) or higher.**

**Installation:**
```bash
instapods services add my-app -s mysql -w
instapods services creds my-app -s mysql
```

**Default Credentials:**
- Host: `localhost`
- Username: `instapod`
- Password: Auto-generated (unique per installation)
- Database: `instapod` (MySQL and PostgreSQL only)

Installation takes 8-15 seconds and runs asynchronously.

---

## MySQL

MySQL 8.0, on-demand service.

**Install:**
```bash
instapods services add my-app -s mysql -w
```

**Credentials:**
| Field | Value |
|-------|-------|
| Host | `localhost` |
| Port | `3306` |
| Username | `instapod` |
| Password | (auto-generated) |
| Database | `instapod` |

**Connecting from PHP:**
```php
$pdo = new PDO('mysql:host=localhost;port=3306;dbname=instapod', 'instapod', 'YOUR_PASSWORD');
```

**Connecting from Node.js:**
```javascript
const mysql = require('mysql2/promise');
const connection = await mysql.createConnection({
  host: 'localhost', port: 3306, user: 'instapod', password: 'YOUR_PASSWORD', database: 'instapod'
});
```

**Connecting from Python:**
```python
import mysql.connector
conn = mysql.connector.connect(host='localhost', port=3306, user='instapod', password='YOUR_PASSWORD', database='instapod')
```

MySQL listens on `localhost:3306` only (not accessible from outside the pod).

---

## PostgreSQL

PostgreSQL 14, on-demand service.

**Install:**
```bash
instapods services add my-app -s postgresql -w
```

**Credentials:**
| Field | Value |
|-------|-------|
| Host | `localhost` |
| Port | `5432` |
| Username | `instapod` |
| Password | (auto-generated) |
| Database | `instapod` |

**Connecting from Python:**
```python
import psycopg2
conn = psycopg2.connect(host='localhost', port=5432, user='instapod', password='YOUR_PASSWORD', dbname='instapod')
```

**Connecting from Node.js:**
```javascript
const { Pool } = require('pg');
const pool = new Pool({ host: 'localhost', port: 5432, user: 'instapod', password: 'YOUR_PASSWORD', database: 'instapod' });
```

---

## Redis

Redis 7, on-demand service for caching, sessions, and message queues.

**Install:**
```bash
instapods services add my-app -s redis -w
```

**Connection:** `localhost:6379`. No authentication (only listens on localhost).

**Node.js:**
```javascript
const Redis = require('ioredis');
const redis = new Redis({ host: 'localhost', port: 6379 });
```

**Python:**
```python
import redis
r = redis.Redis(host='localhost', port=6379)
```

**Use Cases:** Caching, sessions, queues (Bull, Celery, Laravel Queues), pub/sub, rate limiting.

---

## Dashboard Overview

The InstaPods dashboard at https://app.instapods.com shows all pods in your current team with name, preset, plan, resources, status, and domain. The sidebar provides access to Dashboard, Billing, Teams, Admin (admin users), and Docs.

---

## Pod Detail

Click any pod from the dashboard to open its detail page. The page has 8 tabs:

1. **Overview** - Status, preset, plan, resources, domain, server, region, controls
2. **Domains** - Custom domain management with CNAME/TXT verification
3. **Services** - Install/manage MySQL, PostgreSQL, Redis
4. **Git** - Connect repository, deployment history, build logs, rollback
5. **Files** - Browser-based file manager
6. **SSH** - Connection info, SSH key management
7. **Logs** - Application and service logs with filtering
8. **Events** - Timeline of pod lifecycle events

---

## Web IDE

Browser-based code editor built on Monaco (VS Code engine). Access via the **Open IDE** button on any pod detail page, or directly at `https://app.instapods.com/ide/{pod-name}`.

**Features:** File tree sidebar, multi-tab editing (up to 10 files), syntax highlighting for JavaScript, TypeScript, HTML, CSS, PHP, Python, Go, Rust, and more. Ctrl+S/Cmd+S to save. Drag and drop upload. All changes save directly to the pod.

---

## Web Terminal

Full interactive shell in the browser - no SSH keys needed. Go to pod detail → Terminal tab. Connects via WebSocket, runs bash as the `instapod` user starting in `/home/instapod/app`. Auto-resizes with browser window. Use `sudo` for system commands.

---

## Custom Domains

Map up to 5 custom domains per pod with automatic SSL via Let's Encrypt.

1. Go to pod's **Domains** tab → **Add Domain**
2. Enter your domain (e.g., `app.example.com`)
3. Add a CNAME record: `app.example.com CNAME my-pod.nbg1-1.instapods.app`
4. Click **Verify** - SSL certificate is auto-provisioned

Certificates auto-renew. Root domains work if your DNS supports CNAME flattening.

---

## Teams

Teams are the organizational unit. Pods and billing are scoped to teams. Every user has at least one team. Team roles: Owner (full access) and Member (manage pods, view billing).

---

## Billing

Billing is per-team. All plans are flat monthly pricing with prorated billing.

**Payment:** Credit card via Stripe. Failed payments enter a 7-day grace period, then pods are suspended.

**Credits:** Applied automatically to future invoices. Types: promo, bonus, refund.

**Cancellation:** Cancel anytime from billing page. Resume before period ends.

---

## Git Deployment

Deploy code by connecting a GitHub repository (or any Git URL). Push to a branch and your code deploys automatically.

**Quick Start:**
```bash
instapods pods create my-api --preset nodejs -w
instapods git connect my-api --repo https://github.com/you/my-api --deploy
# Push to main → auto-deploys
```

**Deploy Flow:**
1. Pull latest code from configured branch
2. Install dependencies (auto-detected)
3. Build (if configured)
4. Restart application service

**AI Build Detection:** InstaPods uses AI to analyze your project files and determine the right install, build, and start commands automatically. Works for Next.js, Vite, Django, Laravel, and more.

**Skip a deploy:** Add `[skip deploy]` to your commit message.

**Manual Deploy:**
```bash
instapods git deploy my-app -w
```

**Deployment History:**
```bash
instapods git deployments my-app
instapods git logs my-app
```

**Rollback:**
```bash
instapods git rollback my-app
```

**GitHub Commit Status:** InstaPods reports deployment status back to GitHub as commit status checks.

---

## Environment Variables

**Recommended:** Create a `.env` file:
```bash
instapods exec my-app -- "cat > /home/instapod/app/.env << 'EOF'
DATABASE_URL=postgres://instapod:secret@localhost:5432/instapod
API_KEY=sk-your-api-key-here
NODE_ENV=production
EOF"
instapods pods reload my-app
```

- **Node.js:** Use `dotenv` package. `NODE_ENV=production` set by default.
- **Python:** Use `python-dotenv`. Venv auto-activated.
- **PHP:** Use `getenv()` or Laravel's built-in `.env` handling.
- **Static:** Use a `config.js` file with `window.APP_CONFIG`.

---

## SSH Access

Every pod has a dedicated SSH port (range 2200-3200).

```bash
ssh instapod@nbg1-1.instapods.app -p YOUR_PORT
# Or use the CLI shortcut:
instapods ssh my-app
```

**Add SSH Keys:**
```bash
instapods ssh-keys add my-app
instapods ssh-keys add my-app --key ~/.ssh/work_key.pub
```

**SCP/SFTP:**
```bash
scp -P 2201 ./app.js instapod@nbg1-1.instapods.app:/home/instapod/app/
```

Uses Trust On First Use (TOFU) for host key verification. Deleted pod ports are reserved for 7 days.

---

## File Management

**CLI Commands:**
```bash
instapods files ls my-app                                    # List files
instapods files cat my-app /home/instapod/app/index.js       # Read file
instapods files write my-app /path/file.txt --content "Hi"   # Write file
instapods files upload my-app ./index.html                   # Upload file
instapods files sync my-app --local ./my-project             # Sync directory
```

Default excludes: `node_modules`, `.git`, `.env`, `__pycache__`, `.DS_Store`.

---

## CLI Installation

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

Auto-detects OS/architecture, verifies SHA256 checksum, installs to `/usr/local/bin`.

**Self-update:** `instapods update`

**Config:** `~/.instapods/config.json` - stores token, API URL, team ID.

**Shell completion:** Supports bash, zsh, fish, PowerShell.

**Command groups:** Authentication (`login`, `whoami`, `logout`), Catalog (`presets`, `plans`, `regions`), Pod Management (`pods`, `deploy`), Pod Operations (`exec`, `ssh`, `ssh-keys`, `files`, `services`, `logs`), Utilities (`version`, `update`, `completion`).

---

## CLI Authentication

**Browser OAuth (default):**
```bash
instapods login
```

**Email/Password:**
```bash
instapods login --email you@example.com --use-password
```

**Check user:** `instapods whoami`
**Logout:** `instapods logout`
**CI/CD:** `export INSTAPOD_TOKEN=your-token-here`

---

## CLI Pod Management

```bash
instapods pods list                                    # List all pods
instapods pods create my-app -p nodejs                 # Create pod
instapods pods create my-app -p php --version 8.4      # Specific version
instapods pods get my-app                              # Pod details
instapods pods start my-app -w                         # Start (wait)
instapods pods stop my-app                             # Stop
instapods pods restart my-app                          # Restart
instapods pods reload my-app                           # Reload app service
instapods pods resize my-app --plan build              # Change plan
instapods pods delete my-app -f                        # Delete (force)
```

**Create flags:** `-p` preset, `-v` version, `--plan`, `-r` region, `--ssh-key`, `-w` wait, `--timeout`.

**Preset auto-detection:** If `--preset` omitted, CLI scans for `package.json` (Node.js), `composer.json` (PHP), `requirements.txt` (Python), `index.html` (Static).

**Reload:** Restarts services based on preset. Auto-installs dependencies from `package.json` or `requirements.txt`.

**JSON output:** Add `--json` to any command.

---

## CLI Deploy

One-shot workflow: creates pod (if needed) + syncs files + installs deps + reloads.

```bash
instapods deploy myapp                          # Deploy current dir
instapods deploy myapp --local ./src            # Deploy specific dir
instapods deploy myapp --preset nodejs          # Explicit preset
instapods deploy myapp --no-reload              # Just sync files
```

**Flags:** `--local`, `-p`/`--preset`, `--no-reload`, `--exclude`, `-r`/`--region`, `--plan`, `--ssh-key`, `--timeout`.

**Default excludes:** `node_modules`, `.git`, `.env`, `__pycache__`, `.DS_Store`.

---

## CLI Git

```bash
instapods git connect my-app --repo URL --deploy         # Connect + deploy
instapods git connect my-app --repo URL --branch develop  # Custom branch
instapods git disconnect my-app                           # Disconnect
instapods git status my-app                               # Show config
instapods git deploy my-app -w                            # Trigger deploy
instapods git deployments my-app                          # History
instapods git logs my-app                                 # Build logs
instapods git rollback my-app                             # Rollback
```

---

## CLI File Management

```bash
instapods files ls my-app                               # List files
instapods files cat my-app /path/to/file                # Read file
instapods files write my-app /path --content "..."      # Write file
instapods files mkdir my-app /path -p                   # Create directory
instapods files upload my-app ./file.html               # Upload file
instapods files sync my-app --local ./project           # Sync directory
```

Pipe content via stdin: `cat .env | instapods files write my-app /home/instapod/app/.env`

---

## CLI Exec & SSH

```bash
instapods exec my-app -- ls -la /home/instapod/app      # Run command
instapods exec my-app -- npm install                     # Install deps
instapods exec my-app -- python manage.py migrate        # Django migration
instapods ssh my-app                                     # SSH session
instapods ssh-keys add my-app                            # Add SSH key
instapods ssh-keys list my-app                           # List keys
```

---

## CLI Services

```bash
instapods services list my-app                           # List services
instapods services add my-app -s mysql -w                # Install MySQL
instapods services add my-app -s postgresql -w           # Install PostgreSQL
instapods services add my-app -s redis -w                # Install Redis
instapods services creds my-app -s mysql                 # Get credentials
instapods services remove my-app -s mysql -f             # Remove service
```

Services require the Build plan or higher.

---

## CLI Logs

```bash
instapods logs my-app                      # All logs (100 lines)
instapods logs my-app -n 50                # Last 50 lines
instapods logs my-app -s app               # App logs only
instapods logs my-app -s nginx             # Nginx logs only
instapods logs my-app -s mysql             # MySQL logs
```

Available service filters by preset: Static (`nginx`, `system`), PHP (`nginx`, `php-fpm`, `system`), Node.js (`app`, `system`), Python (`app`, `system`).

---

## API Overview

Base URL: `https://app.instapods.com`

**Authentication:** Bearer token via `Authorization: Bearer YOUR_TOKEN` header, or session cookie.

**Login:**
```bash
curl -X POST https://app.instapods.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'
```

**Rate Limits:** Login: 5/min, Register: 3/min, Pod creation: 50/hour.

### Authentication Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/auth/register` | Create account |
| POST | `/api/auth/login` | Log in |
| POST | `/api/auth/logout` | Log out |
| GET | `/api/auth/user` | Get current user |
| POST | `/api/auth/forgot-password` | Request password reset |
| POST | `/api/auth/reset-password` | Reset password |

### Pod Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/pods` | List all pods |
| POST | `/api/pods` | Create a pod |
| GET | `/api/pods/{name}` | Get pod details |
| DELETE | `/api/pods/{name}` | Delete a pod |
| POST | `/api/pods/{name}/start` | Start |
| POST | `/api/pods/{name}/stop` | Stop |
| POST | `/api/pods/{name}/restart` | Restart |
| POST | `/api/pods/{name}/reload` | Reload app services |
| POST | `/api/pods/{name}/resize` | Resize (change plan) |
| POST | `/api/pods/{name}/clone` | Clone |

### File Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/pods/{name}/files` | List files |
| GET | `/api/pods/{name}/files/content` | Read file |
| PUT | `/api/pods/{name}/files/content` | Write file |
| POST | `/api/pods/{name}/files/upload` | Upload (multipart, max 32MB) |
| GET | `/api/pods/{name}/files/download` | Download file |
| DELETE | `/api/pods/{name}/files` | Delete file |
| POST | `/api/pods/{name}/files/rename` | Rename/move |
| POST | `/api/pods/{name}/files/copy` | Copy |
| POST | `/api/pods/{name}/folders` | Create folder |

Path validation: Must be absolute, within `/home/instapod`, `/var/www`, or `/tmp`, no `..` traversal.

### SSH Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/pods/{name}/ssh` | Connection info |
| GET/POST/DELETE | `/api/pods/{name}/ssh/keys` | Pod SSH keys |
| GET/POST/PUT/DELETE | `/api/ssh-keys[/{id}]` | Account SSH keys |

### Domain Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/pods/{name}/domains` | List domains |
| POST | `/api/pods/{name}/domains` | Add domain |
| DELETE | `/api/pods/{name}/domains/{id}` | Remove domain |
| POST | `/api/pods/{name}/domains/{id}/verify` | Verify DNS |

### Service Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/pods/{name}/services` | List services |
| POST | `/api/pods/{name}/services` | Install service |
| DELETE | `/api/pods/{name}/services/{type}` | Remove service |
| GET | `/api/pods/{name}/services/{type}/credentials` | Get credentials |

### Git Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/pods/{name}/git` | Get git config |
| POST | `/api/pods/{name}/git` | Connect repo |
| PUT | `/api/pods/{name}/git` | Update settings |
| DELETE | `/api/pods/{name}/git` | Disconnect |
| POST | `/api/pods/{name}/git/deploy` | Trigger deploy |
| GET | `/api/pods/{name}/git/deployments` | List deployments |
| GET | `/api/pods/{name}/git/deployments/{id}` | Deployment detail + build log |
| POST | `/api/pods/{name}/git/rollback` | Rollback |

### Billing Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/billing/subscription` | Get subscription |
| POST | `/api/billing/subscribe` | Subscribe |
| PUT | `/api/billing/subscription/plan` | Change plan |
| POST | `/api/billing/subscription/cancel` | Cancel |
| POST | `/api/billing/subscription/resume` | Resume |
| GET | `/api/billing/invoices` | List invoices |
| GET/POST/DELETE | `/api/billing/payment-methods[/{id}]` | Payment methods |
| POST | `/api/billing/payment-methods/default` | Set default |
| GET | `/api/billing/credits` | Get credits |
| GET | `/api/billing/upcoming` | Preview charges |

Amounts are in cents (e.g., `700` = $7.00). Pods are billed daily. Stopped pods still incur charges - delete to stop billing.

### Catalog Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/plans` | List plans |
| GET | `/api/presets` | List presets |
| GET | `/api/regions` | List regions |
| GET | `/api/runtimes` | List runtimes |

### Pod Object Shape

```json
{
  "id": "abc123",
  "name": "my-app",
  "preset": "nodejs",
  "status": "running",
  "ip": "10.0.0.5",
  "domain": "my-app.nbg1-1.instapods.app",
  "ssh_port": 2201,
  "ssh_user": "instapod",
  "cpu": 1,
  "memory": "512MB",
  "disk": "10GB",
  "plan_slug": "launch",
  "app_root": "/home/instapod/app",
  "region": "eu-nbg",
  "server_name": "instapod-nbg1-1",
  "created_at": "2026-02-20T10:00:00Z"
}
```

Pod statuses: `creating`, `running`, `stopped`, `deleted`, `error`, `suspended`

---

## MCP Overview

The Model Context Protocol (MCP) lets AI assistants like Claude manage your pods directly - create, start, stop, run commands, all through natural language.

**MCP Server URL:** `https://app.instapods.com/api/mcp`

**Supported Clients:** Claude.ai (Custom Connectors), Claude Desktop (remote MCP server), any MCP-compatible client.

**Quick Setup (Claude.ai):**
1. Go to claude.ai → Settings → Connectors
2. Add Connector → enter `https://app.instapods.com/api/mcp`
3. Sign in and approve access
4. Start chatting: "Show me my pods", "Create a Node.js pod called my-api"

---

## MCP Tools Reference

The MCP server exposes 12 tools:

### Pod Management

**list_pods** - List all pods. No parameters. Example: "Show me all my pods"

**get_pod** - Get pod details. Params: `name` (string, required). Example: "What's the status of my-api?"

**create_pod** - Create a new pod. Params: `name` (required), `preset` (required: static/php/nodejs/python), `plan` (optional), `region` (optional). Example: "Create a Python pod called data-api on the build plan"

**manage_pod** - Start, stop, restart, reload, or delete. Params: `name` (required), `action` (required: start/stop/restart/reload/delete). Reload is the most powerful - auto-starts pod, installs deps, detects entry points, restarts services, runs health check. Example: "Restart my-api"

### File Operations

**list_files** - List files in a directory. Params: `name` (required), `path` (optional, default: ~/app). Example: "Show me the files in my-api"

**read_file** - Read file contents. Params: `name` (required), `path` (required). Example: "Show me the package.json in my-api"

**write_file** - Write content to a file. Params: `name` (required), `path` (required), `content` (required). Creates parent directories. Example: "Create an index.js in my-api"

### Command Execution

**exec_command** - Run a shell command. Params: `name` (required), `command` (required). Runs as `instapod` user. Example: "Run npm install express in my-api"

### Logs

**get_logs** - Get application logs. Params: `name` (required), `lines` (optional, default: 100), `service` (optional). Example: "Show me the logs for my-api"

### Catalog

**list_presets** - List available presets (static, php, nodejs, python).

**list_plans** - List pricing plans with resources and prices.

**list_regions** - List deployment regions.

---

## MCP Authentication

MCP uses OAuth 2.0 with PKCE. Handled automatically by AI clients.

**Flow:**
1. Client hits `POST /api/mcp` → gets 401 with OAuth metadata
2. Client auto-registers via RFC 7591 Dynamic Client Registration
3. Browser opens for login and team selection
4. Client exchanges authorization code for access token (PKCE S256)
5. Connected - tools scoped to selected team

**OAuth Endpoints:**
- Discovery: `GET /.well-known/oauth-authorization-server`
- Registration: `POST /api/oauth/register`
- Authorization: `GET /oauth/authorize`
- Token: `POST /api/oauth/token`

**Token lifetime:** 30 days. PKCE required (S256). No client secrets (public clients). HTTPS enforced.

---

## FAQ

**What is a pod?** A persistent Linux server with its own filesystem, SSH access, and public URL. All data survives restarts.

**How long does pod creation take?** 1-2 seconds using pre-built images.

**Can I run multiple apps in one pod?** Technically yes, but we recommend separate pods for separate apps.

**What Linux distribution?** Ubuntu 24.04 LTS (Noble Numbat).

**How do I SSH in?** `ssh instapod@nbg1-1.instapods.app -p YOUR_PORT` or `instapods ssh my-app`.

**Can I access my database remotely?** Not directly (localhost only for security). Use SSH port forwarding: `ssh -L 3306:localhost:3306 instapod@host -p PORT`.

**Do stopped pods cost money?** Yes. Billing is flat monthly, not per-usage. Delete to stop billing.

**Can I change plans?** Yes, anytime. Changes take effect immediately with prorated billing.

**How many custom domains?** Up to 5 per pod with automatic SSL via Let's Encrypt.

---

## Troubleshooting

### SSH: "REMOTE HOST IDENTIFICATION HAS CHANGED"

Port reuse after pod deletion. Fix: `ssh-keygen -R "[nbg1-1.instapods.app]:PORT"`

### SSH: "Permission denied (publickey)"

Add your key: `instapods ssh-keys add my-app`

### App not responding on public URL

Check your app listens on the correct port and binds to `0.0.0.0`:
- Node.js: port 3000, `app.listen(3000, '0.0.0.0')`
- Python: port 8000, `app.run(host='0.0.0.0', port=8000)`

### Pod stuck in "creating"

Delete and recreate: `instapods pods delete my-app -f && instapods pods create my-app --preset nodejs`

### Service stuck in "installing"

Wait 15 seconds. If still stuck, remove and reinstall: `instapods services remove my-app -s mysql -f && instapods services add my-app -s mysql -w`

### "Plan does not allow services"

Upgrade to Build or higher: `instapods pods resize my-app --plan build`

### Domain verification failing

Check DNS propagation: `dig CNAME app.example.com`. Wait a few minutes and retry.