Docs / .smuggle config

The .smuggle config file

Every workspace has a single .smuggle file at its root, written by smuggle init/smuggle clone and read on every sync. It’s plain TOML, safe to open in a text editor — the generated file itself explains each field with comments, this page just goes a bit deeper.

What you can safely edit

Everything except workspace_id and remote, which identify this workspace to the server. Changing either turns this directory into (or breaks the link to) a different workspace — smuggle won’t stop you, but it’s almost never what you meant to do.

Fields

workspace_id string, generated

The server-assigned id for this workspace (e.g. wsp_a1b2c3d4). Don’t hand-edit this.

name string, optional

The human-readable name shown in the desktop app. Set automatically when you init a workspace, or when you clone one by owner/name slug. Cloning by raw workspace ID instead leaves this empty — smuggle doesn’t do a separate lookup just to fill it in.

remote string, generated

The backend this workspace syncs against. Don’t hand-edit this either, for the same reason as above.

ignore array of strings, default []

Patterns for files and folders smuggle should never sync, in .gitignore syntax. These apply on top of the built-in defaults, so you never need to repeat them:

.git/
node_modules/
dist/
build/
*.log

Notably absent: .env. Unlike git, smuggle syncs secret files by default (encrypted) instead of ignoring them — that’s the actual point of the tool. Add your own patterns to ignore for anything else you don’t want tracked at all, on any device.

local_only array of strings, default []

Patterns for files that stay on this device only: tracked locally, never uploaded, and never deleted here if the same path is removed on another device. Different from ignore — local-only files are still tracked, just not synced. Useful for machine-specific overrides, e.g. a secrets.local.env you deliberately don’t want following you to another machine.

[sync] table

debounce_ms (int, default 500) — milliseconds to wait after the last local file change before syncing. Batches rapid edits (a build writing many files at once, a large find-and-replace) into one sync instead of one per file. Raise it for a noisier workspace; lower it if you want changes to propagate faster and don’t mind more frequent syncs.

Full example

workspace_id = "wsp_a1b2c3d4"
name = "api-server"
remote = "https://smuggle.dev"

ignore = ["*.tmp", "coverage/"]
local_only = ["secrets.local.env"]

[sync]
debounce_ms = 500