Skip to main content

​
Usage

nanobot onboard

​
Description

The onboard command initializes nanobot for first-time use by:
  1. Creating the configuration file (~/.nanobot/config.json)
  2. Setting up the workspace directory
  3. Syncing default templates (SOUL.md, TOOLS.md, etc.)
  4. Displaying next steps for getting started
This is typically the first command you run after installing nanobot.

​
Options

This command has no additional options.

​
First Run

When running for the first time: 
nanobot onboard
Output: 
[green]✓[/green] Created config at ~/.nanobot/config.json
[green]✓[/green] Created workspace at ~/.nanobot/workspace/

🐈 nanobot is ready!

Next steps:
  1. Add your API key to [cyan]~/.nanobot/config.json[/cyan]
     Get one at: https://openrouter.ai/keys
  2. Chat: [cyan]nanobot agent -m "Hello!"[/cyan]

[dim]Want Telegram/WhatsApp? See: https://github.com/HKUDS/nanobot#-chat-apps[/dim]

​
Subsequent Runs

If configuration already exists, you get options: 
nanobot onboard
Output: 
[yellow]Config already exists at ~/.nanobot/config.json[/yellow]
  [bold]y[/bold] = overwrite with defaults (existing values will be lost)
  [bold]N[/bold] = refresh config, keeping existing values and adding new fields
Overwrite? [y/N]:

​
Refresh Config (Default)

Press N or Enter: 
[green]✓[/green] Config refreshed at ~/.nanobot/config.json (existing values preserved)
This:
  • Keeps your existing settings (API keys, preferences)
  • Adds any new configuration fields from updates
  • Preserves your workspace
Use this for: Updating to a new nanobot version

​
Overwrite Config

Press y: 
[green]✓[/green] Config reset to defaults at ~/.nanobot/config.json
This:
  • Replaces config with factory defaults
  • Removes all your settings (API keys, customizations)
  • Preserves workspace files
Use this for: Starting completely fresh

​
What Gets Created

​
Configuration File

Location: ~/.nanobot/config.json 
{
  "agents": {
    "defaults": {
      "model": "openai/gpt-4",
      "temperature": 0.7,
      "max_tokens": 4096,
      "max_tool_iterations": 10,
      "memory_window": 20,
      "reasoning_effort": "medium",
      "workspace": "~/.nanobot/workspace"
    }
  },
  "providers": {
    "openrouter": {
      "api_key": ""
    }
  },
  "tools": {
    "restrict_to_workspace": false,
    "exec": {
      "timeout_seconds": 300
    },
    "web": {
      "enabled": true,
      "search": {
        "enabled": true,
        "api_key": ""
      }
    }
  },
  "channels": {
    "send_progress": true,
    "send_tool_hints": false,
    "telegram": {
      "enabled": false,
      "token": ""
    },
    "whatsapp": {
      "enabled": false
    }
  },
  "gateway": {
    "heartbeat": {
      "enabled": true,
      "interval_s": 3600
    }
  }
}

​
Workspace Directory

Location: ~/.nanobot/workspace/ 
~/.nanobot/workspace/
├── SOUL.md          # Agent personality and behavior
├── TOOLS.md         # Available tools documentation
├── USER.md          # User information (optional)
├── AGENTS.md        # Agent configurations
├── HEARTBEAT.md     # Heartbeat task prompts
├── sessions/        # Chat sessions
└── memory/          # Agent memory
    └── MEMORY.md    # Memory instructions

​
Template Files

Default templates are synced from the nanobot package:
  • SOUL.md: Defines agent personality
  • TOOLS.md: Documents available tools
  • USER.md: Space for user context
  • AGENTS.md: Multi-agent configurations
  • HEARTBEAT.md: Proactive task definitions
  • MEMORY.md: Memory system instructions
These files are editable - customize them for your use case.

​
Configuration Steps

​
1. Add API Key

Edit ~/.nanobot/config.json: 
vim ~/.nanobot/config.json
# or
nano ~/.nanobot/config.json
Add your API key: 
{
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-..."
    }
  }
}
Get an API key:

​
2. Test Connection

nanobot agent -m "Hello!"
Expected output: 
🐈 nanobot

Hello! I'm your personal AI assistant. How can I help you today?

​
3. Optional: Configure Channels

For Telegram: 
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN"
    }
  }
}
See Channels for setup guides.

​
Customization

​
Change Default Model

Edit config.json: 
{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-3-5-sonnet"
    }
  }
}

​
Customize Workspace Location

{
  "agents": {
    "defaults": {
      "workspace": "/path/to/custom/workspace"
    }
  }
}
Then run onboard again to sync templates.

​
Edit Agent Personality

Edit ~/.nanobot/workspace/SOUL.md: 
# Agent Personality

You are a helpful coding assistant specializing in Python and Go.

## Behavior
- Be concise and technical
- Provide code examples
- Explain trade-offs

## Constraints
- Don't use external libraries unless necessary
- Prefer standard library solutions

​
Verification

After onboarding, verify the setup: 
nanobot status
Output: 
🐈 nanobot Status

Config: ~/.nanobot/config.json [green]✓[/green]
Workspace: ~/.nanobot/workspace/ [green]✓[/green]
Model: openai/gpt-4
OpenRouter: [green]✓[/green]

​
Directory Structure

Complete structure after onboarding: 
~/.nanobot/
├── config.json              # Main configuration
├── workspace/               # Agent workspace
│   ├── SOUL.md             # Agent personality
│   ├── TOOLS.md            # Tool documentation
│   ├── USER.md             # User context (optional)
│   ├── AGENTS.md           # Multi-agent setup
│   ├── HEARTBEAT.md        # Proactive tasks
│   ├── sessions/           # Chat sessions
│   │   └── cli_direct.json
│   └── memory/             # Agent memory
│       └── MEMORY.md
├── history/                # CLI history
│   └── cli_history
├── cron/                   # Scheduled jobs
│   └── jobs.json
└── bridge/                 # WhatsApp bridge (if used)

​
Template Syncing

Templates are synced on:
  1. Running nanobot onboard
  2. Starting nanobot gateway
  3. Running nanobot agent
Syncing behavior:
  • Existing files: Not overwritten (your edits are safe)
  • Missing files: Created from defaults
  • New templates: Added from updates

​
Migration

​
From Old Versions

If upgrading from an older version: 
# Backup existing config
cp ~/.nanobot/config.json ~/.nanobot/config.json.backup

# Refresh config (preserves values)
nanobot onboard
# Press 'N' to refresh

# Verify
nanobot status

​
Manual Migration

If you need to migrate manually: 
# Export old config
jq . ~/.nanobot/config.json.backup > old_config.json

# Create new config
nanobot onboard  # Press 'y' to overwrite

# Manually merge API keys and settings
vim ~/.nanobot/config.json

​
Uninstall

To remove all nanobot data: 
rm -rf ~/.nanobot/
To reinstall: 
pip install --force-reinstall nanobot
nanobot onboard

​
Troubleshooting

​
Permission Denied

Permission denied: ~/.nanobot/config.json
Solution: 
sudo chown -R $USER ~/.nanobot/
chmod -R u+rw ~/.nanobot/

​
Disk Full

No space left on device
Solution: 
# Check disk space
df -h

# Clean up old sessions
rm -rf ~/.nanobot/workspace/sessions/*.json

​
Template Sync Failed

[red]Failed to sync templates[/red]
Solution: 
# Reinstall package
pip install --force-reinstall nanobot

# Re-run onboard
nanobot onboard

​
Exit Codes

  • 0: Success
  • 1: Error (I/O, permissions)

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us