# Shakudo Microservice

> Deploy, restart, scale, and monitor Shakudo microservices. Use when creating new services, debugging deployments, or managing service lifecycle. Covers git sync, environment configuration, and log monitoring workflows.

- Skill: `shakudo-io/shakudo-microservice` (Agent Skill)
- Install (CLI): `npx skillmds@latest add shakudo-io/shakudo-microservice`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shakudo-io/shakudo-microservice/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: Shakudo-io (https://skillmd.com/u/shakudo-io)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/shakudo-io/shakudo-microservice

---


# Shakudo Microservice Management

This skill teaches you how to manage Shakudo microservices correctly, including deployment, restart, scaling, and debugging workflows.

## Prerequisites

- Access to Shakudo platform MCP tools (`shakudo-platform_*`)
- Environment variable `USER_EMAIL` must be set (required for all operations)
- Git repository synced with Shakudo platform

## Core Concepts

### Environment Configuration

- **Default environment**: `basic-ai-tools-small` (use unless user specifies otherwise)
- **Git server**: `demos` (default, verify with `listGitServers`)
- **Branch**: `main` (default)
- **Port**: `8787` (default for most services)

### Key Environment Variables

```
USER_EMAIL     - Owner email (REQUIRED for all operations)
MY_JOB_ID      - Current job ID (for URL construction)
```

## Workflows

### 1. Create a New Microservice

**Step-by-step:**

1. **Discover valid environments** (if unsure):
   ```
   shakudo-platform_listEnvironments({ search: "basic" })
   ```

2. **Verify git server is available**:
   ```
   shakudo-platform_listGitServers()
   ```

3. **Create the microservice**:
   ```
   shakudo-platform_createMicroservice({
     name: "my-service-name",       # MUST: lowercase, hyphens, 1-63 chars
     userEmail: process.env.USER_EMAIL,
     environment: "basic-ai-tools-small",
     gitServer: "demos",
     branch: "main",
     port: 8787,
     script: "run.sh"
   })
   ```

4. **Poll for status** until `status='running'`:
   ```
   shakudo-platform_searchMicroservice({ searchTerm: "my-service-name" })
   ```
   Typical startup: 30-120 seconds

5. **Verify service is healthy** by checking logs:
   ```
   shakudo-platform_getPodEvents({ jobId: "<service-id>" })
   ```

### 2. Restart a Microservice (After Code Changes)

**IMPORTANT**: Do NOT cancel/delete the service when debugging. Instead:

1. **Fix the bug in code**

2. **Commit and push to git**:
   ```bash
   git add . && git commit -m "[subfolder] fix description" && git push
   ```

3. **Wait for git sync** (check sync status):
   ```
   shakudo-platform_checkGitServerSync()
   ```
   Wait until the repository shows as synced (usually 30-60 seconds)

4. **Find the service ID**:
   ```
   shakudo-platform_searchMicroservice({ searchTerm: "my-service-name" })
   ```

5. **Restart the service**:
   ```
   shakudo-platform_restartService({ id: "<service-id>" })
   ```

6. **Watch logs for success**:
   ```
   shakudo-platform_getPodEvents({ jobId: "<service-id>", tailLines: 100 })
   ```

### 3. Scale a Microservice

**Scale to zero (stop without deleting):**
```
shakudo-platform_scaleService({ id: "<service-id>", newReplicas: 0 })
```

**Scale up for more capacity:**
```
shakudo-platform_scaleService({ id: "<service-id>", newReplicas: 3 })
```

### 4. Debug a Failing Microservice

1. **Get pod events and logs**:
   ```
   shakudo-platform_getPodEvents({ 
     jobId: "<service-id>",
     tailLines: 200
   })
   ```

2. **Check common issues**:
   - Port mismatch (service expects different port than configured)
   - Missing environment variables
   - Script path incorrect (`run.sh` not found)
   - Git not synced (old code deployed)

3. **Search for service by name** (to get full details):
   ```
   shakudo-platform_listPipelineJobs({
     jobName: "my-service",
     isService: true,
     limit: 10
   })
   ```

### 5. Delete a Microservice

**WARNING: This is permanent and cannot be undone.**

```
shakudo-platform_deleteMicroservice({ 
  id: "<service-id>",
  confirm: true  # REQUIRED safety flag
})
```

## URL Patterns

### External URLs (Public Access)

Pattern: `https://{service-name}.dev.hyperplane.dev`

Priority order for URL construction:
1. `mappedUrl` (if available)
2. `https://{userServiceSubdomain}.dev.hyperplane.dev`
3. `https://{dashboardPrefix}.dev.hyperplane.dev`
4. `https://{service-name}.dev.hyperplane.dev`

### In-cluster URLs (Internal Access)

Pattern: `http://hyperplane-service-{first-6-chars-of-id}.hyperplane-pipelines.svc.cluster.local:8787`

**Use in-cluster URLs for:**
- Playwright testing
- Service-to-service communication
- Health checks

## Common Mistakes to Avoid

1. **Don't guess the environment name** - Always verify with `listEnvironments`
2. **Don't restart before git sync** - Check `checkGitServerSync` first
3. **Don't use `npm` or `pnpm`** - Use `bun` and `bunx` instead
4. **Don't delete to debug** - Use restart workflow instead
5. **Don't hardcode USER_EMAIL** - Always read from environment variable

## Examples

### Deploy a React App

```javascript
// 1. Create microservice
shakudo-platform_createMicroservice({
  name: "my-react-app",
  userEmail: process.env.USER_EMAIL,
  environment: "basic-ai-tools-small",
  port: 3000,
  script: "run.sh"  // Should contain: bunx vite --port 3000 --host
})

// 2. Wait for running status
// 3. Access at: https://my-react-app.dev.hyperplane.dev
```

### Deploy a Python API

```javascript
// 1. Create microservice  
shakudo-platform_createMicroservice({
  name: "my-python-api",
  userEmail: process.env.USER_EMAIL,
  environment: "basic-ai-tools-small",
  port: 8000,
  script: "run.sh"  // Should contain: uv run uvicorn main:app --port 8000 --host 0.0.0.0
})
```