Configuration

ShipMyAgent is configured with four core files:

PROFILE.md: agent role and boundaries (required)
SOUL.md: stable operating principles (optional)
USER.md: user preferences (optional)
ship.json: runtime configuration (required)

Key `ship.json` fields

`start`

Startup options (CLI flags override these values):

{
  "start": {
    "port": 3000,
    "host": "0.0.0.0"
  }
}

`model`

Agent model binding (maps to console-global model pool):

{
  "model": {
    "primary": "default"
  }
}

`services.chat`

Chat channels and queue behavior:

{
  "services": {
    "chat": {
      "method": "direct",
      "queue": {
        "maxConcurrency": 2,
        "mergeDebounceMs": 600,
        "mergeMaxWaitMs": 2000
      },
      "channels": {
        "telegram": {
          "enabled": true,
          "botToken": "${TELEGRAM_BOT_TOKEN}",
          "auth_id": "123456789"
        }
      }
    }
  }
}

services.chat.queue notes:

maxConcurrency: max lane concurrency across different chat keys.
mergeDebounceMs: short debounce window for batching consecutive inbound messages in one run.
mergeMaxWaitMs: hard cap for the batching wait to avoid unbounded delay.

`services.skills`

Skills discovery roots:

{
  "services": {
    "skills": {
      "paths": [".agents/skills"],
      "allowExternalPaths": false
    }
  }
}

`extensions.voice`

Local speech-to-text extension:

{
  "extensions": {
    "voice": {
      "enabled": true,
      "provider": "local",
      "activeModel": "SenseVoiceSmall"
    }
  }
}

`permissions`

Repository write and command execution policies:

{
  "permissions": {
    "read_repo": true,
    "write_repo": { "requiresApproval": false },
    "exec_command": {
      "deny": ["rm"],
      "requiresApproval": false,
      "maxOutputChars": 12000,
      "maxOutputLines": 200
    }
  }
}

Useful commands

sma console config get
sma console config get model.primary
sma console config llm model list
sma console config set start.port 3100
sma console config unset services.chat.channels.telegram