Guides

Set up Dittoly, step by step

Each guide says what a feature is, when to use it and exactly what to click. For every detail, follow Full reference at the end of a guide.

Setup

Install on your computer

Run Dittoly on your own machine. You are the only user, and admin and approver at once.

Use it when you want to try Dittoly, or automate your own work.

  1. Install Node.js 26.
  2. Get the code and build it: git clone https://github.com/SudoDevStudio/dittoly dittoly && cd dittoly, then npm ci && npm run build.
  3. Start it: node bin/dittoly.mjs.
  4. Open the sign-in link it prints (http://127.0.0.1:8484).

Tip Your data and the key to your credentials live in ~/.dittoly. Back them up with node bin/dittoly.mjs backup; start afresh with node bin/dittoly.mjs cleanup (keeps your credentials).

Full reference →

Run it on a server for a team

One shared Dittoly for your team, with Docker: Dittoly, PostgreSQL and RabbitMQ. People sign in with your single sign-on.

Use it when several people will build, approve and run Flows together.

  1. Prepare a Linux host with Docker Engine 28 or later and the Compose plugin. Recommended: 4 vCPU and 8 GB of memory.
  2. Get the code and copy the settings: git clone https://github.com/SudoDevStudio/dittoly.git dittoly, cd dittoly, cp .env.example .env.
  3. In .env, set DITTOLY_MASTER_KEY (openssl rand -base64 32), DITTOLY_PUBLIC_URL, your identity provider (DITTOLY_OIDC_ISSUER, client id and secret) and your AI provider.
  4. In docker-compose.yml, set DITTOLY_MODE: shared and bind the port to 127.0.0.1 behind your HTTPS reverse proxy.
  5. Start it: docker compose up -d --build, then create the first admin: docker compose exec dittoly node dist/src/cli/bootstrap.js admin.
  6. Give people roles in Members & Access after they first sign in: member, approver or admin.

Tip Back up the master key apart from the database and never change it by hand: it encrypts every stored credential.

Full reference →

Connect your AI

The AI drafts modules and Flows from plain words. It uses your organization's own key, and data goes only to the provider you choose.

Use it when you want to describe modules and Flows instead of building them by hand. It is optional.

  1. Choose a provider: anthropic, openai or ollama (on your own computer also claude-cli or codex-cli).
  2. Set DITTOLY_AI_PROVIDER and its key (for example ANTHROPIC_API_KEY) where Dittoly runs, or start the local app with --ai <provider>.
  3. Restart Dittoly.

Tip Without an AI you can still build Flows on the visual canvas and take modules from the marketplace.

Full reference →

Store your credentials

Each person stores their own app tokens once. A run you start uses your access and nobody else's.

Use it when a module you will use needs a token, such as a Slack or GitLab token.

  1. Open My credentials.
  2. Under Needed by approved modules, find the app. It says exactly what to paste, for example "Slack token with chat:write".
  3. Click Add, paste the token and Save.

Tip Tokens are encrypted and never shown again, not even to you. A team admin can also store one shared service account for an app on the team's page, under Teams.

Full reference →

Modules and Flows

Create a module

A module is how Dittoly talks to one app, for example posting to Slack. It may only reach the hosts it declares.

Use it when a Flow needs an app that no approved module covers yet.

  1. Open Modules and describe what it should do, for example "post a message to a Slack channel". You can add the API's docs or spec as a source.
  2. Answer any questions the AI asks. It drafts the module in TypeScript and tests it in a sandbox.
  3. If something is off, ask for a change; each revision is a new version.
  4. Send it for review. An admin sees the hosts it may reach, which actions change data and whose token it uses, then clicks Approve.

Tip You can also take a module from the Marketplace, or import the tools of an MCP server. Some modules need an organization setting, such as your Jira site; the module page asks for it.

Full reference →

Create a Flow

A Flow is a process across your apps: steps that call module actions, ask people, wait or check pages.

Use it when you want something to happen the same way every time.

  1. Open Flows and describe it, for example "when a release is approved, merge the ready merge requests and tell the channel". The AI drafts it from approved modules.
  2. Read What it does: every step that changes data is marked.
  3. Click Create Flow to save a draft.
  4. An approver clicks Approve this version. On a shared server nobody approves their own work.

Tip Any later change makes a new version that needs approval again, so what runs is always what someone approved.

Full reference →

Build a Flow visually

Build or change a Flow by hand on a canvas, without an AI.

Use it when you know the steps, or no AI is connected.

  1. Open Flows → Build a Flow visually, or Edit visually on a Flow you own.
  2. Drag actions from the Palette on the left onto the canvas (or press +). Sign-off and Wait are there too.
  3. Select a step and fill in its form on the right. Use… fills a field from the run form or from an earlier step's output.
  4. Add the Run form inputs people fill in, then save. The draft still needs an approver.

Tip Problems are shown under the editor before you save, the same checks as any other Flow.

Full reference →

Connect Flows into a Super Flow

A Super Flow runs other approved Flows, in stages. The Flows in one stage run at the same time.

Use it when a bigger process is made of Flows you already have.

  1. Open Super Flows in the sidebar.
  2. Pick approved Flows and put them in stages. Stages run one after another.
  3. Each child's inputs start as Super Flow inputs of the same name, so a shared value is asked once. Or use a result from an earlier stage.
  4. Save and approve it like any Flow.

Tip Or let the AI Flow Synthesizer do it: "run Ticket QA, then notify Slack and Teams together".

Full reference →

Run a Flow

Run it by hand, on a schedule, from another system, or for each new item.

Use it when the Flow is approved.

  1. On the Flow's page, read Before you run: what each step changes and whose access it uses.
  2. Fill in the run form and try a Dry run first: it reads for real and skips sign-offs and changes. Then Run now.
  3. To repeat it, use Schedules → Add schedule (a cron time and time zone).
  4. To start it from CI or a script, use Flow URLs → Create URL; to start it for each new issue, email or file, add a Watch.

Tip The run page's Result panel says in plain words how the run ended, or what it is waiting for.

Full reference →

AI and apps

Use Flows from your AI assistant

Claude, ChatGPT, Copilot and other assistants that speak MCP can run your approved Flows as tools, as you, with your access.

Use it when you want an assistant to do a task the same way every time, without spending tokens on it again.

  1. On the Flow's page, click Offer to AI assistants.
  2. On the AI Agents page, make an agent: a name, the Flows it may use and how long it works. Copy its token; it is shown once.
  3. Connect the assistant to https://<your Dittoly>/mcp with the header Authorization: Bearer <token>.

Tip Just did a task with your assistant? Ask it to "save this as a Flow". It drafts the Flow, and people approve it as usual.

Full reference →

Build an app for your team

An app is a set of pages over your team's approved Flows: forms, tables, cards, an inbox and a runs list.

Use it when your team should run Flows from simple pages, with the team's shared keys.

  1. Open Apps and pick the team's approved Flows the app runs.
  2. Make the layout: leave the description empty for a page per Flow, or describe it ("an order desk with product cards and a Buy button") and the AI drafts the pages.
  3. Edit titles, pages, colours and fonts; a sketch follows every change.
  4. Save, and an approver approves the version. Open app opens it for the team.

Tip Runs from an app use the team's shared credentials, so everyone gets the same results whoever clicks.

Full reference →

Turn a PDF into Flows

Upload a document describing what you want automated. Dittoly breaks it down and drafts the modules and Flows.

Use it when your process is already written down.

  1. Open Plans from PDF and upload the PDF (text, not scanned images).
  2. Answer the questions the AI asks (which chat tool, who approves, how often...), or let it decide.
  3. New modules go to an admin for review. Each Flow is drafted once its modules are approved.
  4. Approve the drafted Flows as usual.

Tip The AI reuses approved modules wherever they already cover a step.

Full reference →

Keep everything in git

Dittoly writes what people approve to a git repository, and changes merged in git come back as versions that wait for approval.

Use it when you want reviews, history and rollbacks the way the rest of your code has them.

  1. An admin connects a repository in Members & Access → Git sync (GitHub, GitLab or any git over HTTPS), with a token that may write.
  2. Click Export everything approved now for the first sync. Modules arrive as TypeScript (module.ts), Flows and apps as JSON.
  3. From then on, each approval opens a pull request. Merge it.
  4. Edit in git and merge: Dittoly reads the branch every 10 minutes and the change waits for approval.

Tip In the repository, npm run check type-checks the modules and npm run build compiles them the way Dittoly does.

Full reference →

Export an app that runs on its own

Package approved Flows as a TypeScript project with no database of its own and no connection back to Dittoly. Flows that wait for a person keep their runs in a Redis or Postgres you point it at; the rest run in memory.

Use it when a Flow should run somewhere else: as an API, a small web app or your own frontend.

  1. Open Export an app (under Share; admins and approvers).
  2. Choose the kind: Runner, Headless API, API + simple UI, or Your framework (React, Next.js, Angular, Astro or Vue).
  3. For each Flow, choose who may start it: holders of the app's API token, or anyone.
  4. Download the project and run it; it is configured by environment variables.

Tip An app built under Apps exports with its own layout and look: use Export on its page.

Full reference →

Admin and safety

Set approval rules and policies

Rules decide who must approve what, when runs may start and where modules may connect.

Use it when your organization needs a second approver, working hours or limits.

  1. Open Members & Access (admins) and add a rule.
  2. Pick a kind: several approvers for Flows that change data, allowed hosts for modules, runs only in working hours, a daily run limit per person, only a Flow's own team approves it, or reminders for waiting approvals.
  3. Save. A refused action names the rule that stopped it.

Tip Going on holiday? Pick a stand-in in My credentials → When I'm away.

Full reference →

Audit log and SIEM

Every action is in a hash-chained audit log. Dittoly can stream it, as it happens, to your SIEM.

Use it when security wants every change and run in Splunk, Datadog or another log platform.

  1. Open Members & Access → Stream audit events to a SIEM (organization admins) and add a stream: Splunk, Datadog, any HTTPS collector, syslog over TLS or OpenTelemetry.
  2. Start with new events from now on, or the whole history.
  3. Click Send a test event to check the address and credentials.

Tip Run inputs, outputs, credentials and AI prompts are never sent: they are not in the audit log either.

Full reference →

Single sign-on and SCIM

People sign in with your identity provider, which can also create, update and offboard them, and turn groups into teams.

Use it when you use Okta or Microsoft Entra ID and want access managed in one place.

  1. Set up sign-in with your provider when you install the server (OIDC).
  2. Open Members & Access → Provisioning (SCIM) and copy the SCIM base URL and a token.
  3. In Okta or Entra, turn on provisioning with that URL and token, then assign people and push the groups that should be teams.

Tip The guide has click-by-click steps for Okta and Microsoft Entra ID.

Full reference →

Undo what a run changed

Reverse what a Flow run or an AI agent changed, after an approver signs off.

Use it when an announcement went out a day early, or issues landed in the wrong project.

  1. Open the run (or the agent's calls on the AI Agents page) and choose what to reverse: by default every change that can still be reversed.
  2. An approver signs off the request in their inbox. On a shared server nobody signs off their own.
  3. The changes are reversed newest first, with the same person's access.

Tip Only changes whose module declares how to reverse them can be undone; an email sent cannot.

Full reference →

Build and test code on another machine

App and fix steps build, test and run your project's code on a separate code runner, so it never runs where Dittoly and its database are.

Use it when you run fix or app steps and want project code kept off the Dittoly server.

  1. On the runner machine (Linux, Docker, Node.js 26): clone Dittoly, run npm ci, and make a token with openssl rand -base64 32.
  2. In its .env.runner, set DITTOLY_RUNNER_TOKEN and your TLS certificate and key, then start it with npm run runner.
  3. In Dittoly's .env, set DITTOLY_CODE_RUNNER=remote, DITTOLY_RUNNER_URL and the same token, then restart Dittoly.
  4. Allow the runner's port only from the Dittoly machine.

Tip To go back, set DITTOLY_CODE_RUNNER=local. Nothing else changes: the same Flows, sandboxes, destinations and evidence.

Full reference →