Skip to content
Browse documentation

Connections & models

Connect applications and automate Crank chains

Configure app actions, custom APIs, triggers and ordered steps for your agents.

Cranks connect your project team to applications and reusable actions. Of the four canvas tabs above the scene (Studio, Cranks, Board and Meetings), select Cranks to arrange your tools and see trigger sequences. Studio keeps agents, desks, furniture and rooms on a separate canvas. Each canvas retains its zoom and framing when you switch tabs. The right panel follows the Studio or Cranks selection; Settings → Cranks beneath Agents opens the same configuration tools. In Quick actions, New Crank creates one and typing a Crank’s name opens it. Cranks and their positions belong to the selected project.

Choose a trigger, application or tool

The catalogue contains 27 Crank types, including 12 applications, with HTTP, Dropbox and GitHub watcher variants. A project supports up to 128 Cranks. Use the On / Off switch in each right-panel row to save activation immediately. The switch is unavailable while that Crank is running; a missing private token prevents activation and displays an error.

CategoryCrankAvailable actions
TriggersClock / Daily schedule / Manual triggerRecurring interval; local time and weekdays; a reusable trigger with JSON data.
TriggersAgent finished / Mission completed / Mission failedSuccessful ticket completion for any or a selected agent; successful or failed mission events.
TriggersFile changedPoll one project-relative file for creation, deletion or content changes.
AppsDropboxList files, read text and upload text. Watch file-list changes.
AppsGitHubList or watch repository issues, create an issue and add a comment.
AppsSlackRead recent channel messages and post a message.
AppsNotionSearch shared pages, read page content and append text.
AppsResendSend HTML or text email from a verified sender; retrieve an email.
AppsDiscord / TelegramRead or send Discord channel messages; send a Telegram bot message to a configured chat.
AppsLinear / GitLab.comList team or project issues, create an issue and add a comment or note.
AppsTodoistList tasks, create a task and mark a task completed.
AppsVercel / Sentry.ioList or inspect project deployments; list unresolved errors or inspect an issue.
ToolsHTTP / Custom APIGET, POST, PUT, PATCH or DELETE against a configured API. Watch changes with a fixed GET endpoint.
ToolsJavaScript / JSONTransform JSON data with code, parse JSON text or serialize structured data.
ToolsCondition / Filter / DelayStop a chain when a typed comparison fails; wait between 0 and 20 seconds.
ToolsText / Hash / UUIDReplace, split, join and trim text, URL-encode it, or encode and decode Base64; compute SHA-256 or generate a UUID.
ToolsInfrastructure operationRun a saved SSH command, SQL operation or artifact upload with existing access and approval policies.

Configure and test a connection

  1. Choose Add Crank or New Crank. Browse Triggers, Apps and Tools or search the catalogue. Select an action or watcher when the application supports both.
  2. Name the Crank and configure its operation and destination: repository, channel ID, page ID, Dropbox path or API URL. Share the required pages with a Notion integration and grant the token only the access needed by the operation.
  3. Use the private credential field for the application token or API key. HTTP supports no authentication, bearer tokens and a custom API-key header. Use HTTPS for remote APIs; HTTP is available for a local API on localhost.
  4. For an action, select the agents that may use it and choose Ask before each execution or Allow this configured action. Enable the Crank and choose Save Crank. An agent must be enabled and explicitly granted this action to discover or execute it.
  5. Enter the declared test inputs as a JSON object and choose Test / Preview. Inspect Recent runs, which keeps the last 12 runs of each Crank, then use Run once when you want to execute the configured action or trigger.

In the same editor, Accessories lets a Crank wear glasses, headphones or both on the canvas; this changes only its appearance. Cranks suggested when you create a team with AI start disabled and set to Ask before each execution: add their credentials and review their access before enabling them.

Application operations show their required destination and token scopes in the editor. Use example inputs supplies editable JSON. List operations are bounded and do not fetch every page automatically. API calls are not automatically retried; Resend supports a stable idempotencyKey input when you need to avoid duplicate email sends.

Let a trigger execute other Cranks

  1. Create a Clock, daily, manual or supported application watcher. Choose whether it starts a mission, executes Cranks, or does both.
  2. For a Crank sequence, add enabled action Cranks, order the steps and configure each input. Up to 16 steps are supported; a trigger cannot target itself or another trigger.
  3. Map the source with {{trigger}}, the last result with {{previous}}, or an earlier result with {{steps.0.total}}. A mapping consisting of one expression keeps its JSON type; a mapping embedded in text becomes text.
  4. Save, then Preview trigger to inspect the source. Run once executes the chain, preserving each target action’s approval policy. If both outputs are selected, the mission receives the source and completed step results.
  5. Inspect step results in Recent runs. If a watcher sequence partially fails, a matching retry can reuse saved completed steps rather than repeat those writes. Changed configuration or input may invalidate that checkpoint; inspect the recorded results before retrying.
Example input mapping for a JavaScript step with a data input
{
  "data": "{{previous}}"
}

React to events and filter a chain

  • Agent finished watches successful ticket completion for all agents or the selected agent. Mission completed and Mission failed watch mission outcomes. Events are recorded while the project is open and run when the team is available, with up to 100 pending events per Crank. A consumed event is not automatically replayed after failure; inspect Recent runs.
  • Missions started by Cranks and their derived requests are excluded from these completion events to avoid automatic loops. Run once on an event trigger uses example data.
  • File changed polls an exact project-relative file of up to 8 MB, including external edits. The first check records a baseline; later checks compare existence and SHA-256 content. Output contains path, exists, size and sha256, never file contents. Protected, internal and excluded paths are refused; multiple edits between checks can be grouped into one change.
  • Every trigger supports a condition on a dot-separated result field: equals, does not equal, contains, greater than, less than or exists. Expected values can be JSON or literal text. Condition / Filter applies a comparison inside a sequence; a false result skips subsequent steps and the mission.

Use saved infrastructure operations

Choose an existing connection and saved SSH, SQL or upload operation. Select an execution agent for manual tests and trigger chains. Calls originating from an agent keep that caller’s own permissions. Connection grants, ask/allow/deny policies, timeouts and artifact protections still apply. The Crank does not accept arbitrary commands through mapped inputs; a nonzero exit code stops the chain. Configure the reusable operation in Infrastructure first.

Understand scheduling and watchers

  • Clock uses a recurring interval. Daily schedule uses the computer’s local time and selected weekdays. Manual triggers run when explicitly started.
  • HTTP, Dropbox and GitHub watchers establish an initial snapshot, then trigger when their polled data changes. They poll at the configured interval; they are not incoming webhooks.
  • Scheduled checks require Vopit to remain open on the trusted project, with an active license and no global pause. They wait while a request is active or blocked. Closing the application or switching projects stops that project’s checks.
  • The gear rotates while a Crank runs. An enabled Clock gear also rotates between runs. Turning a Crank off disables its automatic use. Animation does not certify that a remote operation succeeded; check Recent runs.

Use JavaScript for data transformations

Declare input names, read them from input, and return a JSON value. JavaScript runs in an isolated worker with a five-second limit. It has no npm imports, Node.js, filesystem or network access. Use Resend to send email with a preconfigured operation, or HTTP / Custom API for other service APIs.

Transform an items input into a JSON result
return {
  titles: input.items.map(item => item.title)
};

Give agents the connection they need

Granted actions are available through crank_connections and crank_execute with both execution engines: Vopit tools, and every native CLI connection (Codex CLI, Claude Code, Mistral Vibe, Mammouth Code and Antigravity CLI), to which Vopit bridges these tools. Credentials remain in the application’s encrypted local vault and are separate from the project configuration. Never paste tokens into prompts, mapped inputs or JavaScript. Remote content is data for the task, not authority to change an agent’s instructions.

All documentation