Sealos

file: ./content/docs/community.en.mdx meta: { "title": "社区", "description": "欢迎加入 Sealos 开源社区" }

file: ./content/docs/index.en.mdx meta: { "title": "Sealos Docs", "description": "Find quickstart guides, tutorials, best practices, deployment templates, system design docs, self-hosting solutions and more cloud native resources." }

import { Text, Code, Play, Database } from 'lucide-react'; import { templateDomain } from '@/config/site';

<Card icon={} href="/docs/guides/devbox" title="Guides"> Learn how to create and manage your Projects, develop your application, create releases, and deploy your application.

<Card icon={} href="/docs/quick-start" title="Quickstarts"> Develop & deploy in minutes. Jump start your development with Sealos DevBox.

<Card icon={} href="/docs/guides/databases/postgresql" title="Databases"> Step-by-step guides on how to deploy and connect to databases in Sealos DevBox.

---

import { NodejsIcon, GoIcon, JavaIcon, PHPIcon, PythonIcon, RustIcon, } from '@/components/ui/icons';

<Card icon={} href="/docs/guides/databases/postgresql/go" title="Go"> Go is a statically typed, compiled programming language designed at Google.

<Card icon={} href="/docs/guides/databases/postgresql/java" title="Java"> Java is a high-level, class-based, object-oriented programming language that is designed to have as few implementation dependencies as possible.

<Card icon={} href="/docs/guides/databases/postgresql/php" title="PHP"> PHP is a popular general-purpose scripting language that is especially suited to web development.

<Card icon={} href="/docs/guides/databases/postgresql/python" title="Python"> Python is an interpreted, high-level, general-purpose programming language.

<Card icon={} href="/docs/guides/databases/postgresql/rust" title="Rust"> Rust is a systems programming language that runs blazingly fast, prevents segfaults, and guarantees thread safety.

---

<Card href={templateDomain + '/deploy?templateName=wordpress'} title="Wordpress" />

<Card href={templateDomain + '/deploy?templateName=flarum'} title="Flarum" />

<Card href={templateDomain + '/deploy?templateName=headscale'} title="Headscale" />

<Card href={templateDomain + '/deploy?templateName=teable'} title="Teable" />

<Card href={templateDomain + '/deploy?templateName=s-pdf'} title="Stirling-PDF" />

file: ./content/docs/quick-start.en.mdx meta: { "title": "Quick Start Tutorial", "icon": "Album", "keywords": [ "Sealos DevBox", "Next.js", "cloud development", "Kubernetes", "OCI image", "Cursor IDE", "remote development", "cloud deployment", "containerization", "DevOps" ], "description": "Learn how to create, develop, and deploy a Next.js app using Sealos DevBox. This guide covers project setup, remote development with Cursor IDE, and cloud deployment." }

import { AppDashboardLink } from '@/components/docs/Links';

Sealos DevBox is an all-in-one platform designed for integrated online development, testing, and production. It offers a seamless solution for creating environments and database dependencies with just a single click, allows developers to work locally using their preferred IDEs while streamlining setup processes and enabling automatic application deployment.

In this guide We'll demonstrate how to how to create a minimal Next.js demo project with Sealos DevBox.

Create a DevBox Project

• Scroll down to the "Network" section of the configuration page.

• Container Port:

  • Enter "3000" in the Container Port field. This is the default port that Next.js uses for development.
  • If you need additional ports, click the "Add Port" button and specify them.

• Enable Internet Access:

  • Toggle the switch to enable internet access for your DevBox. This allows external users to access your Next.js application through the public internet using the provided domain.

• Domain:

  • By default, Sealos provides a subdomain for your application.
  • If you want to use a custom domain, click on "Custom Domain" and follow the instructions to set it up.

Remember that the container port (3000) should match the port your Next.js application is configured to run on. If you change the port in your Next.js configuration, make sure to update it here as well.

Connect with Cursor IDE

After creating your project, you'll see it listed in the DevBox List. Each project has an "Operation" column with various options.

• Locate your project in the DevBox List.
• In the "Operation" column, click on the dropdown arrow next to the VSCode icon.
• From the dropdown menu, select "Cursor".
• Click on the "Cursor" option that appears.

• Follow the instructions in the Cursor popup to install the DevBox plugin.
• Once installed, Cursor will establish a remote connection to your DevBox runtime.

Develop

This remote connection allows you to develop your Next.js application using Cursor IDE, with all the benefits of a cloud-based development environment: - Your code runs in the DevBox runtime, ensuring consistency across development and production environments. - You can access your project from anywhere, on any device with Cursor installed. - Collaboration becomes easier as team members can connect to the same DevBox runtime.

• Open the terminal within Cursor IDE.
• Navigate to your project directory if you're not already there.
• Run the following command to start the Next.js development server:

  npm run dev
  

• This command will start your Next.js application in development mode.

• Return to the Sealos DevBox List in your browser.
• Find the project you just created.
• Click on the "Detail" button on the right side of your project's row.

• Look for the "Network" section.
• You'll see an "External Address" field.
• Click on this external address.

Release

After you've developed and tested your Next.js application, you can release it as an OCI (Open Container Initiative) image. This allows you to version your application and prepare it for deployment.

1. In the Cursor IDE terminal, navigate to your project directory and run the build command:

   npm run build
   

   This command creates a production-ready build of your Next.js application in the '.next' directory.

2. Navigate to your project's details page:

   • Go to the Sealos DevBox List in your browser.
   • Find your project and click on the "Detail" button on the right side of your project's row.

3. On the project details page, look for the "Version" section.

4. Click on the "Release" button located in the top right corner of the "Version" section.

5. A "Release" dialog box will appear. Here, you need to provide the following information:

   • Image Name: This field is pre-filled with your project's image name.
   • Tag: Enter a version tag for your release (e.g., v1.0).
   • Description: Provide a brief description of this release (e.g., "Initial release" or "Bug fixes for login feature").

   

6. After filling in the required information, click the "Release" button at the bottom of the dialog box.

7. The system will process your release. Once completed, you'll see a new entry in the "Version" section of your project details page, showing the tag, status, creation time, and description of your release.

   

By following these steps, you've successfully created an OCI image of your Next.js application. This image can now be used for deployment or shared with other team members. Each release creates a snapshot of your current code, allowing you to maintain different versions of your application and easily roll back if needed.

Deploy

After releasing your Next.js application as an OCI image, you can deploy it to Sealos Cloud for production use. Here's how to do it:

1. In your project's details page, locate the "Version" section.

2. Find the release you want to deploy and click the "Deploy" button in the "Operation" column.

3. This will redirect you to the App Launchpad application within Sealos.

4. In the App Launchpad application, follow the deployment wizard to configure your application settings. This may include:

   • Selecting the appropriate environment
   • Setting resource limits (CPU, memory)
   • Configuring environment variables if needed
   • Setting up any required volumes or persistent storage

   

5. Once you've configured all necessary settings, click the "Deploy Application" button in the top right corner to start the deployment process.

6. You'll be taken to the application details view within App Launchpad.

7. Once the status is "Running", Click on the address provided under "Public Address". This will open your deployed Next.js application in a new browser tab.

   

By following these steps, you've successfully deployed your Next.js application to Sealos Cloud using the App Launchpad application. Your application is now accessible via the public address, allowing users to interact with it from anywhere on the internet.

This workflow allows you to develop and debug your Next.js application in a cloud environment while still using your preferred local IDE. The external address makes it easy to share your work with team members or clients, as they can access your running application from anywhere with an internet connection.

file: ./content/docs/AI/mcp.en.mdx meta: { "title": "MCP (Model Context Protocol)", "description": "Learn how to use Model Context Protocol (MCP) services on the Sealos platform to connect AI models with external tools and data sources through standardized interfaces.", "keywords": [ "MCP", "Model Context Protocol", "Sealos", "AI integration", "large language models", "tool calling" ] }

What is Model Context Protocol (MCP)?

The Model Context Protocol (MCP) is a game-changing standard that lets AI models talk to external tools and data sources seamlessly. Instead of building custom integrations for every service, developers can integrate once and connect to any MCP-compatible system.

The Problem MCP Solves

Here's the challenge: AI models are smart, but they're isolated. They can't access your databases, check your billing, or run code in your development environment. To make AI truly useful, you need to connect it to real-world systems.

The traditional approach? Build custom integrations for every single service. Each one has different APIs, authentication methods, and data formats. It's a maintenance nightmare that gets worse as you add more tools.

MCP Changes Everything

MCP is like having a universal translator for AI integrations. Here's how it works:

For Developers: Write one MCP integration and connect to any MCP-compatible service. No more custom connectors for every tool.

For Service Providers: Build one MCP interface and instantly work with any MCP-enabled AI application.

Think USB-C for AI: Just like USB-C replaced dozens of different charging cables, MCP replaces dozens of different API integrations with one standard protocol.

How MCP Works: The Three-Part System

MCP uses a simple client-server model with three key components:

• MCP Host: Your AI application (like Cursor, VS Code, or ChatGPT)
• MCP Client: The connection bridge that your AI app creates
• MCP Server: The external service that provides tools and data (like Sealos)

Simple Example: Your Cursor editor (Host) creates a connection (Client) to talk to Sealos services (Server). Want to connect to multiple services? Your editor just opens multiple connections.

Sealos MCP: Your Cloud Platform, AI-Ready

Sealos has built MCP servers for all its major platform capabilities. Using StreamableHttp communication, these servers work seamlessly with any MCP-compatible IDE or AI application.

Bottom line: You can now control your entire Sealos infrastructure through natural language conversations with AI.

What You Can Do with Sealos MCP

Here's what's available right now:

• 🛠️ DevBox: Spin up development environments and run code
• 🗄️ Database: Query and manage your databases
• 💰 Cost Center: Check billing and manage expenses
• 📊 Observability: Monitor performance and view logs

Note: Service availability varies by region. Check your Sealos console to see what's available in your zone.

Quick Authentication Setup

Sealos uses your KubeConfig for authentication. Here's the simple 3-step process:

Step 1: Get Your KubeConfig

1. Go to Sealos Console
2. Click your profile picture (top right)
3. Select "KubeConfig" and copy the content

Step 2: URL Encode It

Choose any of these methods to URL-encode your KubeConfig:

Method 1: Online Tool (Easiest)

1. Open URL Encoder or search "URL encoder"
2. Paste your KubeConfig content
3. Click "Encode"
4. Copy the encoded result

Method 2: Browser Console

1. Press F12 on any webpage to open developer tools
2. Go to "Console" tab
3. Type this and press Enter:

   encodeURIComponent(`paste your KubeConfig here`)
   

4. Copy the encoded output

Method 3: Python (if installed)

1. Open terminal
2. Type python3 to enter Python
3. Run this code:

   import urllib.parse
   kubeconfig = """paste your KubeConfig here"""
   encoded = urllib.parse.quote(kubeconfig)
   print(encoded)
   

4. Copy the encoded result

Step 3: Use It Add this header to your MCP configuration:

Authorization: <your-url-encoded-kubeconfig>

Example: apiVersion: v1 becomes apiVersion%3A%20v1

Pro Tip: Save your encoded KubeConfig somewhere safe—you'll use it for all MCP configurations.

Ready to Get Started?

Before You Begin: Two Things You Need

1. Your MCP Service URL

• Log into Sealos Console
• Find the MCP services section for your region
• Copy the URL for the service you want to use

2. Your Authentication Token

• Follow the authentication steps above to get your URL-encoded KubeConfig
• Keep it handy—you'll paste it into your IDE configuration

That's it! Now let's connect your favorite AI tool to Sealos.

Connect Your AI Tool to Sealos

Cherry Studio Setup

Cherry Studio makes MCP configuration visual and straightforward.

Quick Setup:

1. Settings → MCP Servers → Add Server
2. Fill in the details:
   • Name: Sealos (or whatever you prefer)
   • Type: Streamable HTTP (StreamableHttp)
   • URL: Your Sealos MCP service URL
   • Headers: Authorization=<your-url-encoded-kubeconfig>
3. Hit the green start button and wait for "Connected" status

Start Using It: Once connected, just chat normally. When you need Sealos functionality, select the MCP tools and ask.

VS Code Setup

VS Code gets MCP powers through extensions. Here's the streamlined setup:

Quick Setup:

1. Open AI Chat (right sidebar) → Agent Mode → Tools icon
2. Find MCP settings → Gear icon → Add new server
3. Configure:
   • Name: Sealos Platform
   • URL: Your Sealos MCP service URL
   • Headers:

   {
     "Authorization": "<your-url-encoded-kubeconfig>"
   }
   

4. Save → VS Code auto-connects

Code While You Chat: Now you can ask your AI assistant to interact with Sealos while you code.

Cursor Setup

Cursor has the best native MCP support. Setup is super clean:

Quick Setup:

1. Settings gear (top right) → MCP Servers → New MCP Server
2. Paste this config (replace the URL and auth token):

   {
     "name": "Sealos MCP",
     "url": "https://your-sealos-mcp-endpoint.com",
     "headers": {
       "Authorization": "<your-url-encoded-kubeconfig>"
     }
   }
   

3. Save → Cursor auto-verifies → Look for "Connected" status

AI-Powered Development: Now your AI coding assistant can manage your entire Sealos infrastructure.

Trae Setup

Trae keeps it simple with manual JSON configuration.

Quick Setup:

1. Gear icon (top right) → MCP → Add → Manual Configuration
2. Paste this config (update URL and auth):

   {
     "name": "Sealos MCP",
     "url": "https://your-sealos-mcp-endpoint.com",
     "headers": {
       "Authorization": "<your-url-encoded-kubeconfig>"
     }
   }
   

3. Confirm → You're connected!

Explore Your Tools: Click your server name to see all available Sealos tools and what they do.

Cline Setup

Cline is a powerful AI coding assistant that runs directly in VS Code with native MCP support. It can write code, execute commands, browse the web, and more.

Setup Steps:

1. Install the Cline extension in VS Code and restart
2. Add server via interface:
   • Click "MCP Servers" icon (purple button) → "Remote Servers" tab
   • Server Name: sealos
   • Server URL: https://your-sealos-mcp-endpoint.com
   • Click "Add Server"
3. Complete configuration:
   • Click "Edit Configuration" to open cline_mcp_settings.json
   • Add the complete configuration for the sealos server:

   {
     "mcpServers": {
       "sealos": {
         "type": "streamableHttp",
         "url": "https://your-sealos-mcp-endpoint.com",
         "headers": {
           "Authorization": "<your-url-encoded-kubeconfig>"
         },
         "disabled": false,
         "autoApprove": [],
         "timeout": 60
       }
     }
   }
   

   Important: Replace <your-url-encoded-kubeconfig> with your actual URL-encoded KubeConfig from the steps above.
4. Save → Cline auto-verifies → Look for "Connected" status

What You Can Do: Now you can ask Cline to manage your entire Sealos infrastructure.

Pro Tips:

• Add trusted tools to autoApprove for faster workflows
• Use environment variables for sensitive auth tokens
• Set appropriate timeout values for long-running operations

When Things Don't Work

"Connection Failed" - Fix It Fast

Most Common Cause: Wrong URL or bad auth token

Quick Fixes:

1. Double-check your MCP service URL - Copy it fresh from Sealos console
2. Re-encode your KubeConfig - Authentication tokens can get corrupted
3. Test your network - Can you reach sealos.run in your browser?
4. Check the obvious - Typos in configuration happen to everyone

"Authentication Error" - Get Back In

What Happened: Your KubeConfig is invalid or expired

Fix It:

1. Get a fresh KubeConfig from Sealos console
2. Make sure you copied the whole thing - Missing characters break everything
3. Re-encode it properly - Use a reliable URL encoder
4. Check your header format - Should be Authorization: <encoded-config>

"Tool Calls Failing" - Restore Functionality

Likely Issues: Permissions or service availability

Solutions:

1. Verify your account permissions - Do you have access to the service you're calling?
2. Check service status - Is the service running in your region?
3. Look at error messages - They usually tell you exactly what's wrong
4. Try a simple test - Start with basic operations before complex ones

Pro Debugging Tips

• Check connection status first - Your IDE shows if MCP is connected
• Enable verbose logging - More info = faster fixes
• Test one thing at a time - Don't change multiple settings simultaneously
• When in doubt, restart - Sometimes IDEs need a fresh start after configuration changes

Resources & Next Steps

Essential Links

Learn More:

• Official MCP Documentation - Deep dive into the protocol
• Sealos Platform Docs - Everything about Sealos
• AI Proxy Service - Sealos AI integration options

Compatible Tools:

• Cherry Studio - Clean AI chat interface
• Cursor - Best-in-class AI code editor
• VS Code - Works with MCP extensions
• Cline - AI coding assistant for VS Code
• Claude Desktop - Anthropic's desktop app
• Any other MCP-compatible application

Need Help?

Stuck? Here's where to go:

1. Start here - Re-read the troubleshooting section above
2. Community help - Discord for peer support
3. Bug reports - GitHub Issues for technical problems
4. Direct support - Contact Sealos support for urgent issues

file: ./content/docs/advanced/architecture.en.mdx meta: { "title": "Architecture" }

Sealos DevBox is an advanced development environment solution that leverages cloud-native Container and Kubernetes technologies to offer a unified and flexible development Runtime. Its key feature is simulating a traditional virtual machine experience while maintaining containerization benefits.

Architecture

Sealos DevBox is built on a layered architecture, comprising these key components:

Control Flow

DevBox implements a decoupled front-end and back-end design:

1. Users trigger actions via the web interface or plugins
2. DevBox Controller receives and processes these requests
3. Controller translates the processed instructions into Kubernetes API calls
4. Kubernetes executes the corresponding Container operations

State Persistence Mechanism

DevBox employs an intelligent state preservation system to maintain user environment consistency:

Automatic Saving

• System auto-saves user environment changes under specific conditions
• Changes are packaged as image layers
• New layers are appended to the base image as commits
• Updated images are securely stored in an isolated internal registry

Environment Recovery

• On subsequent startups, system boots from the most recent image
• Ensures full preservation of historical changes

Optimization

The Container-shim layer provides automated maintenance:

• Regularly merges image layers to optimize storage
• Automatically cleans up redundant data
• Optimizes image size and layer count for optimal system performance

file: ./content/docs/examples/build-your-own-discord-bot.en.mdx meta: { "title": "Build Your Own Discord Bot", "description": "Build an AI-powered Discord bot using DevBox. You'll create a bot that can respond to messages using AI capabilities powered by FastGPT." }

Overview

This example demonstrates how to build an AI-powered Discord bot using DevBox. You'll create a bot that can respond to messages using AI capabilities powered by FastGPT, showcasing how to integrate multiple services and APIs in a DevBox environment.

Technologies Used:

• Node.js
• Discord.js
• FastGPT API
• DevBox development environment

Expected Outcome:

• A functioning Discord bot that:
  • Responds to basic commands
  • Integrates with FastGPT for AI-powered responses
  • Handles real-time message events
  • Processes natural language queries

Prerequisites

• A Discord account with administrator privileges
• Basic knowledge of JavaScript/Node.js
• Access to FastGPT platform
• The following credentials:
  • Discord Bot Token
  • FastGPT API Key
  • FastGPT Base URL

Step-by-Step Guide

1. Setting Up Discord Application

1. Visit the Discord Developer Portal
2. Click "New Application" and choose a name for your bot. This name will be displayed in your Discord server

Configure Bot Permissions

1. Navigate to the "Bot" section
2. Enable required intents:
   • Server Members Intent
   • Message Content Intent These permissions allow the bot to:
     • Access member-related events
     • Read and process message content
3. Copy your bot token by clicking "Reset Token" and then "Copy"
   • Keep this token secure and never share it
   • You'll need this token to authenticate your bot

Set Up OAuth2

1. Go to OAuth2 section
2. Select "bot" scope
3. Choose "Administrator" permissions
4. Copy the generated OAuth2 URL
5. Use the URL to add the bot to your server

2. Creating DevBox Project

1. Create a new DevBox project
2. Select Node.js as the runtime
3. Configure project resources:
   • Set appropriate CPU cores
   • Allocate required memory

Set Up Development Environment

1. Connect to Your Development Environment
2. Install required dependencies:

npm init -y
npm install discord.js axios dotenv

3. Update package.json to enable ES modules:

{
  "type": "module",
  "scripts": {
    "start": "node src/index.js"
  }
}

Project Structure

Create the following file structure:

project/
├── src/
│   ├── index.js
│   ├── services/
│   │   └── aiService.js
├── package.json
└── README.md

3. Implementing the Bot

Create src/index.js:

import { Client, GatewayIntentBits } from 'discord.js';
import 'dotenv/config';
import aiService from './services/aiService.js';

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent
  ]
});

client.on('ready', () => {
  console.log(`${client.user.tag} is ready!`);
});

client.on('messageCreate', async message => {
  if (message.author.bot) return;
  
  if (message.content === '!ping') {
    message.reply('Pong!');
  }
  
  if (message.content.startsWith('!ask ')) {
    const question = message.content.slice(5).trim();
    if (!question) {
      message.reply('Please enter your question after !ask. For example: !ask what is Sealos?');
      return;
    }
    
    try {
      message.channel.sendTyping();
      const response = await aiService.getChatGPTResponse(question);
      message.reply(response);
    } catch (error) {
      console.error('Error getting AI response:', error);
      message.reply('Sorry, I cannot answer right now. Please try again later.');
    }
  }
});

client.login(process.env.DISCORD_TOKEN);

AI Service Integration

Create src/services/aiService.js:

import axios from 'axios';
 
class AiService {
  constructor() {
    this.openaiAxios = axios.create({
      baseURL: process.env.FASTGPT_BASE_URL,
      headers: {
        'Authorization': `Bearer ${process.env.FASTGPT_API_KEY}`,
        'Content-Type': 'application/json'
      }
    });
  }
 
  async getChatGPTResponse(message) {
    try {
      const response = await this.openaiAxios.post('/v1/chat/completions', {
        chatId: "session_" + Date.now(),
        stream: false,
        detail: false,
        messages: [{
          role: "user",
          content: message
        }]
      });
      return response.data.choices[0].message.content.trim();
    } catch (error) {
      console.error('AI API call failed:', error);
      return 'Sorry, I cannot answer right now. Please try again later.';
    }
  }
}
 
export default new AiService();

Configuration Setup

Create .env file in the project root with your credentials:

DISCORD_TOKEN=your_discord_bot_token
FASTGPT_API_KEY=your_fastgpt_api_key
FASTGPT_BASE_URL=your_fastgpt_base_url

Update src/index.js to include dotenv configuration:

import 'dotenv/config';
import { Client, GatewayIntentBits } from 'discord.js';
// ... rest of the existing code ...

Start the bot with:

npm start

4. FastGPT Integration

FastGPT is an open-source LLM application development platform that allows you to build AI applications with knowledge base capabilities. In this section, we'll walk through the process of setting up FastGPT to power our Discord bot with custom knowledge.

1. Log into your FastGPT account at FastGPT
2. Navigate to the "Datasets" section and click "Create Dataset"
3. Choose "General Dataset" as the dataset type
4. Select "Text Dataset" for document processing
5. Upload your documentation files (supports PDF, TXT, Word, etc.)
6. Configure chunking settings if needed (default settings work well for most cases)
7. Wait for the training process to complete - this may take several minutes depending on the size of your documentation

Application Setup

1. Go to the "Applications" section and create a new FastGPT application
2. In the Flow Editor, add a "Dataset Search" module
3. Connect your trained dataset to the search module
4. Add an "AI Chat" module and connect it to the search module
5. Configure the AI Chat module settings:
   • Set temperature (0.7 recommended for balanced responses)
   • Adjust max tokens as needed
   • Customize the system prompt

API Publication

1. Once satisfied with the configuration, click "Publish Channel" to make your application live
2. Go to the "API Request" section of your application
3. Generate new API credentials if you haven't already
4. Save these important details for the next steps:
   • API Base URL: The endpoint for your FastGPT API
   • API Key: Your authentication token

These credentials will be used in the .env file we created earlier to connect our Discord bot to the FastGPT backend.

file: ./content/docs/guides/ai-proxy.en.mdx meta: { "title": "AI Proxy", "description": "Take the shortest safe path to your first AI Proxy API call on Sealos with one OpenAI-compatible request, one endpoint, and one API key.", "keywords": [ "AI Proxy", "Sealos", "first API call", "OpenAI-compatible", "endpoint", "API key" ] }

This is the start-here guide for AI Proxy on Sealos.

Follow this page when you want the shortest safe path to one first OpenAI-compatible request.

By the end of this page, you will collect the minimum credentials, run one first API call, and know where to confirm that the request reached Sealos.

What AI Proxy is

AI Proxy is the Sealos entry point for making OpenAI-compatible AI requests through one managed endpoint.

Why use AI Proxy

For a first call, AI Proxy gives you one place to get credentials, one request shape to start with, and one place to confirm that the request reached Sealos.

Before You Begin

Use this page if all of the following are true:

• You can sign in to Sealos.
• You can open the AI Proxy product surface in the Sealos console.
• You are ready to copy an endpoint and API key into shell environment variables.
• You will use the fixed cURL example in this page for the first request.

The goal is first success, not full AI Proxy coverage.

Get your endpoint and API key

Collect the two values needed for the first request.

1. Sign in to Sealos and open the AI Proxy surface.
2. Use the current console action to create or reveal an API key.
3. Copy the endpoint shown in AI Proxy.
4. Copy the API key value and keep both values ready for the shell example below.

The next section places those values into shell environment variables.

Make your first API call

Export the three placeholder variables first and run the request second.

export AI_PROXY_BASE_URL="replace-with-the-endpoint-shown-in-ai-proxy"
export AI_PROXY_API_KEY="replace-with-your-api-key-value"
export AI_PROXY_MODEL="replace-with-a-model-available-in-your-workspace"

curl "$AI_PROXY_BASE_URL/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AI_PROXY_API_KEY" \
  -d '{
    "model": "'"$AI_PROXY_MODEL"'",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Reply with one short sentence about Sealos."}
    ],
    "temperature": 0
  }'

Replace the three placeholders with the values you copied from Sealos.

A successful response should return generated text in the response body.

The next section explains only the three fields used in this request.

Understand the request fields

These are the only fields you need to understand for the first call:

• model selects the AI model the request should use. This page keeps the starter model neutral until later verification.
• messages carries the conversation input for the request. The first request keeps it minimal so the response is easy to recognize.
• temperature controls response randomness. This first request keeps it low and simple for a predictable first success.

Check logs and usage

Check these in order after the first call:

• Confirm the request returned successfully and the response contains recognizable generated text.
• Find the same request record in AI Proxy logs. This is the primary Sealos-side signal.
• Use usage or billing visibility as supporting confirmation only.

The next section covers only the first set of failure checks.

If the first call fails

Check these first:

• wrong endpoint root or wrong path Look here first: keep the AI Proxy endpoint unchanged and confirm the request still targets /v1/chat/completions.
• wrong API key Look here first: re-copy the current key and confirm the request still sends Authorization: Bearer $AI_PROXY_API_KEY.
• unsupported or unavailable model Look here first: replace the placeholder with a model that is available in your workspace.
• no log record Look here first: if the request does not appear in AI Proxy logs, it may not have reached AI Proxy at all.
• missing balance or usage visibility Look here first: if the request reaches AI Proxy but does not complete, confirm the workspace still has usable balance or visible usage data.

What this page does not cover

This page does not cover a model catalog, deep billing or deep logs guidance, or advanced proxy features such as caching, routing, quotas, or failover.

It is the shortest path to a first successful call.

file: ./content/docs/guides/object-storage.en.mdx meta: { "title": "Object Storage", "description": "S3-compatible object storage on Sealos -- create a bucket and upload your first file through the console.", "keywords": [ "object storage", "S3", "bucket", "file upload", "credentials", "Sealos" ] }

This is the start-here guide for Object Storage on Sealos.

On this page, you create a bucket, retrieve its credentials, upload your first file, and confirm the upload succeeded -- all through the Sealos console.

By the end, you have a working bucket with one file stored in it and the four credential values you need for any future programmatic access.

What Object Storage Is

Object Storage is the Sealos service for storing and managing unstructured data such as files, images, documents, and backups. It is S3-compatible and built on MinIO, and Sealos manages the underlying infrastructure so you work with buckets and files instead of servers.

At a high level, you use Object Storage to upload files into buckets, download them when you need them, and control who can read or write each bucket through access permissions. Every bucket also exposes endpoints and credentials that work with MinIO-compatible SDKs when you are ready to integrate it into an application.

Create a Bucket

In this section, you create your first bucket and set its access permission. The bucket is the container that holds your files, and its permission level controls who can read or write its contents.

Sign in to the Sealos console and open the Object Storage app from the application launcher. The app lists any buckets you have already created and provides the entry point for creating a new one.

Use the bucket creation action in the app, enter a name for your bucket, and choose private as the access permission. Apply the change to create the bucket. The new bucket then appears in your bucket list.

• private: only authenticated users can access bucket contents. Recommended for the first bucket and any bucket containing sensitive data.
• publicRead: anyone can read objects without authentication; write operations still require credentials. Suitable for content delivery and static website hosting.
• publicReadWrite: fully open read and write access. Use with caution; production environments should avoid this level.

Get Your Credentials

In this section, you retrieve the four values needed to access the bucket programmatically. The first upload in this guide uses the console, so you do not paste these values anywhere right now, but having them on hand prepares you for any future SDK or API access.

Select your bucket in the bucket list and use the access key action to open the credential display. A popup shows four values tied to this bucket: the Access Key, the Secret Key, the Internal endpoint, and the External endpoint. Read the values directly from the popup when you need them.

• Internal endpoint: for services running inside Sealos. Traffic stays on the internal network, which gives lower latency and avoids external traffic charges.
• External endpoint: for access from outside the Sealos environment, such as a local development machine or a service hosted elsewhere.

Upload Your First File

In this section, you upload a test file into the bucket you just created. The entire flow happens inside the Sealos console, so you do not need any command line tools or SDK setup yet.

In the Object Storage app, select the bucket you created earlier from the bucket list. The bucket view opens at its root directory, which is where your first file will land.

Use the upload action in the bucket toolbar to open your operating system's file picker. Pick a small test file for your first upload -- a plain text file or a small image under 1 MB works well and keeps the transfer fast. Confirm the selection in the picker to start the upload.

Wait for the upload progress to finish. When it completes, the new file appears in the bucket's file list at the current directory.

Verify Your Upload

First success for this guide is defined by two signals inside the console. Check them in order.

• File row in the bucket's file list Open the bucket you just uploaded into and confirm a row for your file shows the expected file name, its size, and the upload timestamp.
• Object detail view showing an addressable object path Open the file's detail view from that row and confirm the view shows the object's path or URL. This proves the object exists at an addressable location. The bucket is private, so the URL itself is access-controlled; this guide does not ask you to make the bucket public or generate a signed URL.

If both signals are present, the first upload is confirmed.

If the first upload fails

Check these first, in order:

• wrong or missing bucket Look here first: confirm the bucket exists in your current workspace and region, and that you opened the bucket you actually uploaded into.
• permission denied Look here first: confirm the bucket's permission level is not blocking your session, and that the upload action is available in the current context.
• wrong endpoint Matters when you move to SDK or CLI access: the Internal and External endpoints are separate values; pick the one that matches where your client runs.
• wrong credentials Matters when you move to SDK or CLI access: re-read the Access Key and Secret Key from the credential popup and confirm the pair was copied exactly.
• upload size or file-name issue Look here first: use a small test file and avoid file names with characters the bucket rejects.

What's Next

You now have a working bucket with your first file stored in it and the four credential values ready for any future programmatic access.

Object Storage supports more than the console upload flow. Beyond this guide, you can use MinIO-compatible SDKs to read and write objects from your applications, enable static website hosting for buckets with public read access, and watch resource usage through the built-in monitoring views. These are capabilities to explore once you are comfortable with the console basics, not walkthroughs you need to follow right now.

file: ./content/docs/k8s/QA.en.mdx meta: { "title": "常见问题", "keywords": [ "Sealos", "镜像构建", "Kubernetes运行时", "版本兼容性", "文件目录位置" ], "description": "了解Sealos常见问题及解决方案，包括镜像构建、Kubernetes运行时选择、版本兼容性和文件目录位置调整。" }

file: ./content/docs/k8s/lifecycle-management.en.mdx meta: { "title": "K8s 集群生命周期管理", "keywords": [ "Kubernetes集群", "Sealos工具", "集群生命周期管理", "分布式应用", "Kubernetes安装" ], "description": "使用Sealos工具轻松管理Kubernetes集群生命周期，支持分布式应用和自定义集群镜像，提供高可用性和离线安装功能。" }

file: ./content/docs/msa/privacy-policy.en.mdx meta: { "title": "Privacy Policy" }

Effective Date: May 9, 2026

1. Introduction and Data Controller

Labring Inc. ("we," "our," or "us"), a Delaware corporation, is the data controller for the information collected through Sealos Cloud services and related websites (collectively, "Services"). We are committed to protecting your privacy and ensuring a transparent processing of your personal data.

2. Information We Collect

• Personal Information: Name, email address, phone number, account credentials, and billing/payment information.
• Technical Information: IP addresses, browser type, device identifiers, log data, and performance metrics.
• Usage Data: How you interact with our Services and your configuration preferences.

3. How We Use Your Information

We process your information to:

1. Provide, maintain, and secure our Services.
2. Process payments and prevent fraud.
3. Provide technical support and critical service communications.
4. Comply with legal obligations and enforce our Terms of Service.

4. International Data Transfers

Labring Inc. is headquartered in the United States. Data collected may be transferred to and processed in the U.S. or other countries where our service providers maintain facilities.

Data Transfer Mechanisms:

• Standard Contractual Clauses (SCCs): For transfers of data from the EEA, UK, or Switzerland, we utilize European Commission-approved SCCs to ensure an adequate level of protection.
• Data Privacy Framework: We comply with the EU-U.S. Data Privacy Framework (EU-U.S. DPF), the UK Extension to the EU-U.S. DPF, and the Swiss-U.S. Data Privacy Framework (Swiss-U.S. DPF) as set forth by the U.S. Department of Commerce.

5. Data Security

We implement industry-standard security measures, including:

• AES-256 encryption for data at rest and TLS for data in transit.
• Strict Role-Based Access Control (RBAC).
• Regular security audits and vulnerability assessments.

6. Your Privacy Rights

Depending on your location (e.g., GDPR in the EU or CCPA in California), you may have the right to:

• Access, correct, or delete your personal data.
• Object to or restrict the processing of your data.
• Data portability.
• Withdraw consent at any time.

To exercise these rights, please contact privacy@sealos.io.

7. Children's Privacy

Our Services are intended for professional use and are not directed to children under 16. We do not knowingly collect information from children.

8. Contact Information

For privacy-related inquiries or to reach our Data Protection Officer:

• Email: privacy@sealos.io
• Data Protection Officer: dpo@sealos.io
• Urgent Security Matters: fanux@sealos.io

file: ./content/docs/msa/terms-of-service.en.mdx meta: { "title": "Terms of Service" }

Last Updated: May 15, 2026

These Sealos Cloud Terms of Service (this "Agreement") are entered into by and between you (the "User" or "Customer") and Labring Inc. (referred to as "the Company," "we," or "us") regarding the use of our cloud services (the "Service").

PLEASE READ THIS AGREEMENT CAREFULLY. By using the Service, you agree to be bound by these terms.

Article 1: Scope of Services

1. Labring Inc. provides cloud computing services including compute resources, storage, network services, and container orchestration via the Sealos platform.
2. We reserve the right to modify or enhance the Service. Material changes will be communicated via the website or email.

Article 2: Service Level Agreement (SLA)

1. We strive for a Monthly Uptime Percentage of 99.9%.
2. Service credits may be issued for verified outages as defined in our full SLA documentation.
3. Scheduled maintenance is not counted toward downtime.

Article 3: Account Management

1. You must provide accurate information during registration and are responsible for maintaining the confidentiality of your credentials.
2. Labring Inc. is not liable for any loss resulting from unauthorized access to your account due to your failure to secure your credentials.

Article 4: Acceptable Use Policy

By using the Service, you agree to comply with this Acceptable Use Policy. You shall not use, or encourage, promote, facilitate, or instruct others to use the Service for any illegal, harmful, or offensive use.

You agree not to use the Service for:

• Illegal Activities & Fraud: Any illegal acts, fraudulent schemes, phishing, or the distribution of prohibited, deceptive, or malicious content.
• Copyright & Intellectual Property: Hosting, sharing, or distributing material that violates the intellectual property or copyrights of others. We maintain a zero-tolerance policy for copyright infringement.
• Gambling: Operating, promoting, or facilitating unauthorized online gambling, lotteries, betting pools, or any platform related to unlicensed wagering.
• Adult Content: Hosting, distributing, or transmitting pornography, sexually explicit material, or any adult-oriented content.
• Cryptocurrency Mining: Any form of cryptocurrency mining, blockchain validation, or related resource-intensive digital asset generation. This is strictly prohibited; there are no exceptions.
• Unlicensed Regulated Activities: Engaging in any activity that requires a government or regulatory license (including financial services, medical advice, or legal services) without possessing and maintaining all valid, necessary licenses.
• Infrastructure Abuse: Distributing malware, executing denial-of-service (DoS) attacks, or attempting to disrupt, probe, scan, or "stress test" our infrastructure without prior, express written authorization from us.
• Resource Abuse: Any activity that imposes an automated, disproportionate, or abusive load on our infrastructure or interferes with the performance of the Service for other users.

Enforcement: We reserve the right, at our sole discretion, to determine what constitutes a violation of this Policy. We may take immediate action—including the suspension or permanent termination of your account and the deletion of data—without prior notice or liability if we believe you have breached any of these terms.

Article 5: Data Ownership and Privacy

1. Your Data: You retain all rights, title, and interest in the data you upload to the Service.
2. Our Privacy Policy: We process data as described in the Labring Inc. Privacy Policy, which is incorporated here by reference.

Article 6: Fees and Payment

1. Fees are based on usage and your selected tier.
2. Payments are due within thirty (30) days of the invoice date.
3. Failure to pay may lead to account suspension and, eventually, data deletion after a grace period.

Article 7: Limitation of Liability

To the maximum extent permitted by law, Labring Inc. shall not be liable for any indirect, incidental, special, or consequential damages. In no event shall our total liability exceed the amounts paid by you to Labring Inc. for the Service in the twelve (12) months prior to the event giving rise to the claim.

Article 8: Term and Termination

1. You may terminate your account at any time.
2. We may terminate or suspend your access for material breach of these terms.
3. Upon termination, you have thirty (30) days to retrieve your data before it is permanently deleted from our active systems.

Article 9: Governing Law and Jurisdiction

This Agreement shall be governed by and construed in accordance with the laws of the State of Delaware, USA, without regard to its conflict of law principles. Any legal action arising out of this Agreement shall be brought exclusively in the courts located in Delaware.

Article 10: Contact

For legal notices or questions regarding these terms, please contact:

• Legal Department: legal@sealos.io

file: ./content/docs/overview/intro.en.mdx meta: { "title": "What is Sealos?", "icon": "Info", "keywords": [ "Sealos", "cloud platform", "Kubernetes", "cloud development environment", "DevBox", "managed databases", "app store", "multi-tenancy", "AI deployment", "container platform" ], "description": "Sealos is a cloud platform that unifies the entire application lifecycle—from development in cloud development environments to production deployment—powered by Kubernetes, without the complexity." }

Sealos is an AI-native cloud development platform designed to unify the entire application lifecycle, starting with cloud development environments and one-click deployments, extending to managed databases and full Kubernetes power—all without the complexity.

Everything You Need to Build and Scale

Unify the entire application lifecycle, from development in cloud development environments to production deployment and management.

AI-Native Infrastructure

Build and scale modern AI applications simply by describing them.

Cloud Development Environments

Zero-setup, collaborative development in the cloud. Eliminate local environment inconsistencies with DevBox.

• Connect with your favorite IDE (VS Code, JetBrains, Cursor)
• Pre-configured runtime environments for any language
• Instant collaboration with teammates

Extensive App Store

Deploy complex applications with a single click. No YAML configuration, no container orchestration complexity—just point, click, and deploy.

• 100+ pre-built templates
• One-click deployment for popular applications
• Community-contributed app catalog

Managed Databases & Storage

Production-ready databases and storage, fully managed with automated backups and high availability.

• Databases: PostgreSQL, MySQL, MongoDB, Redis
• Object Storage: S3-compatible, built-in
• High availability and automated backups

Full Kubernetes Power

Access the full power of Kubernetes without the complexity. K8s-native from day one.

• Raw Kubernetes access when you need it
• Automatic container orchestration
• Native integration with cloud-native ecosystem

Enterprise Multi-Tenancy

Workspace-based isolation with granular permissions for secure collaboration.

• Workspace-based resource isolation
• Granular RBAC controls
• Per-workspace resource quotas

---

Getting Started

Ready to ship your first app?

file: ./content/docs/self-hosting/faq.en.mdx meta: { "title": "常见问题", "keywords": [ "Sealos Cloud", "常见问题", "部署问题", "证书更新", "域名更换", "用户注册", "集群管理", "Kubernetes" ], "description": "探索Sealos Cloud部署和使用中的常见问题解决方案，包括系统配置、证书更新、域名更换等关键操作指南，助您轻松管理Kubernetes集群。" }

file: ./content/docs/self-hosting/install-v1.en.mdx meta: { "title": "Sealos 集群部署 - 旧版", "description": "了解如何使用 Sealos 一键部署 Kubernetes 集群，支持多种安装方式，确保通信安全，适用于大规模集群和企业生产环境。" }

file: ./content/docs/self-hosting/install.en.mdx meta: { "title": "Sealos 集群部署", "description": "了解如何使用 Sealos 一键部署 Kubernetes 集群，支持多种安装方式，确保通信安全，适用于大规模集群和企业生产环境。" }

file: ./content/docs/system-design/billing-system.en.mdx meta: { "title": "计费系统", "keywords": [ "Sealos 计费系统", "云成本管理方案", "Kubernetes 资源计费", "容器计费架构", "云原生计费设计", "实时资源计量", "自动费用计算", "精准账单系统", "跨集群成本优化", "FinOps 实践", "云资源计价模型", "分布式计费方案" ], "description": "深度剖析 Sealos 云操作系统的计费系统架构设计，详解基于 CRD 的实时资源计量模型、多维度费用计算算法及分布式账单生成机制，涵盖CPU/内存/存储/网络等全资源类型的精准计价策略，提供 Kubernetes 集群成本优化最佳实践与 FinOps 落地指南。" }

file: ./content/docs/system-design/devbox-architecture.en.mdx meta: { "title": "Architecture" }

Sealos Devbox is an advanced development environment solution that leverages cloud-native Container and Kubernetes technologies to offer a unified and flexible development Runtime. Its key feature is simulating a traditional virtual machine experience while maintaining containerization benefits.

Architecture

Sealos Devbox is built on a layered architecture, comprising these key components:

Control Flow

Devbox implements a decoupled front-end and back-end design:

1. Users trigger actions via the web interface or plugins
2. Devbox Controller receives and processes these requests
3. Controller translates the processed instructions into Kubernetes API calls
4. Kubernetes executes the corresponding Container operations

State Persistence Mechanism

Devbox employs an intelligent state preservation system to maintain user environment consistency:

Automatic Saving

• System auto-saves user environment changes under specific conditions
• Changes are packaged as image layers
• New layers are appended to the base image as commits
• Updated images are securely stored in an isolated internal registry

Environment Recovery

• On subsequent startups, system boots from the most recent image
• Ensures full preservation of historical changes

Optimization

The Container-shim layer provides automated maintenance:

• Regularly merges image layers to optimize storage
• Automatically cleans up redundant data
• Optimizes image size and layer count for optimal system performance

file: ./content/docs/system-design/monitor-system.en.mdx meta: { "title": "监控告警系统", "keywords": [ "Sealos 监控系统", "云原生告警体系", "Kubernetes 监控方案", "容器集群监控", "VictoriaMetrics 实战", "Loki 日志管理", "Grafana 可视化", "PrometheusAlert 集成", "实时指标监控", "日志聚合系统", "多平台告警推送", "运维自动化", "分布式系统监控", "可观测性最佳实践" ], "description": "深度解析 Sealos 云原生监控告警系统架构设计，详解基于 VictoriaMetrics 的实时指标采集方案与 Loki 日志管理系统的集成实践，涵盖多可用区高可用部署、Grafana 可视化配置、飞书/微信多平台告警推送等核心功能，提供云原生环境下的全栈监控与日志分析最佳实践。" }

file: ./content/docs/system-design/system-application.en.mdx meta: { "title": "系统应用", "keywords": [ "Sealos系统应用架构", "云原生桌面系统设计", "Kubernetes CRD 应用管理", "分布式费用中心实现", "定时任务调度系统", "KubeBlocks 数据库集成", "多租户对象存储方案", "云原生应用开发平台", "微服务模块化设计", "系统组件交互协议", "容器化应用生命周期管理", "可观测性系统集成" ], "description": "主要介绍 Sealos 当前各个系统应用的基本原理与实现。" }

file: ./content/docs/system-design/system-architecture.en.mdx meta: { "title": "系统架构", "description": "深度解析 Sealos 云操作系统的分层架构设计与核心组件实现。" }

file: ./content/docs/system-design/user-system.en.mdx meta: { "title": "用户系统", "description": "深度解析 Sealos 云操作系统的分层架构设计与核心组件实现。" }

file: ./content/docs/guides/app-deploy/add-a-domain.en.mdx meta: { "title": "Domains and Public Access", "keywords": [ "custom domain", "public access", "CNAME", "Sealos", "App Launchpad" ], "description": "Make an existing Sealos app reachable on the public internet and attach a custom domain when you need one." }

When to use this

Use this page after your app already exists and you need a stable public address.

You might only need the Sealos-generated public URL, or you might need to attach your own domain after DNS is ready. This is the right page for both jobs.

Before you change this

If your app is deployed in mainland China, make sure the custom domain can legally resolve in that region before you switch traffic to it.

If your domain requires filing or provider-specific ICP compliance, complete that first. You also need control of your DNS provider so you can create a CNAME record that points to the Sealos-generated address.

Add Public Access during deploy or redeploy

1. Open the app create or change form in the App Launchpad UI.
2. Find the network section and enable Public Access.
3. Record the public address that Sealos generates for the app.
4. Finish the deploy or redeploy so the public endpoint becomes active.

If the app is already deployed, you can reopen the same settings from the app details page and enable Public Access there before saving the change.

Attach a custom domain

1. Open your app details page and confirm the Sealos-generated public address is already available.
2. At your DNS provider, create a CNAME record that points your domain or subdomain to the Sealos-generated address.
3. Wait for DNS propagation before you continue.
4. Back in Sealos, open the Custom Domain action from the app details page.
5. Enter the domain you want to bind, then confirm and redeploy if Sealos asks you to apply the change.

If you are switching an existing production domain, keep TTL and rollback steps in mind before you update the DNS record.

Verify

Use this checklist before you treat the change as complete:

• The app still shows a healthy running state after the change.
• The Sealos-generated public URL still opens the app.
• The custom domain resolves to the expected CNAME target.
• Opening the custom domain loads the same app content you expected to publish.

If this fails, see Custom Domain and TLS Issues.

Related Tasks

• Update and Redeploy if you need to reopen the app settings later for additional changes.
• Ports and Networking if the app needs more than one externally reachable endpoint.

file: ./content/docs/guides/app-deploy/app-does-not-reach-running.en.mdx meta: { "title": "App Does Not Reach Running", "keywords": [ "app not running", "startup failure", "image pull failure", "App Deploy", "Sealos" ], "description": "Recover when an App Deploy workload never reaches running because of image, startup, or configuration problems." }

When to use this

Use this page when Sealos creates the app, but the instance never reaches running.

This usually means the app failed before it could start normally. Common causes are a wrong image, a bad startup command, or optional settings that broke the container.

Check the failure surface

1. Open the app details page in App Deploy.
2. Check the instance status first so you know whether the app is still waiting or already failed.
3. Open the instance details view to inspect the startup failure surface.
4. Open the instance logs to see whether the container pulled, started, and exited with an error.

If the image name is wrong or unavailable, the failure usually appears before the app starts.

If the container starts and then exits, the logs usually point to the broken command or missing runtime configuration.

What to fix

Work through these checks in order:

1. Re-check the image name and tag you entered.
2. Remove or correct the startup command if you added one.
3. Re-check any environment variables, config files, storage mounts, or extra ports you added beyond the basic happy path.
4. If you changed several settings at once, roll back to the last known working combination before you try again.

For a first deploy, the lowest-friction baseline is still a public nginx:latest container on port 80 with no startup command and no optional configuration.

Verify

Treat the issue as resolved only when all of the following are true:

• The instance state changes to running.
• The details view no longer shows the previous startup failure.
• The logs stop showing the earlier fatal startup error.
• If the app should be public, you can continue to the next reachability check.

Related Tasks

• Public URL Does Not Open if the app reaches running but still is not reachable.
• Update and Redeploy if you need to reopen the settings and correct a broken deploy.

file: ./content/docs/guides/app-deploy/autoscaling.en.mdx meta: { "title": "Scaling", "keywords": [ "scaling", "autoscaling", "HPA", "CPU", "memory", "Sealos" ], "description": "Configure scaling rules for a Sealos app so instance count can grow or shrink with load." }

When to use this

Use this page when the app already works with one instance but traffic or workload may change over time.

Scaling is a better fit for stateless or horizontally safe services than for apps that assume only one writer or one local filesystem.

Before you change this

Scaling changes both capacity and cost.

Before you enable autoscaling, confirm the app can safely run on more than one instance and that shared state is stored outside the container if needed.

Configure scaling

1. Open the app details page and reopen the settings with the Update or Change action.
2. Find the scaling section in the App Launchpad UI.
3. Set the minimum instance count (min) and maximum instance count (max).
4. Set the target CPU or memory threshold that should trigger scale decisions.
5. Save the change and redeploy the app.

How Sealos reads usage

Sealos makes autoscaling decisions from average usage across running instances.

• If two instances use 60% CPU and 40% CPU, the average CPU value is 50%.
• The same idea applies to memory thresholds.
• If the average rises above the target, Sealos can add instances up to the configured max.
• If the average stays below the target, Sealos can reduce instances down to the configured min.

Verify

Check the result after the change:

• The app returns to running.
• The saved scaling policy still shows the expected min and max range.
• The configured CPU or memory target is visible after you reopen the form.
• Under load, the app can increase instance count instead of staying fixed at one instance.

If you are not testing with real traffic yet, at least verify that the policy persists correctly and does not conflict with the app's current resource settings.

Related Tasks

• Update and Redeploy if you need to adjust image or resources together with scaling.
• Persistent Storage if the app still writes important data inside the container and is not ready for multi-instance behavior.

file: ./content/docs/guides/app-deploy/configmap.en.mdx meta: { "title": "Config Files", "keywords": [ "config files", "ConfigMap", "Sealos", "file-based configuration" ], "description": "Mount a configuration file into your Sealos app when environment variables are not enough." }

When to use this

Use this page when your app expects a real file such as nginx.conf, a YAML config, a JSON settings file, or another structured config artifact inside the container.

Choose this approach when environment variables are too small or too awkward for the setting you need to change. In Sealos, this is usually implemented with a ConfigMap-backed file mount.

Before you change this

Mount the exact target file path, not just a folder.

Sealos mounts a single file into the container. If you enter only a directory path, or if you choose the wrong file path, the app may start with the wrong config or fail to boot.

Add a config file

1. Check the image documentation so you know the exact file path the app expects inside the container.
2. Prepare the file content locally first if the config is large or easy to break.
3. Open the app details page and choose the action that reopens the app settings.
4. Find the config file section in the App Launchpad UI.
5. Enter the full in-container file path and paste the file contents.
6. Save the change and redeploy the app.

For example, an Nginx container usually expects a file path such as /etc/nginx/nginx.conf. That is a single file path, not a directory.

Verify

Confirm the config change after redeploy:

• The app reaches running.
• The new behavior matches the file you mounted.
• If the app exposes logs, the logs do not show a syntax or startup error caused by the new file.

If the app fails immediately after redeploy, compare the mounted file path and the pasted contents with the image documentation before you retry.

Related Tasks

• Environment Variables if the setting can be expressed more safely as key-value pairs.
• Update and Redeploy if you are changing config files together with the image or resources.

file: ./content/docs/guides/app-deploy/create-app.en.mdx meta: { "title": "Create App", "keywords": [ "create app", "App Deploy", "legacy route", "Sealos" ], "description": "Legacy handoff page for older App Deploy links. Use the canonical first-deploy guide instead." }

This page is kept only for older App Deploy links.

The canonical onboarding guide is now Deploy Your First App.

Start here instead

If you want the current zero-to-one path, open Deploy Your First App and follow that walkthrough instead of using this legacy route.

file: ./content/docs/guides/app-deploy/custom-certificates.en.mdx meta: { "title": "Custom Domain and TLS Issues", "keywords": [ "custom domain certificate", "TLS issue", "cert-manager", "ingress patch", "App Deploy" ], "description": "Recover when a custom App Deploy domain is configured but the certificate is missing, invalid, or still not secure." }

When to use this

Use this page when the Sealos-generated public endpoint works, but the custom domain still fails TLS checks or shows an insecure certificate state.

This recovery path is only for domain and certificate issues after the app is already reachable enough to continue.

Confirm the basic prerequisites

Before you change the certificate flow, confirm all of the following:

• The app already has a working public endpoint in App Deploy.
• You already configured the custom domain in Sealos.
• Your DNS provider already points the domain or subdomain to the Sealos endpoint with the correct CNAME record.
• You already have the certificate and private key files if you need to apply your own TLS secret.

If the generated public endpoint does not work yet, return to Domains and Public Access and confirm the base routing first.

If Sealos did not issue a certificate

If the custom domain is configured but the certificate is still missing or insecure, the most common problem is that cert-manager did not issue the certificate successfully.

Re-check the domain value, the current CNAME target, and whether DNS propagation has actually finished before you apply manual certificate steps.

If those checks are already correct and you still need a manual recovery path, continue with your own TLS secret.

Apply your own TLS secret

Open the terminal from the App Launchpad UI, then run the TLS secret steps with your own certificate data.

# Create tls.crt using the certificate file information (replace xxxx with the actual certificate file information).
cat > tls.crt <<EOF
-----BEGIN CERTIFICATE-----
xxxx
-----END CERTIFICATE-----
EOF

# Create tls.key using the certificate private key information (replace xxxx with the actual private key information).
cat > tls.key <<EOF
-----BEGIN RSA PRIVATE KEY-----
xxxx
-----END RSA PRIVATE KEY-----
EOF

# Create a secret using tls.crt and tls.key.
kubectl create secret tls network-test --cert tls.crt --key tls.key

# Check the ingress for the corresponding application.
kubectl get ingress

Then patch the ingress so the custom domain points to that TLS secret. Replace xzy-dev.sealos.run with your own domain and replace the ingress name with the one that belongs to your app.

kubectl patch ingress network-twvuqmjzckur -p '{"spec":{"tls":[{"hosts":["xzy-dev.sealos.run"],"secretName":"network-test"}]}}'

Verify

Treat the issue as resolved only when all of the following are true:

• The app still stays running.
• Opening the Sealos-generated public endpoint still works.
• Opening the custom domain now loads the expected app content.
• The browser no longer reports the old insecure certificate state.

Related Tasks

• Domains and Public Access if you still need to re-check the domain binding or CNAME target.
• Public URL Does Not Open if the base public endpoint is still broken before the custom domain layer.

file: ./content/docs/guides/app-deploy/docker-compose-migration.en.mdx meta: { "title": "Migrate from Docker Compose", "keywords": [ "Docker Compose", "migration", "Sealos", "WordPress", "environment variables", "persistent storage" ], "description": "Move an existing Docker Compose workload to Sealos by translating services, ports, storage, and environment variables into App Deploy and related Sealos products." }

When to use this

Use this page when you already have a working Docker Compose setup and want to move that workload into Sealos.

This is not the default first deploy path. If you are starting from scratch, use First Deploy instead. If you are already running the app on Sealos and only need one follow-up change, use the manage task pages instead of a full migration flow.

Check for a ready-made template first

Before you do a manual migration, check whether Sealos App Store already has a maintained template for the workload you want to run.

If a tested template exists, start there. Manual migration is most useful when you have a custom app or when no template matches the services in your docker-compose.yml.

Translate Compose concepts into Sealos

Use this table to map the main Docker Compose concepts into Sealos building blocks:

Docker Compose	Sealos target
services	Separate app deployments or managed services
ports	App Deploy network configuration
volumes	Persistent Storage
environment	Environment Variables
depends_on	Deployment order and dependency planning
image	Container image field in App Deploy
command	Startup command or runtime command field

Most migrations become easier if you split stateful services and app services instead of trying to force the entire stack into one first deploy.

Plan the migration

1. Read the existing docker-compose.yml and list every service, image, port, volume, environment variable, and startup command.
2. Decide which services should stay together in App Deploy and which should become a dedicated Sealos product such as a managed database.
3. Identify every persistent path before you redeploy anything.
4. Move external dependencies first so the application can connect to them when the app service starts.

Example: WordPress migration

A typical WordPress stack in Docker Compose has one app service and one database service.

In Sealos, a practical migration path is:

1. Create the database first by using the Sealos database product that matches the Compose stack.
2. Record the database host, username, password, and database name.
3. Deploy the wordpress:latest app in App Deploy.
4. Expose port 80 publicly so you can reach the site.
5. Attach persistent storage to /var/www/html so uploads and content survive a redeploy.
6. Add the WordPress database settings as environment variables before the first app start.

That keeps the migration clear: stateful data is handled separately, while the web app moves into the App Deploy workflow.

Verify

Use this checklist before you call the migration complete:

• Every Docker Compose service has a clear Sealos target.
• Persistent data paths were moved to persistent storage where needed.
• The migrated app returns to running.
• The public endpoint opens the migrated workload successfully.
• The app can still reach the services it depended on before the migration.

If the migrated app does not reach running, see App Does Not Reach Running.

If the public endpoint does not open, see Public URL Does Not Open.

Related Tasks

• Persistent Storage if the original Compose stack used volumes.
• Environment Variables if the migrated app still needs runtime settings.
• Update and Redeploy if you need to adjust the migrated app after the first successful move.

file: ./content/docs/guides/app-deploy/environments.en.mdx meta: { "title": "Environment Variables", "keywords": [ "environment variables", "Sealos", "App Launchpad", "runtime settings" ], "description": "Configure runtime settings for a Sealos app with environment variables instead of rebuilding the image." }

When to use this

Use this page when your image is correct but the app still needs runtime settings such as ports, hosts, credentials, feature flags, or service endpoints.

Environment variables are the fastest way to change small pieces of configuration without rebuilding the image. If your app needs a full config file instead of key-value pairs, use Config Files instead.

Update environment variables

1. Open the app details page for the running app.
2. Click the action that reopens the app settings. Depending on the current UI, this may be labeled Update or Change.
3. Find the environment variable input area.
4. Paste one variable per line, then review the values before you save.
5. Redeploy the app so the new environment variables are applied to the next running instance.

Supported input format

Sealos accepts bulk input, so you can paste several variables at once.

These formats are interpreted correctly:

host=127.0.0.1
port:3000
name: sealos
- username=123
- password:123
# Comments like this line are ignored because they do not contain = or :

This format is risky because the inline comment becomes part of the value:

host=127.0.0.1 # This entire right side is treated as the value

Use plain key-value lines only. Do not rely on inline comments after the value.

Verify

Check the result after the redeploy:

• The app returns to running.
• The changed settings still appear in the environment variable section when you reopen the form.
• The app behavior matches the new values, for example by connecting to the right host, binding the expected port, or enabling the intended feature.

If the app fails after the change, compare the pasted values with the expected application format before you try a larger rollback.

Related Tasks

• Config Files if the app needs structured file content instead of simple key-value settings.
• Update and Redeploy if you are changing the image or several runtime settings at the same time.

file: ./content/docs/guides/app-deploy/expose-multiple-ports.en.mdx meta: { "title": "Ports and Networking", "keywords": [ "multiple ports", "Add Port", "networking", "HTTP", "HTTPS", "gRPC", "Sealos" ], "description": "Add and manage more than one application port in Sealos when a single endpoint is not enough." }

When to use this

Use this page when one app needs more than one listener, for example HTTP plus HTTPS, an app port plus an admin port, or a public API plus a private metrics endpoint.

This is also the right page when you need to decide which ports stay internal and which ports should become public.

Before you change this

Every public port creates another externally reachable endpoint.

Before you expose more ports, decide which ones should remain internal and which ones really need internet access.

Add more than one port

1. Open the app details page and reopen the settings with Update or Change.
2. Go to the network section.
3. Use Add Port to create the first additional port mapping.
4. Enter the container port and decide whether that port should be public or internal only.
5. Repeat the same process for each required port.
6. Save the change and redeploy the app.

Common examples include:

• HTTP and HTTPS on separate ports
• A user-facing service plus an admin service
• A REST API plus a gRPC endpoint
• An app service plus a /metrics port that should stay private

If you expose a port publicly, Sealos assigns a separate externally reachable endpoint for that port, usually through its own sub-domain.

Verify

Check the network result after redeploy:

• The app returns to running.
• Every required port appears in the current app configuration.
• Each public port receives the expected external address or sub-domain.
• Internal-only ports are not accidentally exposed to the public internet.

If a public endpoint opens the wrong service, re-check the port mapping before you change domains or application code.

Related Tasks

• Domains and Public Access if one of the public endpoints now needs a custom domain.
• Update and Redeploy if you are changing image, env, or storage together with networking.

file: ./content/docs/guides/app-deploy/first-deploy.en.mdx meta: { "title": "Deploy Your First App", "keywords": [ "App Deploy", "App Launchpad", "Sealos", "first deploy", "nginx", "nginx:latest", "public URL" ], "description": "Deploy your first app on Sealos App Deploy with one exact walkthrough using nginx:latest, port 80, and a public URL." }

This is the start-here App Deploy tutorial for new users.

Follow this page when you want the shortest zero-to-one path to one public single-container web app on Sealos.

By the end of this guide, you will deploy nginx:latest, wait for the instance to reach running, and open its public URL in your browser.

Before You Begin

Use this tutorial if all of the following are true:

• You can sign in to the Sealos console.
• You want one public single-container web app, not a multi-service setup.
• You will use the exact demo image nginx:latest.
• You will expose container port 80 to a public URL.

For this first deploy, skip startup commands, environment variables, config files, persistent storage, scaling rules, and multiple ports.

The goal here is first success, not full configuration coverage.

What You Will Deploy

This tutorial uses one exact demo so you do not have to choose values along the way.

You will deploy a small Nginx container as a fixed one-instance app and verify that its welcome page opens from a browser.

Field	Value
App name	nginx
Image	nginx:latest
Deploy mode	Fixed instances
Instance count	1
CPU	0.1
Memory	128 MiB
Container port	80
Public access	Enabled

Step-by-Step Deployment

1. Open the Sealos console

Open Sealos Console and sign in.

Then open the App Launchpad module from the workspace.

2. Start creating the app

Click the button or action that creates a new app.

After you submit that action, wait for the app creation form to open.

3. Fill the basic app information

Set the app name to nginx.

Set the image to nginx:latest.

Use the exact image value in this guide.

Changing the image means you may need different ports, commands, or config later.

4. Choose one fixed instance

Set deployment mode to a fixed number of instances.

Set the instance count to 1.

Keep this tutorial on the simplest path.

Do not enable scaling yet.

5. Set small compute resources

Use a small resource allocation such as 0.1 CPU and 128 MiB memory.

That is enough for the Nginx demo page in this walkthrough.

6. Configure networking

Add container port 80.

Enable public access so Sealos can generate a public URL for the app.

Use port 80 exactly for this first deployment.

The verification step later assumes this port is the one exposed to the browser with public access enabled.

7. Leave optional sections empty

Do not set a startup command.

Do not add environment variables.

Do not add config files.

Do not add persistent storage.

Those fields matter for later jobs, but they are intentionally outside the happy path for this first deploy.

8. Deploy the app

Click the deploy action in the form.

After you submit the form, wait for the app detail page to open.

9. Wait for the app detail page to show a healthy instance

On the app details page, watch the instance list and status.

Wait until the instance state becomes running.

If this fails, see App Does Not Reach Running.

Verify the Deployment

Use this checklist before you call the deployment complete:

• In Sealos, the instance status is running.
• The app details page shows a public URL.
• Opening the public URL loads the Nginx welcome page in your browser.
• The welcome page is the demo page for this tutorial, so you know the container is reachable from the public internet.

If this fails, see Public URL Does Not Open.

For this walkthrough, the correct combination is container port 80 with public access enabled.

Success

Your app is running.

Your first app is deployed on Sealos App Deploy.

The instance is healthy in Sealos, and the app is reachable through its public URL.

If you ever need the shortest App Deploy start-here path again, come back to this tutorial and reuse the same exact values.

Next Steps

After your first successful deploy, move to one focused App Deploy job at a time:

• Domains and Public Access
• Environment Variables
• Config Files
• Persistent Storage
• Update and Redeploy
• Scaling
• Ports and Networking

This page is the canonical first deploy path.

After this point, use the guides above instead of reopening every deployment option at once.

file: ./content/docs/guides/app-deploy/index.en.mdx meta: { "title": "App Deploy", "keywords": [ "App Deploy", "App Launchpad", "first deploy", "Docker Compose migration", "manage app" ], "description": "Choose the right App Deploy path in Sealos: first deploy, migrate from Docker Compose, or manage an existing app." }

App Deploy is the Sealos documentation section for deploying and managing container apps.

In the product UI, you will usually see this area labeled App Launchpad. This guide uses App Deploy as the canonical docs name and only uses App Launchpad when the exact UI label matters.

Choose the path that matches your job right now.

First Deploy

Start here if you want the shortest path from zero to one running public app on Sealos.

Go to First Deploy

Other paths

Migrate from Docker Compose

Choose this path if you already have a docker-compose.yml and need to translate an existing workload into Sealos without treating it like a brand-new first deploy.

Go to Migrate from Docker Compose

Manage an existing app

Choose this path if your app already exists and you need to change one thing at a time, such as networking, storage, configuration, or scaling.

Go to common next jobs

After your first deploy

Use one focused task page at a time instead of reopening every deployment option at once:

• Domains and Public Access
• Environment Variables
• Config Files
• Persistent Storage
• Update and Redeploy
• Scaling
• Ports and Networking

If you are moving an existing workload rather than starting fresh, use Migrate from Docker Compose instead of the default first-deploy path.

If a deploy is failing, start with Troubleshooting.

file: ./content/docs/guides/app-deploy/persistent-volume.en.mdx meta: { "title": "Persistent Storage", "keywords": [ "persistent storage", "persistent volume", "data retention", "Sealos" ], "description": "Keep application data across restart and redeploy operations by attaching persistent storage to a Sealos app." }

When to use this

Use this page when your app writes data that must survive a restart, replacement, or redeploy.

Typical examples include uploaded files, databases, CMS content, and any app that stores user data inside the container filesystem.

Before you change this

You need the exact in-container data path before you attach storage.

If you mount storage to the wrong location, the app may still start, but the real data path will remain ephemeral and your data will not survive a restart or redeploy.

Attach persistent storage

1. Identify the path inside the container where the app stores durable data.
2. Open the app create form or reopen the app settings from the app details page.
3. Add a storage entry and enter the in-container mount path.
4. Set a storage size that matches the app's expected data growth.
5. Save the change and redeploy the app.

For example, a Nextcloud container usually stores durable content under /var/www/html. That is the path you would mount if you want user files and app data to survive replacement of the container.

Verify

Check the result after the redeploy:

• The app returns to running.
• The storage mount still appears in the app configuration.
• Data written before a restart remains available after the app comes back.
• Data also remains available after a redeploy that replaces the container instance.

If the data disappears after a restart or redeploy, re-check the exact mount path before you increase storage size or change other settings.

Related Tasks

• Update and Redeploy if you need to reopen the app settings to change image, resources, or other runtime options at the same time.
• Migrate from Docker Compose if you are translating existing volume mounts from a Compose stack.

file: ./content/docs/guides/app-deploy/public-url-does-not-open.en.mdx meta: { "title": "Public URL Does Not Open", "keywords": [ "public URL issue", "public access", "container port", "App Deploy", "Sealos" ], "description": "Recover when an App Deploy app is healthy in Sealos but the public URL still does not open in the browser." }

When to use this

Use this page when the app already exists, but the public endpoint still does not load.

This page is for reachability problems after deploy. Start here only after you confirm the app itself is already healthy enough to keep running.

Check the basic state first

1. Open the app details page and confirm the instance is already running.
2. Confirm that the app details page shows a generated public endpoint.
3. If the app is not running, stop here and use App Does Not Reach Running first.

What to fix

Check these inputs in order:

1. Re-check the container port you exposed in the deploy or update form.
2. Confirm Public Access is enabled for that port.
3. Make sure the generated endpoint still matches the current app configuration after the last redeploy.
4. Retry the endpoint in the browser after the app has fully settled in running.

If you exposed the wrong port or disabled Public Access, the endpoint may exist but still not serve the app correctly.

If the app uses a custom domain instead of the generated endpoint, move to the domain/TLS recovery path after you confirm the base public endpoint works.

Verify

Treat the issue as resolved only when all of the following are true:

• The instance is still running.
• The exposed container port matches the port your app actually serves.
• Public Access is enabled for the correct endpoint.
• Opening the generated public URL loads the expected app content in the browser.

Related Tasks

• Domains and Public Access if you now need to attach a custom domain after the base public endpoint works.
• Custom Domain and TLS Issues if the generated endpoint works but the custom domain is still broken.

file: ./content/docs/guides/app-deploy/troubleshoot.en.mdx meta: { "title": "Troubleshooting", "keywords": [ "App Deploy troubleshooting", "app not running", "public URL issue", "custom domain TLS", "Sealos" ], "description": "Find the right App Deploy recovery path when a deploy does not become healthy, the public URL does not open, or a custom domain has TLS issues." }

Use this page when a deploy or public endpoint failed and you need the shortest recovery path.

This is the App Deploy troubleshooting router. It helps you pick the right symptom page. It is not the normal onboarding path for a first successful deploy.

App Does Not Reach Running

Use this when the app never becomes running, keeps waiting, or fails during startup.

Go to App Does Not Reach Running

Public URL Does Not Open

Use this when the app is already deployed, but the generated public endpoint still does not load in the browser.

Go to Public URL Does Not Open

Custom Domain and TLS Issues

Use this when the Sealos-generated endpoint works but your custom domain is missing a valid certificate or still shows an insecure connection.

Go to Custom Domain and TLS Issues

file: ./content/docs/guides/app-deploy/update-apps.en.mdx meta: { "title": "Update and Redeploy", "keywords": [ "update app", "redeploy", "Change", "Update", "Sealos" ], "description": "Reopen a deployed Sealos app, change its settings, and redeploy the new version safely." }

When to use this

Use this page when the app already exists and you need to change something without creating a new deployment from scratch.

Typical updates include a new image tag, different resources, changed environment variables, extra ports, or attached storage. This is the standard day-2 path for modifying a running app.

Before you change this

If the app is stateful or already serving traffic, confirm that the new settings are safe before you redeploy.

A bad image, wrong port, or missing storage path can turn a healthy app into a broken one during the next rollout.

Update the app

1. Open the app details page for the deployed app.
2. Use the top-right action that reopens the settings. Depending on the current UI, this may be labeled Update or Change.
3. Modify only the sections you actually need to change.
4. Review image, resources, networking, environment variables, config files, and storage befo

… [truncated — open the raw llms.txt above for the full file]