> ## Documentation Index
> Fetch the complete documentation index at: https://sincronizado.micr.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Complete reference for configuring sincronizado.

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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

| Option     | Type     | Description                                                                                                                    |
| :--------- | :------- | :----------------------------------------------------------------------------------------------------------------------------- |
| `hostname` | `string` | **Required**. The IP address or domain name of your VPS.                                                                       |
| `user`     | `string` | The SSH username. Defaults to `ubuntu`. Common alternatives: `root`, `debian`, `ec2-user`.                                     |
| `port`     | `number` | The SSH port. Defaults to `22`.                                                                                                |
| `keyPath`  | `string` | Path 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](https://mutagen.io/documentation/synchronization/ignores) (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.

```gitignore theme={"theme":{"light":"github-light","dark":"github-dark"}}
# .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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
# ~/.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"`.