Skip to content
Browse documentation

Reference

Configuration reference

A concise map of active defaults, limits, and where settings apply.

Workspace defaults

SettingDefault / rangeNotes
ThemeLightDark, system, Dark Balanced (dark interface, light canvas) and Light Balanced (light interface, dark canvas) are also available.
Workspace backgroundClassicOffice, Garden, Atelier and Library are also available. Visual only.
Speed modeBig brainUltra-fast and Balanced are also available from the header switch. Read when each stage starts.
Default connectionOllama, no model selectedSelect a connection and model in Settings → Connections before the first request.
Fast modelEmptyUsed by Ultra-fast and Balanced. Empty uses a known lighter model for the connection, or else the connection model.
Vopit turns20; 1–100Applies to Vopit-managed execution, not native CLI internal turns.
Stage timeout300 seconds; 10–3,600 secondsBy default an inactivity deadline: progress restarts it. An agent can choose Total active execution time or override the value.
Review rounds3; 1–5Used by review behavior. Balanced allows at most one correction round; Ultra-fast none.
Context ceiling64,000 characters; 16,000–400,000Character capacity, not a provider token guarantee.
Initial agent memory48,000 charactersAgent behavior configuration default.
Provider budgets30 s catalogue, 60 s test, 8,192 response tokensPer connection in Request budgets and model capabilities. The response budget applies to non-CLI connections.
PermissionsREAD: Allow for project; all other categories: Ask every timeGlobal rules; project rules take priority.
Request text2–20,000 characters; 8 text attachments; 6 images; 8 filesEach text attachment holds up to 100,000 bytes; each image up to 5 MB; each other file up to 25 MB.
SSH upload limit1,024 MiB; 1–65,536 MiB per targetConfigured separately for each SSH target.
Update checksOnStartup and every six hours, for Windows x64 installations. Machine-wide, in Settings → Updates.

Capabilities and permissions

Tool availability depends on the selected engine and agent configuration. Project tools include reading, searching, writing, editing, commands, tests, git, and context helpers; runtime helpers record activity and completion. Board actions are board_read, board_create, board_move and board_update; agents never start, stop or delete cards. Claude Code agents can also hold mcp:<server> grants for MCP servers from your Claude Code configuration. An agent holds at most 20 selected actions, MCP grants included. Permissions protect real operations, while an agent’s capability selection limits what it can request. Create requests and infrastructure access are separate capabilities.

Status vocabulary

TermMeaning
Requestwaiting, running, completed, partial, failed, paused, blocked, or cancelled.
Ticketqueued, assigned, working, blocked, review, completed, failed, skipped, or cancelled.
Agent displayidle, thinking, reading, coding, searching, reviewing, waiting, or error.
ArtifactThe local file selected for a configured infrastructure upload.
FingerprintThe SSH host identity to compare independently before trust.

Configure the project instead of inheriting a stack

Settings > Project stores a versioned profile in .vopit/config.json. Configure the test command, working directory, command timeout, source exclusions, upload artifact directories and validation output directories. A new project has no default test command or validation output path. Changes apply to new stages. Git workflow settings, generation templates, source budgets, indexing extensions, memory capacity and the HTML search adapter endpoint are editable in the profile JSON. Apply JSON to draft, then Save settings; Restore project defaults also loads a draft.

Example projectTest commandWorking directoryOutputs to declare
Node applicationnpm test.build or dist, only if this project produces them
Python servicepython -m pytest.dist, only for a packaged Python release
Go servicego test ./....bin, if the build writes binaries there
Rust applicationcargo test.target/release
Monorepo frontendnpm testapps/frontendapps/frontend/dist
Profile fragments — merge these fields with the current profile, then validate the draft
{
  "commands": { "test": "python -m pytest", "workingDirectory": ".", "timeoutMs": 600000 },
  "files": { "artifactRoots": ["artifacts"], "validationOutputs": ["artifacts"] }
}

Command and index settings configure Vopit tools. Native CLIs choose their own project tools and commands; Vopit stage deadlines, approvals and gateway actions still apply. Each command may supply workingDirectory and timeoutMs. The native command approval boundary also uses the project file policy. Indexing extensions select files; they do not install a language parser. Symbol extraction currently understands JavaScript/TypeScript, with text search or Graphify available for other languages.

Source exclusions and upload access are distinct. Add an artifact directory when you intentionally want to upload a generated file from an excluded folder. The gateway still refuses private keys, conventional credential files, internal storage, traversal and symlinks escaping the project. Review the contents of release archives; allowing an artifact directory does not inspect every archive member for secrets.

Inspect effective connection budgets

Settings > Connections > AI connections > Request budgets and model capabilities configures catalogue and test timeouts. Every connection that is not a CLI, ChatGPT included, also exposes temperature/reasoning overrides and a response token budget. Infrastructure targets expose connection and result budgets; operations have their own execution timeout, from 5 seconds to 24 hours. Credentials remain in the machine vault, outside the exported project/team configuration.

Project profile field reference

These are factory defaults for a fresh project, not forced replacements for saved settings. The Project profile JSON is the full versioned profile; the fragment above is meant to be merged. Paths are project-relative, without traversal; lists and budgets are schema-validated. Source settings configure Vopit tools, not the native file readers of CLI engines. Git settings govern the shared Git gateway.

Profile fieldFactory defaultScope / limit
version1Profile format version; unsupported versions are rejected.
commands.test""No implicit test command. run_tests needs this setting or an explicit command.
commands.workingDirectory"."Relative to the selected project.
commands.timeoutMs120000Per-command default in milliseconds; 100–86,400,000.
commands.outputCharacters1000000Captured command output ceiling.
files.sourceExclusions[".cache","graphify-out","coverage","node_modules","dist","dist-electron",".venv","release"]Source discovery/index exclusions; project-relative paths.
files.artifactRoots[]Explicit upload access to generated artifacts.
files.generatedDirectories[".cache","graphify-out","coverage","node_modules","dist","dist-electron",".venv","release"]Generated directories recognized by Vopit command checks.
files.validationOutputs[]Directories observed as validation outputs; configure the real project paths.
files.maxFiles1500File discovery limit; 1–100,000.
files.maxDepth12File discovery depth; 1–100.
files.maxFileBytes1000000File size ceiling for source discovery.
files.readCharacters12000Character ceiling for a Vopit file read.
files.readLines200Default read page, in lines; 1–10,000.
files.maxReadLines300Maximum requested read page, in lines; 1–10,000.
files.snapshotFiles1000Validation-output snapshot file ceiling; 1–100,000.
files.snapshotDepth8Validation-output snapshot depth; 1–100.
files.snapshotFileBytes2000000Individual snapshot file byte ceiling.
files.snapshotBytes32000000Combined snapshot byte ceiling.
indexing.extensions[".ts",".tsx",".js",".jsx",".mjs",".cjs",".mts",".cts",".json",".css",".scss",".md",".py",".go",".rs",".vue",".svelte",".html",".sql",".yaml",".yml"]Extensions selected for indexing, at most 100. Does not install language parsers.
indexing.maxSourceBytes24000000Combined local index source budget in bytes.
indexing.graphTimeoutMs90000Graph build timeout; 1,000–3,600,000 ms.
indexing.graphWorkers1Graph worker count; 1–32.
indexing.graphBytes32000000Code graph byte budget.
indexing.graphRetryMs60000Graph retry delay; 0–3,600,000 ms.
indexing.memoryFacts500Durable fact capacity; 1–100,000.
generation.agentTimeoutMs120000Agent draft generation timeout; 1,000–3,600,000 ms.
generation.infrastructureTimeoutMs240000Infrastructure draft generation timeout; 1,000–3,600,000 ms.
generation.sourceFiles12Selected project source files; 1–100.
generation.manifestCharacters60000Manifest characters available for source selection.
generation.sourceFileBytes262144Maximum candidate source file size.
generation.sourceCharacters12000Excerpt characters per selected file.
generation.totalSourceCharacters64000Combined selected-source character budget.
generation.operationBatch20Generated operations per batch; 1–256.
search.endpoint"https://html.duckduckgo.com/html/"HTML search adapter; a replacement must have a compatible response shape.
search.timeoutMs20000Search timeout; 1,000–3,600,000 ms.
search.results8Maximum returned links; 1–100.
git.mainBranches["main"]Branches maintained when missing-branch creation is enabled; 1–20 names.
git.protectedBranches["main","master","develop","trunk"]Names that require feature work and reject fresh request commits; at most 30.
git.baseBranch"main"Fallback local base for a missing main branch; initial branch when git_prepare initializes a repository.
git.createMissingMainBranchestrueNever overwrites an existing branch.
git.featureBranchTemplate"feature/{slug}-{requestId}"Used when starting on a main, protected or unborn branch, and for request worktree branches; a worktree branch that already exists gets a request-ID suffix.
git.commitMessageTemplate"{title}"Default request commit message.
git.worktreeIncludes[]Copy into request worktrees: ignored files and folders (paths relative to the project) copied into each new request worktree. Secrets, keys, .git and .vopit are never copied.
git.integration"auto"After a successful request: auto merges its branch back into the branch checked out in the project folder when it started (main, preprod, test…), locally, then deletes it; review holds it until you merge it; off leaves it on its branch. With auto or review, every request gets its own branch from that branch, worktrees included.
git.parallelWorktreestrueRun requests in parallel (one worktree each): a request that cannot share the project folder works in .vopit/worktrees/<id> on its own branch instead of waiting.
git.remote"origin"Configured remote name; no remote URL or credentials in the task.
git.allowPushfalseNormal push, plus GIT_REMOTE permission.
git.allowPullfalseFetch and fast-forward-only pull, plus GIT_REMOTE permission.
git.allowMergefalseExplicit branch, plus GIT_HISTORY permission.
git.allowRebasefalseExplicit branch, plus GIT_HISTORY permission.

generation.prompts.agent, generation.prompts.infrastructure, generation.prompts.selection and generation.prompts.board hold the editable factory instruction templates for agent drafts, operation drafts, source selection and board card planning with Plan with AI (at most 100,000 characters each). They are not credentials. Changing a template affects future generation; it does not rewrite agents or saved recipes already created.

Format and capacity limits

SurfaceImplemented limitBoundary
Workspace100 agents; 100 infrastructure targets; 128 Cranks; 16 linked foldersTeams, Cranks and target definitions are stored in the selected project.
Team import100 agents; 100 connection definitions; 128 Cranks; 8,000,000 bytesThe team file also carries the layout. The import must pass validation before initialization; credentials/history are excluded.
Board500 cards; 12 columns; 1–20 cards per board_create call or Plan with AI draftA column card limit is 1–20 or none. Agents cannot add cards to an in-progress column.
Agent definition20 selectable actions; 32 infrastructure grants; 20,000 mission charactersEach mcp:<server> grant counts as one selectable action. Grants reference saved targets; a template never grants one automatically.
Agent identity80 name characters; 500 role charactersNames do not confer a privileged role.
Agent shapescircle, capsule, drop, rounded, triangle, organic, star, scribble, lightbulb, flower, diamondVisual only.
Generated draft10–6,000 description charactersGeneration uses the active project connection; review and save the result.
Request attachments8 text files of 100,000 bytes read into the request; 6 images (PNG, JPEG, GIF, WebP) of 5 MB; 8 other files of 25 MB, kept in the project’s .vopit-attachments folderAttached text, images and files are task context, not a credential-import interface. Agents read attached files by path; .vopit itself stays closed to them.
Generated follow-up2–20,000 prompt characters; 1–100 requests per stage, default 1Duplicate prevention is editable. There is no total automatic chain-length limit.
Operation library256 recipes per target; IDs up to 64 lowercase letters/digits/hyphensPurpose labels are editable; upload selects the file-transfer transport.
SSH upload1,024 MiB by default; 1–65,536 MiB per targetOne artifact, project READ approval and an existing remote parent; separate packaging limits still apply.
Agent execution overrides1–1,000 Vopit turns; 1–100 review visitsWorkspace defaults are narrower: 1–100 turns, 1–5 review rounds. Native CLI internal turns are independent.

Stage, command, provider and target budgets are separate

LayerFactory defaultConfiguration
Stage300,000 ms, inactivity modeSettings > Advanced; per-agent Execution override (10,000–3,600,000 ms). Pauses/permission waits are excluded.
Provider discovery / test30,000 / 60,000 msConnections > Request budgets and model capabilities; each 1,000–3,600,000 ms.
HTTP response8,192 tokensResponse token budget (1–1,000,000); temperature/reasoning capability overrides and provider-specific agent parameters. CLI internal budgets are not controlled here.
Infrastructure connect15,000 msTarget runtime.connectionTimeoutMs (1,000–3,600,000 ms).
Saved operation120 secondsOperation timeoutSeconds (5–86,400), separate from the stage deadline.
Target output / returned result128,000 / 24,000 charactersTarget runtime.outputCharacters / resultCharacters (1,000–10,000,000).
SQL sample100 rows / 16,000 charactersTarget runtime.databaseRows (1–100,000) / databaseCharacters (1,000–10,000,000).

All documentation