Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Emanuele-web04/synara/llms.txt

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

The Synara workspace is the local directory where your code lives. You point Synara at a folder on your machine, and it becomes a project — a root that agents can browse, edit, and commit against. Everything Synara stores — threads, messages, checkpoints, attachments, logs — lives on your machine under a single configurable home directory. There is no Synara cloud account, no remote sync, and no external service that holds your repositories or chat history.

​
Home directory layout

Synara roots all of its stored state under a base directory. By default that directory is ~/.synara/. The userdata/ subdirectory (or dev/ when running from source in development mode) holds the live application state: 
~/.synara/
├── userdata/                  ← all application state
│   ├── state.sqlite           ← threads, messages, projects, events
│   ├── settings.json          ← server settings (ServerSettings shape)
│   ├── keybindings.json       ← custom keybinding overrides
│   ├── attachments/           ← uploaded image and selection attachments
│   ├── logs/
│   │   ├── server.log         ← server process log
│   │   ├── provider/
│   │   │   └── events.log     ← per-provider event log
│   │   └── terminals/         ← integrated terminal session logs
│   ├── secrets/               ← encrypted credential storage
│   └── server-runtime.json    ← ephemeral runtime state (port, pid)
└── worktrees/                 ← isolated Git worktree checkouts
    ├── <thread-id-a>/
    └── <thread-id-b>/
These paths are derived at startup from the deriveServerPaths function in config.ts: 
export interface ServerDerivedPaths {
  readonly stateDir: string;              // ~/.synara/userdata
  readonly dbPath: string;                // ~/.synara/userdata/state.sqlite
  readonly settingsPath: string;          // ~/.synara/userdata/settings.json
  readonly keybindingsConfigPath: string; // ~/.synara/userdata/keybindings.json
  readonly worktreesDir: string;          // ~/.synara/worktrees
  readonly attachmentsDir: string;        // ~/.synara/userdata/attachments
  readonly logsDir: string;               // ~/.synara/userdata/logs
  readonly serverLogPath: string;         // ~/.synara/userdata/logs/server.log
  readonly providerLogsDir: string;       // ~/.synara/userdata/logs/provider
  readonly providerEventLogPath: string;  // ~/.synara/userdata/logs/provider/events.log
  readonly terminalLogsDir: string;       // ~/.synara/userdata/logs/terminals
  readonly secretsDir: string;            // ~/.synara/userdata/secrets
  readonly serverRuntimeStatePath: string; // ~/.synara/userdata/server-runtime.json
  readonly anonymousIdPath: string;       // ~/.synara/userdata/anonymous-id
  readonly environmentIdPath: string;     // ~/.synara/userdata/environment-id
}
The SYNARA_HOME environment variable overrides the base directory when you need to run multiple isolated Synara instances or store data on a different volume.

​
What each path stores

state.sqlite

The primary SQLite database. Stores every project, thread, message, orchestration event, checkpoint, pinned message, thread marker, and proposed plan. This is the source of truth for your entire Synara history.

settings.json

Serialized ServerSettings — provider binary paths, custom model lists, the default thread environment mode, streaming preferences, and skill toggles. Edited through the Settings UI or directly on disk.

keybindings.json

User-defined keybinding overrides. Synara merges these on top of the built-in bindings at startup.

worktrees/

One subdirectory per worktree-mode thread. Each subdirectory is a git worktree add checkout of the thread’s branch. Synara reads the .git pointer file inside each worktree to resolve the originating repository root.

attachments/

Image files and assistant-selection snippets attached to chat messages. Referenced by ChatImageAttachment and ChatAssistantSelectionAttachment records in the database. Maximum attachment size per image is 10 MB.

logs/

Structured logs written by the server process (server.log), individual provider adapter event streams (provider/events.log), and per-session integrated terminal output (terminals/).

​
Projects

A project links Synara to a local repository or directory. You create one by pointing Synara at a workspaceRoot — an absolute path to the directory the agent should treat as its root. 
export const OrchestrationProject = Schema.Struct({
  id: ProjectId,
  kind: ProjectKind,          // "project" | "chat"
  title: TrimmedNonEmptyString,
  workspaceRoot: TrimmedNonEmptyString,  // absolute path on disk
  defaultModelSelection: Schema.NullOr(ModelSelection),
  scripts: Schema.Array(ProjectScript),
  isPinned: Schema.optional(Schema.Boolean), // defaults to false
  createdAt: IsoDateTime,
  updatedAt: IsoDateTime,
  deletedAt: Schema.NullOr(IsoDateTime),
});
Projects of kind "project" are full code repositories. Projects of kind "chat" are lightweight containers for conversational threads not tied to a codebase. Up to 3 projects can be pinned to the top of the sidebar at once.

​
Project scripts

Each project can store a set of runnable commands — build, test, lint, and so on — that appear as one-click buttons in the UI: 
export const ProjectScript = Schema.Struct({
  id: TrimmedNonEmptyString,
  name: TrimmedNonEmptyString,
  command: TrimmedNonEmptyString,
  icon: ProjectScriptIcon,           // "play" | "test" | "lint" | "configure" | "build" | "debug"
  runOnWorktreeCreate: Schema.Boolean,
});
When runOnWorktreeCreate is true, Synara runs the script automatically each time it provisions a new Git worktree for this project — useful for npm install, dependency bootstrapping, or any other setup that needs to happen before an agent starts.

​
Adding a project base directory

The addProjectBaseDirectory setting tells Synara which directory to suggest as the default root when you create a new project: 
export const ServerSettings = Schema.Struct({
  addProjectBaseDirectory: StringSetting, // defaults to ""
  // ...
});
Set this to your code directory (e.g. ~/code or ~/projects) and Synara will open the file picker there instead of your home folder.

​
File indexing and workspace entries

When an agent is running, Synara exposes the project’s file tree through a WorkspaceEntries service. The service supports:
  • browse — recursive directory listing with configurable depth
  • search — fuzzy-search for files by name within the workspace root
  • listDirectories — directory-only traversal for tree navigation
  • resolveFileBySuffix — resolve a bare filename or partial path to its unique absolute path within the project
Agents receive workspace entries as context so they can reference files without needing the user to copy-paste paths manually. The entry cache is invalidated on demand via invalidate(cwd) when the filesystem changes. 
export interface WorkspaceEntriesShape {
  readonly browse: (input: FilesystemBrowseInput) => Effect.Effect<...>;
  readonly search: (input: ProjectSearchEntriesInput) => Effect.Effect<...>;
  readonly listDirectories: (input: ProjectListDirectoriesInput) => Effect.Effect<...>;
  readonly resolveFileBySuffix: (input: { cwd: string; relativePath: string }) => Effect.Effect<...>;
  readonly invalidate: (cwd: string) => Effect.Effect<void>;
}
Search results are capped at 200 entries per query and 100 entries for local suffix searches. If the result set is truncated, the truncated: true flag is set in the response so the UI can prompt you to refine the query.

​
Privacy: all data stays local

Synara is a local-first workspace layer. It does not operate a cloud backend, does not sync your code or chat history to Synara servers, and does not require a Synara account. The only network traffic Synara initiates on your behalf is the traffic to the provider you chose — the same traffic you’d generate by running that provider’s CLI directly from your terminal. Your prompts, file snippets, and diffs go to the provider’s API endpoint (OpenAI, Anthropic, Google, etc.) and nowhere else.
Individual provider CLIs may send telemetry to their own services according to their own privacy policies. Review each provider’s documentation if you need to understand or restrict that traffic. Synara itself does not add additional telemetry hops.

​
Default chat workspace root

When you first open Synara without an explicit project configured, it suggests a default workspace directory derived from your system home folder: 
export function resolveDefaultChatWorkspaceRoot(input: {
  readonly homeDir: string;
  readonly platform?: NodeJS.Platform;
}): string {
  // Returns ~/Documents/Synara on macOS/Linux, or the Windows equivalent
}
This ~/Documents/Synara directory is used as the chatWorkspaceRoot — a safe default location for loosely-organized chat-mode projects that aren’t tied to an existing repository.

Settings reference

Full documentation of every field in settings.json, including provider binary paths, default thread mode, and streaming options.

Remote access

How to expose the Synara server on a local network and configure the host, port, and authToken fields.

Build docs developers (and LLMs) love

Get started for freeTalk to us