Skip to main content
Complete reference for .opencode.config.json.

​
Location

  • Project: .opencode.config.json in project root
  • Global fallback: ~/.config/sincronizado/config.json

​
Schema

{
  "vps": {
    "default": "string",
    "hosts": {
      "host-name": {
        "hostname": "string",
        "user": "string",
        "port": 2222,
        "provider": "string"
      }
    }
  },
  "sync": {
    "ignore": ["string"]
  },
  "session": {
    "prefix": "string",
    "default_editor": "string"
  },
  "plugins": {
    "enabled": ["string"]
  }
}

​
Options

​
vps.default

  • Type: string
  • Required: yes
  • Example: "oracle-ashburn"

​
vps.hosts

  • Type: object
  • Required: yes

​
host.hostname

  • Type: string
  • Required: yes
  • Example: "my-vps.tailnet.ts.net"

​
host.user

  • Type: string
  • Default: "ubuntu"

​
host.port

  • Type: integer
  • Default: 2222

​
host.provider

  • Type: string
  • Example: "oracle"

​
sync.ignore

  • Type: array of strings
  • Default: ["node_modules", ".venv", ".git", "dist", "build"]

​
session.prefix

  • Type: string
  • Default: "sync-"

​
session.default_editor

  • Type: string
  • Default: "code"

​
plugins.enabled

  • Type: array of strings
  • Default: ["opencode-direnv", "agentmap", "opencode-sync", "ai-sessions-mcp", "ccmanager"]

​
Example

{
  "vps": {
    "default": "oracle-ashburn",
    "hosts": {
      "oracle-ashburn": {
        "hostname": "ashburn",
        "user": "ubuntu",
        "port": 2222,
        "provider": "oracle"
      }
    }
  },
  "sync": {
    "ignore": ["node_modules", ".venv", ".git", "dist", "build"]
  }
}

​
Examples

​
Single VPS (Oracle)

{
  "vps": {
    "default": "oracle-ashburn",
    "hosts": {
      "oracle-ashburn": {
        "hostname": "ashburn",
        "user": "ubuntu",
        "port": 2222,
        "provider": "oracle"
      }
    }
  }
}

​
Multiple VPS (prod + staging)

{
  "vps": {
    "default": "prod",
    "hosts": {
      "prod": {
        "hostname": "prod-vps",
        "user": "ubuntu",
        "port": 2222
      },
      "staging": {
        "hostname": "staging-vps",
        "user": "ubuntu",
        "port": 2222
      }
    }
  }
}

​
Custom sync ignore

{
  "sync": {
    "ignore": ["node_modules", ".venv", ".git", "dist", "build", "*.tmp", "data/large-files/"]
  }
}

​
Full configuration

{
  "vps": {
    "default": "my-vps",
    "hosts": {
      "my-vps": {
        "hostname": "my-vps.tailnet.ts.net",
        "user": "ubuntu",
        "port": 2222,
        "provider": "hetzner"
      }
    }
  },
  "sync": {
    "ignore": ["node_modules", ".venv", ".git", "dist", "build", "__pycache__", ".pytest_cache"]
  },
  "session": {
    "prefix": "sync-",
    "default_editor": "code"
  },
  "plugins": {
    "enabled": ["opencode-direnv", "agentmap", "opencode-sync", "ai-sessions-mcp", "ccmanager"]
  }
}

​
Validation

Windows: 
.\scripts\config-wizard.ps1 -Validate
Checks:
  • Required fields present
  • Valid JSON syntax
  • Host configurations complete

​
Troubleshooting

​
Config not loading

  1. Check file is valid JSON: python -m json.tool < .opencode.config.json
  2. Verify file is in project root
  3. Check file permissions (readable)

​
VPS not found

  1. Verify vps.default matches a key in vps.hosts
  2. Check hostname is correct
  3. Ensure user has SSH access