Add a project

A project is one git repository on one execution host. Everything Otomat launches for it — runs, worktrees, agents, presets — belongs to that host's daemon.

Add a local project

1. Open the project switcher at the top of the sidebar and choose Add project.
2. Enter the Repository path — the absolute path of an existing git clone — or click Browse… to pick the folder.
3. Add project. The project appears in the switcher and becomes the active one.

Otomat registers the path; it does not copy or move the repository. Runs work in workspaces of their own.

Per-project settings

Settings → Project → This project holds what belongs to that repository:

• Worktree init commands — shell lines run in every new worktree before an agent starts (pnpm install, pnpm build, …). They run on the host that owns the project.
• Linear sources — the team and Linear project the issues are mirrored from (see below).
• Run health check — see Project readiness.

Settings → Project → Workspaces lists the branches and worktrees the project holds, and Agents / Skills the profiles and skills scoped to this project alone.

Connect Linear

Local issues need no integration: New issue in the Issues view creates one. To work from Linear:

1. Settings → All hosts → Integrations → Linear: Add Linear workspace with a name and a Personal API key. Disconnecting a workspace is the only action that removes the key (stored as described under Credentials), and it lists the projects that lose their mapping first.
2. Settings → Project → This project → Linear sources: pick the Linear connection, then the Linear team and, optionally, the Linear project whose issues this Otomat project mirrors. A project maps to one connection; two projects may share it.
3. In the same card, map the workflow states Otomat writes back: Run started (the state an issue enters when a run is created on it) and Pull request merged. An unmapped phase writes nothing to Linear.

Issues sync when you open the project and when the window comes back to the foreground — unless they were synced less than a minute ago — and when you click Refresh issues in the Issues view; there are no webhooks. Beyond those two transitions, Otomat writes to Linear only what you publish yourself from the issue page: Publish to Linear for edited fields, a status change, a Comment, or a pull-request link.

Add a VPS as an execution host

The daemon can run on a Linux server you own while the desktop app stays the user interface. Repositories, worktrees, the database and the agent CLIs then live on the server; the app reaches them through an SSH tunnel and never exposes a port.

On the server you need: Linux with bash, Node.js 22 or newer on the login shell's PATH, git, an authenticated gh (it also downloads the daemon build), and the claude / codex CLIs you intend to use, signed in.

On your Mac:

1. Make sure ssh <alias> works from a terminal without any prompt — Otomat connects with the system ssh in batch mode, using a Host alias from ~/.ssh/config. Accept the host key once from the terminal.
2. Settings → All hosts → Execution hosts: enter the Remote host SSH alias and Save alias. Nothing else is stored (see Credentials).
3. Otomat starts the daemon on the host if it is absent, installs the exact daemon build this app expects when the one running differs (waiting for in-flight runs to finish first, and backing up the database before the swap), and opens the tunnel. The sidebar shows the progress; a first connection takes about half a minute.
4. Add project again, this time with Host set to the alias. Otomat lists the git repositories it finds under the server's home directory; pick one or type the path.

The host follows the project: choosing a VPS project in the switcher points the whole cockpit at that daemon. Local and remote daemons keep separate databases and nothing is synchronised between them. Closing the app closes the tunnel but leaves the remote daemon and its runs working; the next connection finds them again. Remove host forgets the alias — the daemon and its data stay on the server.

Details on the host layout and manual deployment are in the remote execution host reference.