> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instapods.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating a Pod

> Step-by-step guide to creating your first pod on InstaPods.

## From the Dashboard

1. Navigate to the **Dashboard** and click **Create Pod**

2. Fill in the creation form:

   * **Name**: A unique name for your pod. Must be lowercase alphanumeric with hyphens (e.g., `my-app`, `staging-api`). This becomes your subdomain.
   * **Preset**: Choose your development stack — Static, PHP, Node.js, or Python
   * **Version** (optional): For PHP, Node.js, and Python, pick a runtime version (e.g., Node.js 22, PHP 8.4). Defaults to the latest stable.
   * **Plan**: Select a resource tier — Launch, Build, Grow, Scale, or Turbo
   * **Region** (optional): Pick a geographic region, or leave blank for auto-selection
   * **SSH Key** (optional): Paste a public SSH key for immediate access

3. Click **Create**

Your pod will be ready in 1-2 seconds. You'll be redirected to the pod detail page.

## From the CLI

```bash theme={null}
instapods pods create my-app -p nodejs --plan build
```

### Available Flags

| Flag            | Description                                            | Default               |
| --------------- | ------------------------------------------------------ | --------------------- |
| `-p, --preset`  | Preset slug: `static`, `php`, `nodejs`, `python`       | Auto-detected         |
| `-v, --version` | Runtime version (e.g., `8.4`, `22`, `3.11`)            | Preset default        |
| `--plan`        | Plan slug: `launch`, `build`, `grow`, `scale`, `turbo` | `launch`              |
| `-r, --region`  | Region slug (e.g., `eu-nbg`)                           | Auto-select (closest) |
| `--ssh-key`     | SSH public key or path to key file                     | None                  |
| `-w, --wait`    | Wait until pod is running before returning             | `false`               |
| `--timeout`     | Max seconds to wait for pod creation                   | `120`                 |

The CLI returns immediately by default. Use `-w` to wait until the pod is fully running.

If `--preset` is omitted, the CLI auto-detects from your current directory (e.g., `package.json` → Node.js, `requirements.txt` → Python).

### Examples

```bash theme={null}
# Basic creation
instapods pods create my-site -p static

# With specific plan and region
instapods pods create api-server -p nodejs --plan scale -r eu-nbg

# With SSH key
instapods pods create dev-env -p python --ssh-key ~/.ssh/id_ed25519.pub

# With a specific runtime version
instapods pods create my-app -p nodejs --version 22

# Wait until pod is fully running
instapods pods create my-site -p static -w
```

## From the API

```bash theme={null}
curl -X POST https://app.instapods.com/api/pods \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "preset": "nodejs",
    "plan": "build",
    "region": "sg",
    "ssh_key": "ssh-ed25519 AAAA... user@host"
  }'
```

## What Happens During Creation

1. **Server selection** — The orchestrator picks the best server in your chosen region (or the closest region if unspecified)
2. **Container launch** — A container is created from the pre-built image for your preset
3. **Network setup** — A unique SSH port is allocated and the proxy route is configured
4. **DNS** — Your pod's subdomain is immediately available via wildcard DNS

## Pod Naming Rules

* Lowercase letters, numbers, and hyphens only
* Must start with a letter
* 3-40 characters long
* Must be unique within the platform
* The name becomes your subdomain: `{name}.{server-domain}`