User manual

One command, and the orchestrator is ready.

Connect GitLab, add a project, type sydla. This page shows what happens next, the few commands you use every day, and how to work with the orchestrator.

Manual plugin

plugin instructions below follow your choice

Start here

Quick start

Four steps to get started. Tick them as you go — this page remembers.

0/4

Sign in and connect GitLab
Google, GitHub or GitLab to sign in; then GitLab by OAuth, so the orchestrator can open merge requests and keep the board mirror up to date.
Open Setup
Add a project
Pick one of your GitLab projects or create one. Choose whether you also approve merge requests in GitLab — you can change it later.
Open Projects
Install and connect the CLI
Install the CLI, connect it to this server and install the Sydla plugin in Claude Code (or Codex, Antigravity). A local cluster also needs its HTTPS certificate.
Open Install & keys
Open the orchestrator, keep the supervisor running
sydla sets your project up and opens the Sydla orchestrator; the supervisor answers the Sydla chat and runs the work you launch, under its cap.
```
sydla
sydla account start
```

Launched work runs in Claude Code under the supervisor; the orchestrator also runs inside Codex and Antigravity when you open it there.

Under the hood

What happens when you type sydla

The first run signs in, clones and sets the project up, then opens the Sydla orchestrator; later runs open it directly.

first run, illustrated — your output names your account and project

$ sydla
✓ server Sydla — API v1
Sign in in your browser — check that the page shows the code  KQ7M-2PXD
✓ logged in as you — license key saved in ~/.config/sydla/sydla.env
Your projects: 1. acme/app
Project: 1
Which tool runs the orchestrator? 1. Claude Code
Tool: 1
Setting up Sydla in ~/code/app
✓ launcher .sydla/bin/sydla
✓ config .sydla/config.json (acme/app, reviewer you)
board ready: https://gitlab.com/acme/app/-/boards
✓ git HTTPS credentials for gitlab.com from Sydla
Sydla on acme/app with Claude Code
> /sydla:run
Checkout v2: 2 pieces wait for you — "Study the providers" (estimate 0.80 – 1.60 €)
and the scope gate of APP-12. I propose to launch the study first.
$ sydla account start
Starting account supervisor — chat and launched work, nothing runs on its own

Nothing secret lands in your repository. The license key is in ~/.config/sydla/sydla.env; GitLab and Slack credentials are fetched from the backend as needed.
Each piece of work is built in its own worktree under .sydla/work/, never in your checkout.
SYDLA.md, the project's playbook, is filled from your repository the first time. Read it, fix it, commit it.

On your machine

The supervisor

One background process answers the Sydla chat and runs the work a person launches in the dashboard. Nothing runs on its own.

Launched work: one piece at a time, run by the Sydla orchestrator (claude --agent sydla:orchestrator) under the cap set at launch, up to 55 minutes. A Stop in the dashboard stops it at its next step; the measured cost is recorded either way.
Your agents: the orchestrator hands steps to the agents you configure (Claude Code subagents, or those named in SYDLA.md § Agents) and always checks the work in a separate session.
Secrets: Sydla's MCP token is written to a private file (0600) for one request only; GitLab and Slack credentials are short-lived and fetched from the backend.

sydla account start    # start it in the background
sydla account status   # is it running?
sydla account stop     # stop it
tail -f ~/.config/sydla/account.log

The per-role Docker loop of CLI 0.7 and earlier is retired: the supervisor stops any project container left, and sydla uninstall removes the old images.

The orchestrator

How a piece of work runs

A person launches a piece of work from an initiative's plan of work, with its estimate and a cap. The Sydla orchestrator holds its whole context, runs only the steps it needs — itself, or through an agent you configured — and stops at every gate for you.

The orchestrator — Writes what the piece must achieve, for whom, and what is out, in a Sydla Docs page linked to the initiative. Open questions become questions for you, not guesses.

your partAnswer its questions when they come.

Before a costly step it compares what it spent with the cap; close to it, it stops and asks you with what is left and its estimate. At the end it records its tokens and cost against the piece. The GitLab board is kept up to date as a mirror — pm while the piece is framed, dev while it is built, qa while it is verified, rm while it ships — with a one-line trail in the issue; it is not how the work is coordinated.

Commands

I want to…

Pick what you want to do; copy the command.

Project (optional)

sydla

Sets the project up if needed, then opens your tool on the Sydla orchestrator: it says what waits and proposes what to do next.

Cheat sheet

Every day

sydla

Open the Sydla orchestrator on your project.

sydla board

The board mirror: pm 1 → dev 2 → qa 0 → rm 1.

sydla logs

Short activity. Add -f to follow or --raw for details.

sydla open board

The GitLab board in your browser.

Stop the supervisor with sydla account stop; launched work does not start again until you run sydla account start.

Collaboration

Working with the orchestrator

Give it work

Ask it to prepare an initiative (/sydla:run prepare <initiative>): it proposes the pieces of the plan of work, each with an estimate. You choose who does each piece, and launch.

Answer a decision

Questions and gates wait in the dashboard and the Sydla command bar, with the options, the one it recommends and what each costs. Agents cannot decide them.

Stop a piece

Stop it in the dashboard: it ends at its next step, and its measured cost is recorded.

Bring your own agents

Claude Code subagents in .claude/agents/, or agents named in SYDLA.md § Agents: the orchestrator hands them the steps their description fits.

Keep the Commands section of SYDLA.md real — install, tests, typecheck, audit: the build and the verification run them and paste their actual output.

Messaging

Slack

Connect Slack from Setup to link your workspace and its private #sydla-agents channel.

Only authorized people are listened to: whoever installed the app, plus the ids in slack.authorized.
Gates are passed in Sydla or on your code host, by a person — never by a chat message on an agent's behalf.

Control

Merge and release: your gates

verified independently
you pass the merge gate
merged
you pass the release gate
released

Merging and releasing are always gates a person passes; agents can request them, never decide them. Set per project in Projects.

Codex

Inside your coding tool

The Sydla plugin inside the selected tool: one orchestrator, plus login, status and init.

Use the login skill
Use the status skill
Use the init skill
Use the orchestrator skill

The orchestrator skill runs in this session; it asks you before anything paid and never launches work on its own.

Update the plugin

codex plugin marketplace upgrade sydla && codex plugin add sydla@sydla

Settings

Project configuration

.sydla/config.json is written at setup; shared settings come from your dashboard. Commit it with SYDLA.md so the whole team shares them.

Key	Default	Meaning
`release.ship_mode`	auto	auto or review — see Ship mode. Set from the dashboard.
`release.reviewers`	[]	GitLab usernames whose approval also ships, besides you.
`release.tag_prefix`	v	Prefix of the release tags.
`slack.authorized`	the installer	Slack ids Sydla listens to.
`gitlab.project / reviewer`	set at setup	The project, and you as its reviewer.

Keys left from the retired per-role loop (wip, parallel, pm_lenses, loop) are not used by the orchestrator.

Security

Installs, keys and revoking

Installs lists every machine and tool signed in — version, last seen, last project — and your connections. Revoke one: it stops at its next turn.
Install & keys makes a key by hand for a CI runner or server: SYDLA_CLOUD_URL and SYDLA_LICENSE_KEY in ~/.config/sydla/sydla.env, chmod 600.
Disconnecting GitLab stops the orchestrator at its next step.

Help

Troubleshooting

First reflex: sydla check

Docker is missing or the daemon is unavailable+
Start Docker on this Linux machine, then rerun the check. The CLI loop cannot run without Docker.
```
sydla check
```
Docker permission denied+
Your user must be allowed to talk to the Docker daemon. Fix Docker access, then run sydla again.
```
docker info
```
Claude Code is not signed in+
Open Claude Code and run /login; launched work runs with that sign-in.
```
claude
```
license key rejected / 401+
The key was revoked in Installs, or belongs to another server.
```
sydla init --relogin
```
GitLab is not connected for the agents+
Connect GitLab in step 1 of Setup.
```
sydla open setup
```
no project configured+
Add a project in the dashboard, then run sydla again.
```
sydla open projects
```
launched work does not start+
The supervisor runs launched work; start it with sydla account start. The dashboard says when no supervisor is connected.
```
sydla account status
```
a launched piece stopped+
The piece shows the agent's last message in the dashboard; it may have reached its cost cap or need a decision from you.
```
tail ~/.config/sydla/account.log
```
self-signed certificate / unable to verify+
Trust the CA of a self-hosted or local server.
```
sydla init --ca-file /absolute/path/to/ca.pem
```
Sydla plugin behaves like an older version+
Update the plugin in your tool (see Inside your coding tool), then restart the tool.
```
claude plugin update sydla@sydla
```
an old owenagents-loop container keeps running+
The per-role Docker loop is retired since CLI 0.8; sydla uninstall removes its container and images.
```
sydla docker stop
```
several projects here — name one+
logs and board use the last project started; name another with -p or as an argument.
```
sydla logs -p owner/project
```

Everything

Reference

sydla — every command and option

sydla                                   set the project up, open the Sydla orchestrator
owen …                                       the same command, shorter (owen board, owen logs…)
sydla start [project] [--tool claude|codex|agy] [--dir PATH]
sydla account start|status|stop [--tool …] [--chat claude|codex]
sydla project add <group/repository>
sydla docker stop|status|logs   (retired loop, cleanup only)
sydla service stop|status|logs  (legacy cleanup only)
sydla uninstall [--yes]
sydla logs [role] [-f] [-p project] [-n lines] [--raw]
sydla board [project]
sydla open [board|dashboard|projects|installs|setup|docs]
sydla init [--relogin] [--tools claude,codex,agy] [--yes] [--git-base GIT] [--host URL] [--ca-file PEM] [--no-plugins]
sydla check
sydla version

.sydla/bin/sydla — in your repository

owen status            account, plan, connections
owen board             tickets per column
owen queue <role>      a role's tickets, oldest first
owen show <iid>        a ticket and its whole thread
owen inbox <role>      unread notes addressed to a role
owen pull              shared config from Sydla
owen setup             labels and the "Sydla" board