Skip to main content
sincronizado uses a single JSON configuration file located at: ~/.config/sincronizado/config.json This file is created automatically when you run sinc --setup, but you can edit it manually to fine-tune your experience.

​
The Config Object

Here is the full schema with default values: 
{
  "vps": {
    "hostname": "192.168.1.100",  // Required: IP or Domain
    "user": "ubuntu",             // Default: ubuntu
    "port": 22,                   // Default: 22
    "keyPath": "~/.ssh/id_ed25519" // Optional: Force specific key
  },
  "sync": {
    "mode": "both",               // options: both, push, pull, none
    "remoteBase": "~/workspace",  // Where projects live on VPS
    "ignore": [                   // Global ignore list
      ".git",
      "node_modules",
      ".next",
      "dist",
      "coverage",
      "*.log"
    ]
  },
  "agent": "opencode",            // options: opencode, claude
  "ssh": {
    "connectTimeout": 10,         // Seconds to wait for connection
    "keepaliveInterval": 60       // Seconds between keepalive packets
  }
}

​
Detailed Options

​
vps Section

OptionTypeDescription
hostnamestringRequired. The IP address or domain name of your VPS.
userstringThe SSH username. Defaults to ubuntu. Common alternatives: root, debian, ec2-user.
portnumberThe SSH port. Defaults to 22.
keyPathstringPath to a specific private key file. If omitted, ssh uses its default resolution (checking ~/.ssh/config, id_rsa, etc.).

​
sync Section

Controls how files are synchronized between your machine and the VPS.

​
mode

  • both (Default): Two-way Safe Sync. Changes on either side are synced. Conflicts are detected. Recommended.
  • push: One-way. Local changes overwrite remote. Remote changes are ignored/overwritten. Good if you treat the VPS strictly as a build runner.
  • pull: One-way. Remote changes overwrite local.
  • none: Disabled. No files are synced. Useful if you’re just using sinc as a glorified ssh+tmux wrapper.

​
remoteBase

The parent directory on the VPS where your projects will be stored.
  • Example: If remoteBase is ~/workspace and you are in ~/projects/my-app locally, sinc will sync to ~/workspace/my-app remotely.

​
ignore

A global list of file patterns to ignore. Crucial for performance.
  • Why? Syncing node_modules (often 100k+ files) is slow and unnecessary if you run npm install on the VPS.
  • Syntax: Uses Mutagen ignore syntax (very similar to .gitignore).

​
agent

The command to run inside the remote tmux session.
  • opencode: Runs the OpenCode interpreter.
  • claude: Runs Anthropic’s Claude Code CLI.
  • Custom: You can theoretically put any command here (e.g., bash), but sinc is optimized for AI agents.

​
Per-Project Configuration

​
.syncignore

You can create a .syncignore file in the root of your project to add project-specific ignores. These are appended to the global ignore list. 
# .syncignore example
build/
tmp/
*.mp4
test-data/

​
Advanced: Multiple VPS Hosts?

Currently, sinc supports one global VPS configuration. If you need to switch between multiple VPSs, you can use environment variables or aliases to swap config files: 
# Alias for prod VPS
alias sinc-prod="cp ~/.config/sincronizado/prod.json ~/.config/sincronizado/config.json && sinc"
(Native multi-host support is planned for v3).

​
Optimization Tips

  1. Ignore Heavy Folders: Always ignore build artifacts (dist, build, .next) and dependency folders (node_modules, venv, target).
  2. Use Tailscale: Instead of public IPs, use Tailscale IPs. They are stable and don’t change if you restart your cloud instance (usually).
  3. SSH Config: Instead of putting complex SSH settings in sinc’s config, configure them in ~/.ssh/config and just use the Host alias in sinc.
# ~/.ssh/config
Host my-gpu-box
    HostName 123.45.67.89
    User ubuntu
    IdentityFile ~/.ssh/gpu_key
    ForwardAgent no
Then in sinc config, just set "hostname": "my-gpu-box".