Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HKUDS/nanobot/llms.txt

Use this file to discover all available pages before exploring further.

​
Usage

nanobot status

​
Description

The status command displays the current state of your nanobot installation, including:
  • Configuration file status
  • Workspace directory status
  • Active model configuration
  • Provider API key status
  • OAuth authentication status
Use this command to verify your setup and troubleshoot configuration issues.

​
Options

This command has no additional options.

​
Example Output

​
Fully Configured System

nanobot status
Output: 
🐈 nanobot Status

Config: ~/.nanobot/config.json [green]✓[/green]
Workspace: ~/.nanobot/workspace/ [green]✓[/green]
Model: openai/gpt-4
OpenRouter: [green]✓[/green]
OpenAI: [green]✓[/green]
Anthropic: [dim]not set[/dim]
Google AI: [dim]not set[/dim]

​
Missing Configuration

nanobot status
Output: 
🐈 nanobot Status

Config: ~/.nanobot/config.json [red]✗[/red]
Workspace: ~/.nanobot/workspace/ [red]✗[/red]
Model: openai/gpt-4
Action: Run nanobot onboard to initialize.

​
OAuth Provider

nanobot status
Output: 
🐈 nanobot Status

Config: ~/.nanobot/config.json [green]✓[/green]
Workspace: ~/.nanobot/workspace/ [green]✓[/green]
Model: openai-codex/gpt-4o
OpenAI Codex: [green]✓ (OAuth)[/green]
GitHub Copilot: [green]✓ (OAuth)[/green]

​
Local Model

nanobot status
Output: 
🐈 nanobot Status

Config: ~/.nanobot/config.json [green]✓[/green]
Workspace: ~/.nanobot/workspace/ [green]✓[/green]
Model: ollama/llama3
Ollama: [green]✓ http://localhost:11434[/green]

​
Status Fields

​
Config File

Shows whether the configuration file exists:
  • [green]✓[/green]: File exists and is readable
  • [red]✗[/red]: File missing or unreadable
Location: ~/.nanobot/config.json

​
Workspace Directory

Shows whether the workspace directory exists:
  • [green]✓[/green]: Directory exists
  • [red]✗[/red]: Directory missing
Location: From config or ~/.nanobot/workspace/

​
Model

Displays the currently configured model: 
Model: openai/gpt-4
Format: provider/model-name Configured in: config.json → agents.defaults.model

​
Provider Status

Shows authentication status for each provider:

​
API Key Providers

  • [green]✓[/green]: API key is set
  • [dim]not set[/dim]: No API key configured
Example: 
OpenRouter: [green]✓[/green]
OpenAI: [green]✓[/green]
Anthropic: [dim]not set[/dim]

​
OAuth Providers

  • [green]✓ (OAuth)[/green]: Authenticated via OAuth
Example: 
OpenAI Codex: [green]✓ (OAuth)[/green]
GitHub Copilot: [green]✓ (OAuth)[/green]

​
Local Providers

Shows the API base URL: 
Ollama: [green]✓ http://localhost:11434[/green]
LM Studio: [green]✓ http://localhost:1234[/green]
Or if not configured: 
Ollama: [dim]not set[/dim]

​
Provider Types

​
Standard API Key Providers

  • OpenRouter: Multi-model gateway
  • OpenAI: Official OpenAI API
  • Anthropic: Claude models
  • Google AI: Gemini models
  • Groq: Fast inference
  • Together AI: Open source models
  • Replicate: ML model hosting

​
OAuth Providers

  • OpenAI Codex: IDE integrations (OAuth required)
  • GitHub Copilot: GitHub authentication

​
Local Providers

  • Ollama: Local LLM runtime
  • LM Studio: Desktop LLM app
  • Custom: Any OpenAI-compatible endpoint

​
Interpreting Status

​
Ready to Use

Config: [green]✓[/green]
Workspace: [green]✓[/green]
Model: openai/gpt-4
OpenRouter: [green]✓[/green]
You can start using nanobot: 
nanobot agent -m "Hello!"

​
Not Initialized

Config: [red]✗[/red]
Workspace: [red]✗[/red]
Action: 
nanobot onboard

​
Missing API Key

Config: [green]✓[/green]
Workspace: [green]✓[/green]
Model: openai/gpt-4
OpenRouter: [dim]not set[/dim]
Action:
  1. Get API key from provider
  2. Edit config: 
    vim ~/.nanobot/config.json
  3. Add key: 
    {
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-..."
    }
  }
}

​
Wrong Provider for Model

Model: anthropic/claude-3-5-sonnet
Anthropic: [dim]not set[/dim]
Action: Add Anthropic API key or switch to a provider you have configured.

​
OAuth Not Authenticated

Model: openai-codex/gpt-4o
OpenAI Codex: [dim]not set[/dim]
Action: 
nanobot provider login openai-codex

​
Configuration Verification

​
Check Config File

cat ~/.nanobot/config.json | jq .

​
Check Workspace

ls -la ~/.nanobot/workspace/
Expected files: 
SOUL.md
TOOLS.md
USER.md
AGENTS.md
HEARTBEAT.md
sessions/
memory/

​
Validate JSON

jq empty ~/.nanobot/config.json
No output = valid JSON
Error = syntax error in config

​
Troubleshooting

​
Status Shows Wrong Model

The model shown is from config.json: 
jq '.agents.defaults.model' ~/.nanobot/config.json
To change: 
jq '.agents.defaults.model = "anthropic/claude-3-5-sonnet"' \
  ~/.nanobot/config.json > tmp.json && \
  mv tmp.json ~/.nanobot/config.json

​
Provider Shows Checkmark But Fails

Status only checks if the key is set, not if it’s valid. Test the API: 
nanobot agent -m "test"
If it fails, the key may be:
  • Expired
  • Invalid
  • Out of credits
  • Wrong format

​
OAuth Provider Not Showing

OAuth providers only appear in status if:
  1. They’re in the registry (built-in support)
  2. Authentication has been attempted
Authenticate: 
nanobot provider login openai-codex

​
Local Provider Shows Not Set

For local providers (Ollama, LM Studio), you need to set the api_base: 
{
  "providers": {
    "ollama": {
      "api_base": "http://localhost:11434"
    }
  }
}
Then set the model: 
{
  "agents": {
    "defaults": {
      "model": "ollama/llama3"
    }
  }
}

​
Workspace Path Wrong

If the workspace path doesn’t match your config: 
jq '.agents.defaults.workspace' ~/.nanobot/config.json
Update if needed: 
{
  "agents": {
    "defaults": {
      "workspace": "/path/to/workspace"
    }
  }
}
Then sync templates: 
nanobot onboard  # Press 'N' to refresh

​
Exit Codes

  • 0: Success (always)
This command always exits with 0, even if configuration is missing. It’s informational only.

​
Scripting

Parse status output in scripts: 
#!/bin/bash

status=$(nanobot status)

if echo "$status" | grep -q "Config.*✓"; then
  echo "Config OK"
else
  echo "Config missing"
  nanobot onboard
fi

​
See Also