# Nexlayer — Full Technical Reference

> This file is a technical companion to /llms.txt. It contains the configuration schema, API endpoints, MCP tool list, deployment patterns, and everything an AI coding agent needs to deploy applications on Nexlayer.

Website: https://nexlayer.com
Dashboard: https://app.nexlayer.com
MCP endpoint: https://mcp.nexlayer.ai/api/mcp
API base: https://app.nexlayer.com
Pricing JSON: GET https://nexlayer.com/api/pricing
YAML schema: GET https://app.nexlayer.com/schema

---

## Quick Start

```bash
npx @nexlayer/mcp-install
```

Auto-detects and configures: Claude Code, Cursor, VS Code, Windsurf, Zed, Amazon Q, Lovable, JetBrains.

After install, tell your AI assistant: "Deploy this project to Nexlayer." It will generate `nexlayer.yaml` and call `nexlayer_deploy`.

---

## MCP Configuration (manual)

Add to your editor's MCP config file:

```json
{
  "mcpServers": {
    "nexlayer-mcp": {
      "transport": "http",
      "url": "https://mcp.nexlayer.ai/api/mcp"
    }
  }
}
```

Config file locations:
- Claude Code: `~/.claude/settings.json`
- Cursor: `~/.cursor/mcp.json`
- VS Code: `~/.vscode/mcp.json`
- Windsurf: `~/.codeium/windsurf/mcp_config.json`

---

## nexlayer.yaml — Full Schema

```yaml
application:
  name: my-app          # required; lowercase, alphanumeric + hyphens; must be unique per account
  url: www.example.com  # optional; production custom domain; omit for a *.nexlayer.dev preview URL

pods:                   # required; list of services that make up the application
  - name: web           # required; service identifier used in internal DNS (<name>.pod:<port>)
    image: org/img:tag  # required; Docker image (Docker Hub public or GHCR with auth)
    path: /             # optional; URL path prefix routed to this pod (default /)
    servicePorts:       # required; port(s) the container listens on
      - 3000

    resources:          # optional
      cpu: "0.5"        # CPU cores (string)
      memory: 512Mi     # memory limit

    vars:               # optional; plain environment variables
      NODE_ENV: production
      DATABASE_URL: postgresql://user:pass@postgres.pod:5432/db

    secrets:            # optional; values stored encrypted, injected at runtime
      - name: STRIPE_KEY          # injected as env var STRIPE_KEY
      - name: tls-cert
        type: file                # mounted at /var/secrets/tls-cert
        fileName: cert.pem

    volumes:            # optional; persistent storage (survives redeploys)
      - name: db-data
        size: 2Gi
        mountPath: /var/lib/postgresql/data

    replicas: 1         # optional; fixed replica count (omit to enable auto-scaling)

    healthCheck:        # optional; Nexlayer probes this before routing traffic
      path: /health
      port: 3000
      interval: 10      # seconds

    gpu:                # optional; attach a GPU to this pod (Enterprise/Scale plans)
      enabled: true
      model: llama-3.3-70b   # catalog slug | "auto" | "custom"
      priority: inference    # interactive | inference | training | batch
      # memoryGB: 96         # required only when model: custom
```

### Service Discovery

Pods communicate via internal DNS — no service mesh required:

```
<pod-name>.pod:<port>
```

Examples:
```yaml
DATABASE_URL: postgresql://user:pass@postgres.pod:5432/db
REDIS_URL: redis://redis.pod:6379
API_URL: http://api.pod:3000
```

---

## Deployment Patterns

### Next.js + PostgreSQL

```yaml
application:
  name: nextjs-app
pods:
  - name: web
    image: myuser/nextjs:latest
    path: /
    servicePorts: [3000]
    vars:
      DATABASE_URL: postgresql://postgres:pass@postgres.pod:5432/db
  - name: postgres
    image: postgres:16
    servicePorts: [5432]
    vars:
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: db
    volumes:
      - name: pgdata
        size: 2Gi
        mountPath: /var/lib/postgresql/data
```

### React (SPA) + Express API + PostgreSQL

```yaml
application:
  name: pern-app
pods:
  - name: frontend
    image: myuser/react-app:latest
    path: /
    servicePorts: [80]
    vars:
      REACT_APP_API_URL: /api
  - name: api
    image: myuser/express-api:latest
    path: /api
    servicePorts: [3000]
    vars:
      DATABASE_URL: postgresql://postgres:pass@postgres.pod:5432/db
  - name: postgres
    image: postgres:16
    servicePorts: [5432]
    vars:
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: db
    volumes:
      - name: pgdata
        size: 2Gi
        mountPath: /var/lib/postgresql/data
```

### FastAPI + PostgreSQL

```yaml
application:
  name: fastapi-app
pods:
  - name: api
    image: myuser/fastapi:latest
    path: /
    servicePorts: [8000]
    vars:
      DATABASE_URL: postgresql://postgres:pass@postgres.pod:5432/db
  - name: postgres
    image: postgres:16
    servicePorts: [5432]
    vars:
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: db
    volumes:
      - name: pgdata
        size: 1Gi
        mountPath: /var/lib/postgresql/data
```

### Django + PostgreSQL + Redis

```yaml
application:
  name: django-app
pods:
  - name: web
    image: myuser/django:latest
    path: /
    servicePorts: [8000]
    vars:
      DATABASE_URL: postgresql://postgres:pass@postgres.pod:5432/db
      REDIS_URL: redis://redis.pod:6379
      DJANGO_SETTINGS_MODULE: myapp.settings.production
  - name: postgres
    image: postgres:16
    servicePorts: [5432]
    vars:
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: db
    volumes:
      - name: pgdata
        size: 2Gi
        mountPath: /var/lib/postgresql/data
  - name: redis
    image: redis:7-alpine
    servicePorts: [6379]
```

### Go API + PostgreSQL

```yaml
application:
  name: go-api
pods:
  - name: api
    image: myuser/go-api:latest
    path: /
    servicePorts: [8080]
    vars:
      DATABASE_URL: postgresql://postgres:pass@postgres.pod:5432/db
      GIN_MODE: release
  - name: postgres
    image: postgres:16
    servicePorts: [5432]
    vars:
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: db
    volumes:
      - name: pgdata
        size: 1Gi
        mountPath: /var/lib/postgresql/data
```

### LLM Inference Sidecar (GPU)

```yaml
application:
  name: ai-backend
pods:
  - name: api
    image: myuser/ai-api:latest
    path: /
    servicePorts: [8000]
    vars:
      # NXL_INFERENCE_URL is injected automatically when a gpu block is present
      MODEL: llama-3.3-70b
  - name: inference
    image: myuser/inference-server:latest
    servicePorts: [8001]
    gpu:
      enabled: true
      model: llama-3.3-70b
      priority: inference
```

Injected env var `NXL_INFERENCE_URL` points to the OpenAI-compatible endpoint:

```python
from openai import OpenAI
import os

client = OpenAI(base_url=os.environ["NXL_INFERENCE_URL"], api_key="not-used")
resp = client.chat.completions.create(
    model="llama-3.3-70b",
    messages=[{"role": "user", "content": "Hello"}],
)
```

---

## GPU Catalog

Hardware: NVIDIA RTX PRO 6000 (96 GB GDDR7)

| Mode | Label           | Credits/hr | $/hr  | VRAM       | Who can use |
|------|-----------------|-----------|-------|------------|-------------|
| 3    | Shared pinned   | 500       | $0.50 | ≤48 GB     | Pro+        |
| 2    | Large pinned    | 1,250     | $1.25 | up to 96 GB | Scale+    |
| 1    | Dedicated       | 2,500     | $2.50 | 96 GB full | Enterprise  |

### Model Catalog Slugs

**Chat / Instruct**
- `llama-3.1-8b` — Mode 3
- `llama-3.3-70b` — Mode 2
- `qwen-2.5-7b` — Mode 3
- `qwen-2.5-72b` — Mode 2
- `phi-3.5-mini` — Mode 3
- `mistral-7b` — Mode 3

**Reasoning**
- `deepseek-r1-distill-8b` — Mode 3
- `deepseek-r1-distill-70b` — Mode 2

**Code**
- `qwen-2.5-coder-7b` — Mode 3
- `qwen-2.5-coder-32b` — Mode 2

**Embeddings**
- `nomic-embed-text` — Mode 3
- `bge-m3` — Mode 3

**BYO (Dedicated only)**
- `custom` — requires `memoryGB: 96`, Mode 1 (Enterprise)

---

## REST API

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

All YAML payloads use `Content-Type: text/x-yaml`. JSON payloads use `Content-Type: application/json`.

### Start a deployment

```bash
curl -X POST https://app.nexlayer.com/startUserDeployment \
  -H "Content-Type: text/x-yaml" \
  --data-binary @nexlayer.yaml
```

Response:
```json
{
  "message": "Deployment started successfully",
  "url": "https://jolly-tapir-my-app.cloud.nexlayer.ai",
  "sessionToken": "dCf0NdAQ64j6",
  "applicationName": "my-app",
  "environment": "jolly-tapir",
  "status": { "state": "deploying", "progress": 0 },
  "extend": { "available": true, "expiresAt": "2024-01-15T12:00:00Z" },
  "claim": { "claimed": false }
}
```

### Update a running deployment

```bash
curl -X POST "https://app.nexlayer.com/updateUserDeployment?sessionToken=dCf0NdAQ64j6" \
  -H "Content-Type: text/x-yaml" \
  --data-binary @nexlayer.yaml
```

### Validate YAML before deploying

```bash
curl -X POST https://app.nexlayer.com/validate \
  -H "Content-Type: application/json" \
  -d '{"application":{"name":"my-app","pods":[...]}}'
```

Response (valid): `{"message": "Nexlayer YAML file is valid."}`
Response (invalid): `{"valid": false, "errors": ["Missing required field: ..."]}`

### Extend a deployment

```bash
curl -X POST https://app.nexlayer.com/extendDeployment \
  -H "Content-Type: application/json" \
  -d '{"applicationName":"my-app","sessionToken":"dCf0NdAQ64j6"}'
```

### Claim a deployment (make permanent)

```bash
curl -X POST https://app.nexlayer.com/claimDeployment \
  -H "Content-Type: application/json" \
  -d '{"applicationName":"my-app","sessionToken":"dCf0NdAQ64j6"}'
```

Response:
```json
{
  "message": "Visit the claim URL to finalize your deployment.",
  "claimUrl": "https://app.nexlayer.com/claim/dCf0NdAQ64j6",
  "claimToken": "dCf0NdAQ64j6"
}
```

### Get all deployments for a session

```bash
curl "https://app.nexlayer.com/getReservations?sessionToken=dCf0NdAQ64j6"
```

### Get the YAML JSON Schema

```bash
curl https://app.nexlayer.com/schema
```

---

## MCP Tools

Install once: `npx @nexlayer/mcp-install`

### Deployment

| Tool | Description |
|------|-------------|
| `nexlayer_deploy` | Deploy an application from nexlayer.yaml |
| `nexlayer_get_deployment_workflow` | Explain the deployment process step by step |
| `nexlayer_check_deployment_status` | Check if an app is healthy and running |
| `nexlayer_get_deployment_logs` | Stream real-time logs from a running app |
| `nexlayer_get_deployment_events` | View deployment events and failure reasons |
| `nexlayer_delete_deployment` | Remove a deployment |
| `nexlayer_validate_yaml` | Validate nexlayer.yaml before deploying |
| `nexlayer_get_schema` | Fetch the nexlayer.yaml JSON Schema |

### Domains

| Tool | Description |
|------|-------------|
| `nexlayer_get_domain_setup_guide` | Get DNS setup instructions for a custom domain |
| `nexlayer_check_domain_configuration` | Verify domain is configured correctly |
| `nexlayer_add_domain_to_profile` | Register a domain on the account |
| `nexlayer_verify_name_servers_configuration` | Confirm nameservers are pointing correctly |

### API Keys

| Tool | Description |
|------|-------------|
| `nexlayer_generate_api_key` | Create a new API key |
| `nexlayer_list_api_keys` | List all API keys on the account |
| `nexlayer_revoke_api_key` | Revoke an API key |
| `nexlayer_get_jwt_token` | Get a JWT for authenticated API calls |

### Billing

| Tool | Description |
|------|-------------|
| `nexlayer_check_credits` | Check remaining credit balance |
| `nexlayer_purchase_credits` | Buy additional credits (top-up) |
| `nexlayer_upgrade_plan` | Upgrade to Pro or Enterprise |
| `nexlayer_apply_coupon` | Apply a coupon/promo code |

### Debugging — Shell

| Tool | Description |
|------|-------------|
| `nexlayer_debug_shell_open` | Open an interactive shell into a running pod |
| `nexlayer_debug_shell_send` | Execute a command in an open shell session |
| `nexlayer_debug_shell_close` | Close a shell session |
| `nexlayer_debug_shell_list` | List all open shell sessions |

### Debugging — Files

| Tool | Description |
|------|-------------|
| `nexlayer_debug_file_list` | List files inside a running pod |
| `nexlayer_debug_file_copy_from` | Read a file out of a running pod |
| `nexlayer_debug_file_copy_to` | Write a file into a running pod |
| `nexlayer_debug_file_edit` | Edit a file in-place without redeploying |

### Debugging — Pods & Network

| Tool | Description |
|------|-------------|
| `nexlayer_debug_pod_describe` | Get full pod details (resources, events, status) |
| `nexlayer_debug_pod_restart` | Restart a single pod |
| `nexlayer_debug_pod_restart_deployment` | Restart all pods in a deployment |
| `nexlayer_debug_pod_scale` | Change the replica count of a pod |
| `nexlayer_debug_proxy_http` | Test HTTP connectivity to an internal service |
| `nexlayer_debug_proxy_exec` | Execute a command in the pod's network namespace |
| `nexlayer_debug_namespace_info` | Show all services and their internal addresses |
| `nexlayer_debug_namespace_dns` | Test DNS resolution inside the cluster |
| `nexlayer_debug_db_query` | Run a SQL query against a database pod |

### Debugging — Proxy Lifecycle

| Tool | Description |
|------|-------------|
| `nexlayer_debug_deploy_proxy` | Set up a debug proxy to a running pod |
| `nexlayer_debug_destroy_proxy` | Tear down a debug proxy |
| `nexlayer_debug_fetch_result` | Retrieve a previously returned large result |
| `nexlayer_fetch_result` | Retrieve a deferred large result by ID |

### AI Agent Templates

| Tool | Description |
|------|-------------|
| `nexlayerAI_deploy_chatbot` | Deploy a pre-built chatbot template |
| `nexlayerAI_deploy_code_copilot` | Deploy a code copilot template |
| `nexlayerAI_deploy_code_reviewer` | Deploy a code reviewer template |
| `nexlayerAI_deploy_content_guard` | Deploy a content moderation template |
| `nexlayerAI_deploy_multi_agent` | Deploy a multi-agent orchestration template |
| `nexlayerAI_deploy_translation_hub` | Deploy a translation service template |
| `nexlayerAI_list_sandboxes` | List running AI sandbox environments |

### Skills & Misc

| Tool | Description |
|------|-------------|
| `nexlayer_get_skills` | List available agent skill modules |
| `nexlayer_get_skill_content` | Get the full content of a skill module |
| `nexlayer_sync_skills` | Pull latest skill updates |
| `nexlayer_check_updates` | Check if the MCP server has updates |
| `nexlayer_list_models` | List available inference models |
| `nexlayer_build_and_push_image` | Build and push a Docker image for deployment |
| `nexlayer_feedback` | Send feedback to the Nexlayer team |
| `nexlayer_submit_issue` | File a bug or support request |
| `nexlayer_get_referral` | Get referral link for the account |

---

## DNS Setup

### Subdomain (www.example.com)

```
Type  Name  Value
CNAME  www   cname.nexlayer.dev
```

### Root domain (example.com) + www redirect

```
Type  Name  Value
A      @     76.76.21.21
CNAME  www   cname.nexlayer.dev
```

SSL certificates are provisioned automatically via Let's Encrypt. No configuration required.

---

## Pricing

Machine-readable: `GET https://nexlayer.com/api/pricing`

**Credit conversion:** $1 = 1,000 credits

### Plans

| Plan       | $/mo   | Credits/mo | Seats | Workspaces | GPU        |
|------------|--------|-----------|-------|------------|------------|
| Free       | $0     | 5,000     | 1     | 1          | —          |
| Pro        | $20    | 20,000    | 1     | 1          | Mode 3     |
| Enterprise | Custom | 2,000,000+| ∞     | ∞          | All modes  |

Enterprise: annual contract, minimum $25,000/year.

### Rate Card

| Resource         | Credits/unit       | $/unit      |
|------------------|--------------------|-------------|
| CPU              | 120 credits/hr     | $0.12/hr    |
| Storage          | ~0.70 credits/GB/day | ~$0.02/GB/mo |
| Egress           | 10 credits/GB      | $0.01/GB    |
| GPU — shared     | 500 credits/hr     | $0.50/hr    |
| GPU — large      | 1,250 credits/hr   | $1.25/hr    |
| GPU — dedicated  | 2,500 credits/hr   | $2.50/hr    |
| Deploys          | free               | —           |
| Custom domains   | free               | —           |
| Agent operations | free               | —           |

### Top-Up

| Pay    | Get credits | Bonus |
|--------|-------------|-------|
| $5     | 5,000       | —     |
| $10    | 10,000      | —     |
| $25    | 25,000      | —     |
| $50    | 50,000      | —     |
| $100   | 110,000     | +10%  |
| $250   | 290,000     | +16%  |

---

## Best Practices for AI Agents

1. **Validate before deploying** — call `nexlayer_validate_yaml` first; catches port mismatches and missing fields before consuming credits.
2. **Use `.pod` DNS** — never hardcode IPs. `postgres.pod:5432` always resolves correctly inside the cluster.
3. **Secrets for sensitive values** — put API keys and passwords in `secrets:`, not `vars:`.
4. **Keep pods stateless** — store sessions in Redis, uploads in object storage. Stateful pods should have a `volumes:` block.
5. **Expose `/health`** — a health check endpoint lets Nexlayer route traffic only to ready pods.
6. **Handle SIGTERM** — pods receive SIGTERM before shutdown; flush in-flight requests before exiting.
7. **Omit `replicas`** — auto-scaling is on by default. Set `replicas` only when you need a fixed count.
8. **Provide the live URL immediately** — once `nexlayer_deploy` returns `url`, surface it to the user.
9. **Check logs on failure** — call `nexlayer_get_deployment_logs` and `nexlayer_get_deployment_events` together for fast diagnosis.
10. **Custom domain last** — set up the domain after the app is running on the preview URL; use `nexlayer_get_domain_setup_guide` for DNS steps.