io-setup

name	io-setup
description	Help users configure IO Φ CLI usage, setup wizard, model/provider selection, tools, skills, voice/STT/TTS, gateway, and troubleshooting. Use when someone asks to enable features, configure settings, or needs help with IO itself.
version	1.1.0
author	IO
tags	["setup","configuration","tools","stt","tts","voice","io","cli","skills"]

IO Setup & Configuration

Use this skill when a user asks about configuring IO, enabling features, setting up voice, managing tools/skills, or troubleshooting.

Key Paths

• Config: ~/.io/config.yaml
• API keys: ~/.io/.env
• Skills: ~/.io/skills/
• IO install: ~/.io/io/
• Venv: ~/.io/io/.venv/ (or venv/)

CLI Overview

IO is used via the io command (or python -m io_cli.main from the repo).

Core commands:

io                          Interactive chat (default)
io chat -q "question"       Single query, then exit
io chat -m MODEL            Chat with a specific model
io -c                       Resume most recent session
io -c "project name"        Resume session by name
io --resume SESSION_ID      Resume by exact ID
io -w                       Isolated git worktree mode
io -s skill1,skill2         Preload skills for the session
io --yolo                   Skip dangerous command approval

Configuration & setup:

io setup                    Interactive setup wizard (provider, API keys, model)
io model                    Interactive model/provider selection
io config                   View current configuration
io config edit              Open config.yaml in $EDITOR
io config set KEY VALUE     Set a config value directly
io login                    Authenticate with a provider
io logout                   Clear stored auth
io doctor                   Check configuration and dependencies

Tools & skills:

io tools                    Interactive tool enable/disable per platform
io skills list              List installed skills
io skills search QUERY      Search the skills hub
io skills install NAME      Install a skill from the hub
io skills config            Enable/disable skills per platform

Gateway (messaging platforms):

io gateway run              Start the messaging gateway
io gateway install          Install gateway as background service
io gateway status           Check gateway status

Session management:

io sessions list            List past sessions
io sessions browse          Interactive session picker
io sessions rename ID TITLE Rename a session
io sessions export ID       Export session as markdown
io sessions prune           Clean up old sessions

Other:

io status                   Show status of all components
io cron list                List cron jobs
io insights                 Usage analytics
io update                   Update to latest version
io pairing                  Manage DM authorization codes

Setup Wizard (io setup)

The interactive setup wizard walks through:

1. Provider selection Φ OpenRouter, Anthropic, OpenAI, Google, DeepSeek, and many more
2. API key entry Φ stores securely in the env file
3. Model selection Φ picks from available models for the chosen provider
4. Basic settings Φ reasoning effort, tool preferences

Run it from terminal:

cd ~/.io/io
source .venv/bin/activate
python -m io_cli.main setup

To change just the model/provider later: io model

Skills Configuration (io skills)

Skills are reusable instruction sets that extend what IO can do.

Managing skills:

io skills list              # Show installed skills
io skills search "docker"   # Search the hub
io skills install NAME      # Install from hub
io skills config            # Enable/disable per platform

Per-platform skill control:

io skills config opens an interactive UI where you can enable or disable specific skills for each platform (cli, telegram, discord, etc.). Disabled skills won't appear in the agent's available skills list for that platform.

Loading skills in a session:

• CLI: io -s skill-name or io -s skill1,skill2
• Chat: /skill skill-name
• Gateway: type /skill skill-name in any chat

Voice Messages (STT)

Voice messages from Telegram/Discord/WhatsApp/Slack/Signal are auto-transcribed when an STT provider is available.

Provider priority (auto-detected):

1. Local faster-whisper Φ free, no API key, runs on CPU/GPU
2. Groq Whisper Φ free tier, needs GROQ_API_KEY
3. OpenAI Whisper Φ paid, needs VOICE_TOOLS_OPENAI_KEY

Setup local STT (recommended):

cd ~/.io/io
source .venv/bin/activate  # or: source venv/bin/activate
pip install faster-whisper

Add to config.yaml under the stt: section:

stt:
  enabled: true
  provider: local
  local:
    model: base  # Options: tiny, base, small, medium, large-v3

Model downloads automatically on first use (~150 MB for base).

Setup Groq STT (free cloud):

1. Get free key from https://console.groq.com
2. Add GROQ_API_KEY to the env file
3. Set provider to groq in config.yaml stt section

Verify STT:

After config changes, restart the gateway (send /restart in chat, or restart io gateway run). Then send a voice message.

Voice Replies (TTS)

IO can reply with voice when users send voice messages.

TTS providers (set API key in env file):

Provider	Env var	Free?
ElevenLabs	ELEVENLABS_API_KEY	Free tier
OpenAI	VOICE_TOOLS_OPENAI_KEY	Paid
Kokoro (local)	None needed	Free
Fish Audio	FISH_AUDIO_API_KEY	Free tier

Voice commands (in any chat):

• /voice on Φ voice reply to voice messages only
• /voice tts Φ voice reply to all messages
• /voice off Φ text only (default)

Enabling/Disabling Tools (io tools)

Interactive tool config:

cd ~/.io/io
source .venv/bin/activate
python -m io_cli.main tools

This opens a curses UI to enable/disable toolsets per platform (cli, telegram, discord, slack, etc.).

After changing tools:

Use /reset in the chat to start a fresh session with the new toolset. Tool changes do NOT take effect mid-conversation (this preserves prompt caching and avoids cost spikes).

Common toolsets:

Toolset	What it provides
terminal	Shell command execution
file	File read/write/search/patch
web	Web search and extraction
browser	Browser automation (needs Browserbase)
image_gen	AI image generation
mcp	MCP server connections
voice	Text-to-speech output
cronjob	Scheduled tasks

Installing Dependencies

Some tools need extra packages:

cd ~/.io/io && source .venv/bin/activate

pip install faster-whisper    # Local STT (voice transcription)
pip install browserbase       # Browser automation
pip install mcp               # MCP server connections

Config File Reference

The main config file is ~/.io/config.yaml. Key sections:

# Model and provider
model:
  default: anthropic/claude-opus-4.6
  provider: openrouter

# Agent behavior
agent:
  max_turns: 90
  reasoning_effort: high    # xhigh, high, medium, low, minimal, none

# Voice
stt:
  enabled: true
  provider: local           # local, groq, openai
tts:
  provider: elevenlabs      # elevenlabs, openai, kokoro, fish

# Display
display:
  skin: default             # default, ares, mono, slate
  tool_progress: full       # full, compact, off
  background_process_notifications: all  # all, result, error, off

Edit with io config edit or io config set KEY VALUE.

Gateway Commands (Messaging Platforms)

Command	What it does
/reset or /new	Fresh session (picks up new tool config)
/help	Show all commands
/model [name]	Show or change model
/compact	Compress conversation to save context
/voice [mode]	Configure voice replies
/reasoning [effort]	Set reasoning level
/sethome	Set home channel for cron/notifications
/restart	Restart the gateway (picks up config changes)
/status	Show session info
/retry	Retry last message
/undo	Remove last exchange
/personality [name]	Set agent personality
/skill [name]	Load a skill

Troubleshooting

Voice messages not working

1. Check stt.enabled is true in config.yaml
2. Check a provider is available (faster-whisper installed, or API key set)
3. Restart gateway after config changes (/restart)

Tool not available

1. Run io tools to check if the toolset is enabled for your platform
2. Some tools need env vars Φ check the env file
3. Use /reset after enabling tools

Model/provider issues

1. Run io doctor to check configuration
2. Run io login to re-authenticate
3. Check the env file has the right API key

Changes not taking effect

• Gateway: /reset for tool changes, /restart for config changes
• CLI: start a new session

Skills not showing up

1. Check io skills list shows the skill
2. Check io skills config has it enabled for your platform
3. Load explicitly with /skill name or io -s name