diff --git a/README.md b/README.md
index b40d7eb..7aa4c65 100644
--- a/README.md
+++ b/README.md
@@ -9,13 +9,13 @@
### Installation
```bash
-npm install devbox-sdk
+npm install @labring/devbox-sdk
```
### Secure Code Execution
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
// Initialize SDK
const sdk = new DevboxSDK({
@@ -99,7 +99,7 @@ Each sandbox runs in an isolated Kubernetes Pod, ensuring:
This is a monorepo containing multiple packages:
-### devbox-sdk (Main Package)
+### @labring/devbox-sdk (Main Package)
The primary TypeScript SDK for secure sandbox execution. See [packages/sdk/README.md](./packages/sdk/README.md) for detailed documentation.
### devbox-shared
diff --git a/apps/docs/components/landing/footer.tsx b/apps/docs/components/landing/footer.tsx
index 7a4f874..8100544 100644
--- a/apps/docs/components/landing/footer.tsx
+++ b/apps/docs/components/landing/footer.tsx
@@ -31,7 +31,7 @@ export function Footer() {
NPM
diff --git a/apps/docs/components/landing/hero-section.tsx b/apps/docs/components/landing/hero-section.tsx
index b4531ed..d222bd1 100644
--- a/apps/docs/components/landing/hero-section.tsx
+++ b/apps/docs/components/landing/hero-section.tsx
@@ -95,7 +95,7 @@ export function HeroSection() {
import{' '}
{'{ DevboxSDK }'}{' '}
from{' '}
- 'devbox-sdk'
+ '@labring/devbox-sdk'
{'\n\n'}
{'// Initialize SDK'}
{'\n'}
diff --git a/apps/docs/content/docs/api/devbox-instance.mdx b/apps/docs/content/docs/api/devbox-instance.mdx
index 4d47bfa..ec10db0 100644
--- a/apps/docs/content/docs/api/devbox-instance.mdx
+++ b/apps/docs/content/docs/api/devbox-instance.mdx
@@ -408,7 +408,7 @@ waitForReady(
## Complete Example
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
const sdk = new DevboxSDK({
kubeconfig: process.env.KUBECONFIG
diff --git a/apps/docs/content/docs/api/devbox-sdk.mdx b/apps/docs/content/docs/api/devbox-sdk.mdx
index 5865eca..0aae0c3 100644
--- a/apps/docs/content/docs/api/devbox-sdk.mdx
+++ b/apps/docs/content/docs/api/devbox-sdk.mdx
@@ -25,7 +25,7 @@ new DevboxSDK(config: DevboxSDKConfig)
### Example
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
const sdk = new DevboxSDK({
kubeconfig: process.env.KUBECONFIG,
@@ -212,7 +212,7 @@ try {
## Complete Example
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
async function main() {
const sdk = new DevboxSDK({
diff --git a/apps/docs/content/docs/api/types.mdx b/apps/docs/content/docs/api/types.mdx
index 82cd5be..ad97465 100644
--- a/apps/docs/content/docs/api/types.mdx
+++ b/apps/docs/content/docs/api/types.mdx
@@ -200,7 +200,7 @@ import type {
ProcessExecResponse,
FileChangeEvent,
GitCloneOptions
-} from 'devbox-sdk'
+} from '@labring/devbox-sdk'
```
## Next Steps
diff --git a/apps/docs/content/docs/examples/ai-agent-workflow.mdx b/apps/docs/content/docs/examples/ai-agent-workflow.mdx
index 42b27cc..444b827 100644
--- a/apps/docs/content/docs/examples/ai-agent-workflow.mdx
+++ b/apps/docs/content/docs/examples/ai-agent-workflow.mdx
@@ -10,7 +10,7 @@ This example demonstrates a complete workflow for executing AI-generated code sa
## Complete Example
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
async function executeAIAgent(aiGeneratedCode: string) {
const sdk = new DevboxSDK({
@@ -114,7 +114,7 @@ import {
DevboxSDKError,
FileOperationError,
ValidationError
-} from 'devbox-sdk'
+} from '@labring/devbox-sdk'
async function safeExecuteAI(code: string) {
const sdk = new DevboxSDK({
@@ -226,4 +226,5 @@ async function processAIBatch(tasks: Array<{ id: string; code: string }>) {
- Learn about [Automation Tasks](/docs/examples/automation-tasks)
- Explore [CI/CD Integration](/docs/examples/ci-cd-integration)
+- See the [Full Lifecycle Example](/docs/examples/full-lifecycle) for a complete workflow
diff --git a/apps/docs/content/docs/examples/automation-tasks.mdx b/apps/docs/content/docs/examples/automation-tasks.mdx
index 79871e5..4a6c9da 100644
--- a/apps/docs/content/docs/examples/automation-tasks.mdx
+++ b/apps/docs/content/docs/examples/automation-tasks.mdx
@@ -10,7 +10,7 @@ Execute untrusted automation scripts safely in isolated sandboxes.
## Basic Automation
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
async function runAutomation(script: string) {
const sdk = new DevboxSDK({
@@ -249,5 +249,6 @@ async function processFiles(
## Next Steps
- Learn about [CI/CD Integration](/docs/examples/ci-cd-integration)
+- See the [Full Lifecycle Example](/docs/examples/full-lifecycle) for a complete workflow
- Explore [API Reference](/docs/api/devbox-instance)
diff --git a/apps/docs/content/docs/examples/ci-cd-integration.mdx b/apps/docs/content/docs/examples/ci-cd-integration.mdx
index a99cb2c..73d64fb 100644
--- a/apps/docs/content/docs/examples/ci-cd-integration.mdx
+++ b/apps/docs/content/docs/examples/ci-cd-integration.mdx
@@ -37,7 +37,7 @@ jobs:
```typescript
// scripts/ci-test.js
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
import fs from 'fs'
async function runCITests() {
@@ -255,6 +255,7 @@ async function runParallelTests(testSuites: string[]) {
## Next Steps
+- See the [Full Lifecycle Example](/docs/examples/full-lifecycle) for a complete workflow
- Read [API Reference](/docs/api/devbox-sdk)
- Explore [Guides](/docs/guides/secure-code-execution)
diff --git a/apps/docs/content/docs/examples/full-lifecycle.mdx b/apps/docs/content/docs/examples/full-lifecycle.mdx
new file mode 100644
index 0000000..a7d3ee4
--- /dev/null
+++ b/apps/docs/content/docs/examples/full-lifecycle.mdx
@@ -0,0 +1,254 @@
+---
+title: Full Lifecycle Example
+description: Complete example demonstrating the full devbox lifecycle from creation to cleanup
+---
+
+# Full Lifecycle Example
+
+This example demonstrates a complete workflow for creating, managing, and cleaning up a devbox instance. It covers environment setup, devbox creation, execution of commands, and proper resource cleanup.
+
+## Complete Example
+
+This example shows how to:
+
+- Load environment variables and kubeconfig
+- Create a devbox instance
+- Start the devbox and wait for it to be ready
+- Execute commands in the devbox
+- Handle errors properly
+- Clean up resources
+
+```typescript
+import { config as loadEnv } from 'dotenv'
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { DevboxSDK } from '@labring/devbox-sdk'
+import { DevboxRuntime } from '@labring/devbox-sdk'
+
+// Load environment variables from .env file
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+const envPaths = [
+ resolve(__dirname, '.env'),
+ resolve(__dirname, '../.env'),
+ resolve(__dirname, '../../.env'),
+ resolve(process.cwd(), '.env'),
+]
+
+let envLoaded = false
+for (const envPath of envPaths) {
+ if (existsSync(envPath)) {
+ loadEnv({ path: envPath, override: false })
+ console.log(`โ
Loaded environment variables from ${envPath}`)
+ envLoaded = true
+ break
+ }
+}
+
+if (!envLoaded) {
+ console.warn('โ ๏ธ .env file not found, using system environment variables')
+}
+
+if (!process.env.KUBECONFIG) {
+ console.error('โ Missing required environment variable: KUBECONFIG')
+ process.exit(1)
+}
+
+let kubeconfigContent = process.env.KUBECONFIG
+
+// Handle kubeconfig as file path or content
+if (!kubeconfigContent.includes('apiVersion') && existsSync(kubeconfigContent)) {
+ kubeconfigContent = readFileSync(kubeconfigContent, 'utf-8')
+} else if (kubeconfigContent.includes('\\n')) {
+ kubeconfigContent = kubeconfigContent.replace(/\\n/g, '\n')
+}
+
+const SDK_CONFIG = {
+ kubeconfig: kubeconfigContent,
+ http: {
+ timeout: 300000, // 5 minutes
+ retries: 3,
+ rejectUnauthorized: false,
+ },
+}
+
+// Generate unique devbox name
+const generateDevboxName = (prefix: string) => {
+ const timestamp = Date.now()
+ const random = Math.floor(Math.random() * 1000)
+ const sanitizedPrefix = prefix.replace(/\./g, '-')
+ return `example-${sanitizedPrefix}-${timestamp}-${random}`
+}
+
+async function main() {
+ const sdk = new DevboxSDK(SDK_CONFIG)
+ const name = generateDevboxName('full-lifecycle')
+
+ try {
+ console.log('๐ Starting full lifecycle example...')
+ console.log(`๐ฆ Creating devbox: ${name}`)
+
+ // 1. Create devbox
+ const devbox = await sdk.createDevbox({
+ name,
+ runtime: DevboxRuntime.TEST_AGENT,
+ resource: { cpu: 1, memory: 2 },
+ })
+
+ console.log(`โ
Devbox created: ${devbox.name}`)
+ console.log('โณ Starting devbox...')
+
+ // 2. Start devbox
+ await devbox.start()
+
+ // 3. Wait for devbox to be ready
+ let currentDevbox = await sdk.getDevbox(name)
+ const startTime = Date.now()
+ const timeout = 30000 // 30 seconds
+
+ while (currentDevbox.status !== 'Running' && Date.now() - startTime < timeout) {
+ await new Promise(resolve => setTimeout(resolve, 2000))
+ currentDevbox = await sdk.getDevbox(name)
+ process.stdout.write('.')
+ }
+
+ console.log('')
+ console.log(`โ
Devbox is ${currentDevbox.status}`)
+
+ if (currentDevbox.status !== 'Running') {
+ throw new Error(`Devbox failed to start. Status: ${currentDevbox.status}`)
+ }
+
+ // 4. Execute commands in the devbox
+ console.log('')
+ console.log('๐ Testing command execution...')
+
+ // Method 1: Execute command with arguments
+ const homeResult1 = await currentDevbox.execSync({
+ command: 'echo',
+ args: ['$HOME'],
+ })
+ console.log(`๐ HOME: ${homeResult1.stdout.trim()}`)
+
+ // Method 2: Execute command with environment variable expansion
+ const homeResult2 = await currentDevbox.execSync({
+ command: 'echo',
+ args: ['My home is $HOME'],
+ })
+ console.log(`๐ Result: ${homeResult2.stdout.trim()}`)
+
+ // Method 3: Execute shell command with pipes
+ const homeResult3 = await currentDevbox.execSync({
+ command: 'echo $HOME | wc -c',
+ })
+ console.log(`๐ HOME length: ${homeResult3.stdout.trim()} characters`)
+
+ // 5. Additional operations can be added here:
+ // - File operations (writeFile, readFile, listFiles)
+ // - Git operations (clone, pull, push)
+ // - Process management (exec, getProcessStatus)
+ // - File watching (watchFiles)
+
+ console.log('')
+ console.log('๐ Full lifecycle example completed successfully!')
+
+ } catch (error) {
+ console.error('โ Error occurred:', error)
+ throw error
+ } finally {
+ // 6. Always clean up resources
+ try {
+ const devboxToDelete = await sdk.getDevbox(name).catch(() => null)
+ if (devboxToDelete) {
+ console.log(`๐งน Cleaning up devbox: ${name}`)
+ await devboxToDelete.delete()
+ console.log('โ
Devbox deleted successfully')
+ }
+ } catch (error) {
+ console.warn('โ ๏ธ Failed to delete devbox:', error)
+ }
+
+ await sdk.close()
+ console.log('โ
SDK connections closed')
+ }
+}
+
+main().catch((error) => {
+ console.error('Failed to run example:', error)
+ process.exit(1)
+})
+```
+
+## Key Features Demonstrated
+
+### 1. Environment Configuration
+
+The example shows how to:
+- Load environment variables from multiple possible locations
+- Handle kubeconfig as both file path and content string
+- Configure SDK with appropriate timeouts and retry settings
+
+### 2. Devbox Lifecycle Management
+
+- **Creation**: Create a devbox with specified runtime and resources
+- **Starting**: Start the devbox instance
+- **Status Checking**: Poll for devbox status until it's ready
+- **Cleanup**: Properly delete the devbox and close SDK connections
+
+### 3. Command Execution
+
+The example demonstrates three methods of executing commands:
+- Direct command execution with arguments
+- Environment variable expansion in commands
+- Shell features like pipes
+
+### 4. Error Handling
+
+- Try-catch blocks for error handling
+- Proper cleanup in finally block
+- Graceful handling of cleanup errors
+
+## Running the Example
+
+1. **Install dependencies**:
+
+```bash
+npm install @labring/devbox-sdk dotenv
+```
+
+2. **Set up environment variables**:
+
+Create a `.env` file or set the `KUBECONFIG` environment variable:
+
+```bash
+export KUBECONFIG=/path/to/your/kubeconfig
+```
+
+Or in a `.env` file:
+
+```
+KUBECONFIG=/path/to/your/kubeconfig
+```
+
+3. **Run the example**:
+
+```bash
+node full-lifecycle.js
+```
+
+## Best Practices
+
+1. **Always clean up**: Use try-finally blocks to ensure resources are cleaned up even if errors occur
+2. **Generate unique names**: Use timestamps and random numbers to avoid naming conflicts
+3. **Wait for readiness**: Always wait for devbox to be in "Running" status before executing commands
+4. **Handle timeouts**: Set appropriate timeouts for operations that might take time
+5. **Error handling**: Catch and handle errors appropriately, logging useful information
+
+## Next Steps
+
+- Learn about [File Operations](/docs/guides/file-operations)
+- Explore [Git Integration](/docs/guides/git-integration)
+- Read the [API Reference](/docs/api/devbox-sdk)
+
diff --git a/apps/docs/content/docs/getting-started/configuration.mdx b/apps/docs/content/docs/getting-started/configuration.mdx
index 7a9a1d0..65b95d3 100644
--- a/apps/docs/content/docs/getting-started/configuration.mdx
+++ b/apps/docs/content/docs/getting-started/configuration.mdx
@@ -10,7 +10,7 @@ description: Configure Devbox SDK for your needs
When creating a `DevboxSDK` instance, you can configure various options:
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
const sdk = new DevboxSDK({
// Required: Kubernetes configuration
@@ -157,7 +157,7 @@ export KUBECONFIG=/path/to/kubeconfig
## Example: Production Configuration
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
const sdk = new DevboxSDK({
kubeconfig: process.env.KUBECONFIG,
diff --git a/apps/docs/content/docs/getting-started/installation.mdx b/apps/docs/content/docs/getting-started/installation.mdx
index 15437cf..77c4541 100644
--- a/apps/docs/content/docs/getting-started/installation.mdx
+++ b/apps/docs/content/docs/getting-started/installation.mdx
@@ -15,19 +15,19 @@ description: Install and configure Devbox SDK
## Install the Package
```bash
-npm install devbox-sdk
+npm install @labring/devbox-sdk
```
Or with yarn:
```bash
-yarn add devbox-sdk
+yarn add @labring/devbox-sdk
```
Or with pnpm:
```bash
-pnpm add devbox-sdk
+pnpm add @labring/devbox-sdk
```
## Kubernetes Configuration
@@ -43,7 +43,7 @@ export KUBECONFIG=/path/to/your/kubeconfig
### Option 2: File Path
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
const sdk = new DevboxSDK({
kubeconfig: '/path/to/your/kubeconfig'
@@ -53,7 +53,7 @@ const sdk = new DevboxSDK({
### Option 3: Kubeconfig Content
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
import fs from 'fs'
const kubeconfigContent = fs.readFileSync('/path/to/kubeconfig', 'utf-8')
@@ -68,7 +68,7 @@ const sdk = new DevboxSDK({
Create a simple test file to verify your installation:
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
const sdk = new DevboxSDK({
kubeconfig: process.env.KUBECONFIG
diff --git a/apps/docs/content/docs/getting-started/quick-start.mdx b/apps/docs/content/docs/getting-started/quick-start.mdx
index 4146a26..10f9799 100644
--- a/apps/docs/content/docs/getting-started/quick-start.mdx
+++ b/apps/docs/content/docs/getting-started/quick-start.mdx
@@ -10,7 +10,7 @@ This guide will help you create your first secure sandbox and execute code safel
## Create Your First Sandbox
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
// Initialize SDK
const sdk = new DevboxSDK({
@@ -129,7 +129,7 @@ await sdk.close()
Here's a complete example that demonstrates the full workflow:
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
async function main() {
const sdk = new DevboxSDK({
@@ -172,6 +172,7 @@ main().catch(console.error)
## Next Steps
+- See the [Full Lifecycle Example](/docs/examples/full-lifecycle) for a complete workflow
- Learn about [Secure Code Execution](/docs/guides/secure-code-execution)
- Explore [File Operations](/docs/guides/file-operations)
- Read the [API Reference](/docs/api/devbox-sdk)
diff --git a/apps/docs/content/docs/index.mdx b/apps/docs/content/docs/index.mdx
index a243551..bc73404 100644
--- a/apps/docs/content/docs/index.mdx
+++ b/apps/docs/content/docs/index.mdx
@@ -21,13 +21,13 @@ Devbox SDK provides **container-based isolation** for safe code execution. Each
### Installation
```bash
-npm install devbox-sdk
+npm install @labring/devbox-sdk
```
### Your First Sandbox
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
// Initialize SDK
const sdk = new DevboxSDK({
@@ -128,6 +128,7 @@ await sandbox.git.pull('/workspace/repo')
- **[Guides](/docs/guides/secure-code-execution)** - Usage guides and best practices
- **[API Reference](/docs/api/devbox-sdk)** - Complete API documentation
- **[Examples](/docs/examples/ai-agent-workflow)** - Real-world examples
+ - [Full Lifecycle Example](/docs/examples/full-lifecycle) - Complete devbox lifecycle from creation to cleanup
## Next Steps
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index 1f4be59..2ad50bb 100644
--- a/packages/sdk/README.md
+++ b/packages/sdk/README.md
@@ -1,11 +1,11 @@
-# devbox-sdk
+# @labring/devbox-sdk
**Secure Sandbox SDK for Isolated Code Execution.** Execute AI-generated code, run automation tasks, and test untrusted code with zero risk to your infrastructure.
## Installation
```bash
-npm install devbox-sdk
+npm install @labring/devbox-sdk
```
## Requirements
@@ -18,7 +18,7 @@ npm install devbox-sdk
### Secure Code Execution
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
// Initialize SDK
const sdk = new DevboxSDK({
@@ -383,7 +383,7 @@ import {
FileOperationError,
DevboxNotFoundError,
ValidationError
-} from 'devbox-sdk'
+} from '@labring/devbox-sdk'
try {
await sandbox.writeFile('/invalid/path', 'content')
@@ -410,7 +410,7 @@ try {
### Complete AI Agent Workflow
```typescript
-import { DevboxSDK } from 'devbox-sdk'
+import { DevboxSDK } from '@labring/devbox-sdk'
async function runAIAgent() {
const sdk = new DevboxSDK({
@@ -457,7 +457,7 @@ import type {
FileMap,
ProcessExecOptions,
GitCloneOptions
-} from 'devbox-sdk'
+} from '@labring/devbox-sdk'
```
## Performance
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index 9b16c0c..8a44e2d 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -1,5 +1,5 @@
{
- "name": "devbox-sdk",
+ "name": "@labring/devbox-sdk",
"version": "1.1.2",
"description": "Enterprise TypeScript SDK for Sealos Devbox management",
"main": "./dist/index.cjs",