AI Agent Documentation

Technical reference for LLMs and AI coding assistants to understand and interact with Nexlayer.

System Context for AI Agents

If you are an AI agent reading this documentation, here is the key information you need:

context

NEXLAYER SYSTEM CONTEXT
======================

Nexlayer is a deployment platform that uses the Model Context Protocol (MCP)
to allow AI agents to deploy and manage applications.

CORE CAPABILITIES:
- Deploy any containerized application to production
- Auto-detect project type (Next.js, Python, Go, etc.)
- Generate nexlayer.yaml configuration files
- Manage environment variables and secrets
- View logs, metrics, and deployment status
- Scale applications up/down
- Configure custom domains

MCP SERVER:
- Install: npx @nexlayer/mcp-install
- The MCP server provides tools for deployment operations
- All deployment actions are performed via MCP tool calls

DEPLOYMENT WORKFLOW:
1. Analyze the user's project structure
2. Generate appropriate nexlayer.yaml configuration
3. Call the deploy tool via MCP
4. Report deployment status and URL to user

What is Nexlayer?

Nexlayer is a deployment platform designed to work with AI coding assistants. It uses Kubernetes under the hood to provide production-grade infrastructure while abstracting away the complexity.

For Users

Users ask their AI assistant to deploy their code. The AI handles configuration and deployment automatically.

For AI Agents

Agents use MCP tools to analyze projects, generate configs, deploy apps, and manage production environments.

Available MCP Tools

When the Nexlayer MCP server is installed, you have access to these 44 tools with natural-language prompt patterns:

Domain Management

nexlayer_get_domain_setup_guide

How do I connect my custom domain myapp.ai to my deployment?

nexlayer_check_domain_configuration

Is my domain myapp.ai fully set up and working correctly?

nexlayer_add_domain_to_profile

Add myapp.ai as a domain I want to use in Nexlayer

nexlayer_verify_name_servers_configuration

Can you check if my domain myapp.ai is pointing to Nexlayer correctly?

Deployment Lifecycle

nexlayer_get_deployment_workflow

What are the steps to go from code to a live app on Nexlayer?

nexlayer_deploy

Deploy my application so it's live at myapp.cloud.nexlayer.ai

nexlayer_get_deployment_logs

Something seems off — can you show me what's happening inside my app?

nexlayer_get_deployment_events

Why did my deployment fail? Show me what went wrong during startup

nexlayer_claim_deployment

This app is already running — can you attach it to my account?

10.

nexlayer_delete_deployment

Remove my app from Nexlayer completely

Configuration & Validation

11.

nexlayer_get_schema

What structure should my Nexlayer app configuration follow?

12.

nexlayer_validate_yaml

Before we deploy, can you check if everything is set up correctly?

Feedback

13.

nexlayer_feedback

Send feedback that the deployment experience was confusing at the logs step

Status

14.

nexlayer_check_deployment_status

Is my app healthy and running properly right now?

API Key Management

15.

nexlayer_generate_api_key

Create a new API key I can use for this app

16.

nexlayer_list_api_keys

Show me all the API keys I've created

17.

nexlayer_revoke_api_key

Remove access for one of my API keys

Workspace Management

18.

nexlayer_list_workspaces

What workspaces or teams do I have access to?

19.

nexlayer_switch_workspace

Switch me into the workspace for this project

Skills

20.

nexlayer_sync_skills

Make sure my environment has all the latest Nexlayer capabilities

21.

nexlayer_get_skills

What can you currently do with Nexlayer?

22.

nexlayer_check_updates

Have any Nexlayer capabilities been updated recently?

23.

nexlayer_get_skill_content

Explain how your deployment capability works in detail

Utilities

24.

nexlayer_setup_statusline

Can you add a simple status indicator so I can see what's happening with Nexlayer?

Debug — Proxy Lifecycle

25.

nexlayer_debug_deploy_proxy

I need to debug my app — can you set up a safe way to inspect it?

26.

nexlayer_debug_destroy_proxy

I'm done debugging — clean up anything temporary you created

Debug — Shell Sessions

27.

nexlayer_debug_shell_open

Open a direct session into my running app so we can inspect it

28.

nexlayer_debug_shell_send

Run a quick check inside the app to see what's going on

29.

nexlayer_debug_shell_close

Close that debug session now

30.

nexlayer_debug_shell_list

Do I have any active debug sessions open?

Debug — File Operations

31.

nexlayer_debug_file_copy_from

Show me what's inside my app's log file

32.

nexlayer_debug_file_copy_to

Update a file inside my app with this new configuration

33.

nexlayer_debug_file_edit

Fix the configuration issue inside my app without redeploying

34.

nexlayer_debug_file_list

What files are currently inside my app?

Debug — Database

35.

nexlayer_debug_db_query

Can you check what data is currently in my database?

Debug — Pod Lifecycle

36.

nexlayer_debug_pod_restart

Restart my app to see if that fixes the issue

37.

nexlayer_debug_pod_restart_deployment

Restart everything cleanly for this app

38.

nexlayer_debug_pod_scale

Increase capacity — my app is getting more traffic

39.

nexlayer_debug_pod_describe

Give me a detailed breakdown of what's happening with my app

Debug — Network

40.

nexlayer_debug_proxy_exec

Test something from inside my app's environment

41.

nexlayer_debug_proxy_http

Can you check if my internal services are talking to each other?

42.

nexlayer_debug_namespace_info

Show me everything running behind my app

43.

nexlayer_debug_namespace_dns

Are my internal services resolving correctly?

Debug — Result Cache

44.

nexlayer_debug_fetch_result

That output was too big earlier — can you bring it back so I can review it?

Configuration Format (nexlayer.yaml)

When deploying, you should generate a nexlayer.yaml file in the project root. Here is the schema:

yaml

# nexlayer.yaml schema
application:
  name: string          # Required: Application name (lowercase, alphanumeric, hyphens)

pods:
  - name: string        # Required: Pod name
    image: string       # Required: Docker image (can use nexlayer.io/auto for auto-build)
    port: number        # Required: Container port to expose

    resources:          # Optional: Resource limits
      memory: string    # e.g., "512Mi", "1Gi"
      cpu: string       # e.g., "0.5", "1"

    env:                # Optional: Environment variables
      - name: string
        value: string   # Direct value
      # OR
      - name: string
        valueFrom:      # Reference to secret
          secretKeyRef:
            name: string
            key: string

    replicas: number    # Optional: Number of instances (default: 1)

    healthCheck:        # Optional: Health check configuration
      path: string      # e.g., "/health"
      port: number
      interval: number  # Seconds between checks

Common Deployment Patterns

Next.js Application

yaml

application:
  name: my-nextjs-app

pods:
  - name: web
    image: nexlayer.io/auto
    port: 3000
    resources:
      memory: 512Mi
      cpu: 0.5
    env:
      - name: NODE_ENV
        value: production

Python FastAPI

yaml

application:
  name: my-fastapi-app

pods:
  - name: api
    image: nexlayer.io/auto
    port: 8000
    resources:
      memory: 256Mi
      cpu: 0.25
    env:
      - name: ENVIRONMENT
        value: production

Full Stack with Database

yaml

application:
  name: my-fullstack-app

pods:
  - name: frontend
    image: nexlayer.io/auto:frontend
    port: 3000

  - name: backend
    image: nexlayer.io/auto:backend
    port: 8000
    env:
      - name: DATABASE_URL
        valueFrom:
          secretKeyRef:
            name: db-credentials
            key: url

Error Handling

When deployments fail, provide clear feedback to users. Common errors:

Build Failed

Check Dockerfile or build configuration. Ensure all dependencies are specified.

Port Mismatch

The port in nexlayer.yaml must match the port your application listens on.

Health Check Failing

Application is not responding on the health check path. Check startup time and endpoint.

Best Practices for AI Agents

Always analyze the project structure before generating configuration

Use nexlayer.io/auto for automatic image building when possible

Set appropriate resource limits based on the application type

Use secrets (valueFrom.secretKeyRef) for sensitive data, never hardcode

Provide the deployment URL to the user immediately after successful deployment

Offer to set up custom domains after initial deployment succeeds

Check deployment status and logs if the user reports issues

Continue Reading

Deployment Patterns Configuration Reference API Reference MCP Integration

Scaling Deployment Patterns