DevAgentForce documentation

Install, run, operate and troubleshoot a self-hosted DevAgentForce. Inside the dashboard, the Ask Agent panel answers the same questions about the page you are on.

What it is

DevAgentForce is an autonomous development pipeline. You queue a task; a worker checks out an isolated git worktree, runs a coding-agent CLI (Claude Code, Codex or Antigravity) in it, verifies the result and opens a pull request on Gitea, GitHub or Azure DevOps — or leaves a local branch, patch set or plain edits for a local-only repository.

• Dashboard (Next.js, port 3200) — tasks, templates, Ideas/Backlog, skills, repos, logs, settings, secrets, analytics.
• Worker (Go) — consumes the PostgreSQL job queue, runs agents, verifies, ships. It has no authentication of its own and stays on loopback or a private network.
• PostgreSQL 16+ with pgvector — tasks, queue, events, memory.

Real-time updates flow task events → PostgreSQL NOTIFY → WebSocket → browser. Task statuses: pending → queued → running → verifying → done / failed / cancelled.

Requirements

• PostgreSQL 16+ with the pgvector extension — or let the native installer set up a private one.
• macOS (Apple silicon; Intel Macs are not supported), Linux (x64) or Windows (x64; ARM runs the x64 build). No admin rights.
• At least one agent CLI the worker can run — claude, codex or agy — with an API key or an interactive login.
• A Gitea, GitHub or Azure DevOps token only if you want pull requests. A Local Git repository needs none.
• Node.js 22 and Go 1.27+ only when building from source.

Install

Native binaries (recommended)

One command downloads the release for your OS and CPU, checks its sha256, installs it, registers a per-user service and opens the dashboard. Node is bundled; nothing is compiled. Without a licence it runs the free edition, on API keys only. For Pro, a signed-in account can generate a 14-day trial key at /account: one key per account, activated online on one machine only — on any other machine it runs as free. The trial includes 7 days of Max subscription mode (run agents on your own Claude/ChatGPT/Gemini subscription); Max mode is part of every paid licence.

macOS / Linux:

curl -fsSL https://capitaltools.app/install.sh | bash

Windows (PowerShell 5.1 or 7+):

irm https://capitaltools.app/install.ps1 | iex

Pass options after bash -s -- on Unix, or through the scriptblock form on Windows:

curl -fsSL https://capitaltools.app/install.sh | bash -s -- --key <LICENSE> --bundled-db
& ([scriptblock]::Create((irm https://capitaltools.app/install.ps1))) -Key <LICENSE> -BundledDb

From source

cp config/.env.example .env      # set at least PGPASSWORD
./scripts/migrate.sh             # create / upgrade the schema
./scripts/start.sh --dev         # or --prod; start.ps1 on Windows

Native binaries: scripts and layout

Where things live

Start, stop, restart

The install folder ships the same scripts as a source checkout. In a native install they drive the registered service, wait for the dashboard and print its localhost and Tailscale addresses. --dev/--prod are accepted and ignored.

~/.devagentforce/scripts/start.sh
~/.devagentforce/scripts/stop.sh
~/.devagentforce/scripts/restart.sh

& "$env:LOCALAPPDATA\DevAgentForce\scripts\start.ps1"
& "$env:LOCALAPPDATA\DevAgentForce\scripts\stop.ps1"
& "$env:LOCALAPPDATA\DevAgentForce\scripts\restart.ps1"

The launcher

devagentforce (Windows: devagentforce.ps1) at the root of the install folder is what the service runs:

Private PostgreSQL

When no database answers, the installer offers a private PostgreSQL with pgvector (or use --bundled-db). It listens on 127.0.0.1 from port 5433 with a random password, runs as its own service, and the connection string lands in .env. Updates never touch it and no uninstall deletes it; a major PostgreSQL upgrade is a manual dump and restore.

Reaching the dashboard from another machine

Native installs bind the dashboard to 0.0.0.0 so Tailscale peers can reach it, with the sign-in page off (WEB_HOST=0.0.0.0, WEB_LOCAL_ONLY=true, ENABLE_LOGIN_PAGE=false in .env); the worker stays on loopback. The /setup checklist then asks under Dashboard access whether to turn sign-in on, limit the dashboard to this machine, or keep the defaults. On Windows the installer adds a firewall rule admitting the dashboard port from 100.64.0.0/10 (Tailscale) only. Anything wider — a LAN, the internet — should sit behind the sign-in page and a TLS proxy.

First run

1. Open http://localhost:3200. Until setup is complete every page redirects to the Setup wizard.
2. Open Ask Agent and click Set up DevAgentForce (or type /setup): it scans the deployment and walks through what is still missing.
3. Decide Dashboard access on /setup: a native install starts reachable from other machines with sign-in off — turn sign-in on, restrict it to this machine, or keep it on a network you trust.
4. Add a repository on /repos. The easiest first one is a Local Git folder with the Patch only flow — no token, no remote.
5. Check the worker indicator on the dashboard toolbar says online.
6. Create a small, concrete first task — a research task proves your agent credentials without touching code.

Tasks, types and git flows

Git flows:

• untracked — the agent only edits files.
• commit — commit to the checked-out branch (Local) or merge to the default branch.
• patch — commit to agent/<task-key> and export git format-patch files.
• branch — push agent/<task-key> and open a pull request.

Continue resumes the same agent session; Compact summarises a long run into a short brief and restarts on a clean conversation. A backup vendor/model fails over automatically when the primary exhausts its retries. Write @repo_name in a task to give the agent read access to another repository, or @Backlog: Folder/Path to hand it a backlog folder.

File and image attachments

A task’s description and acceptance criteria take pasted screenshots and Add file(s). Text files are inlined; images, PDF and Word documents are saved next to the task’s log ({LOG_DIR}/{task_key}.attachments/) and the agent is handed the path, so it opens the real file — nothing is sent to the model as base64 text.

Dictation

Dictate beside a task description (New Task, Quick Task) and in the Ask Agent composer records your voice. The phrase in progress shows greyed at the cursor and each finished phrase is typed in; press Stop, or just submit — pending speech is kept. Speech is transcribed on the server, not by the browser: Google Gemini (GEMINI_API_KEY) by default, or a self-hosted OpenAI-compatible server such as Whisper (DICTATION_STT_URL, so audio never leaves your network). Browsers allow live microphone capture only over HTTPS or on localhost; over plain http the button becomes Dictate audio file and records or uploads a clip instead.

Skills

A skill is a callable procedure: a skills/<name>/SKILL.md folder in the Agent Skills format with declared parameters. There are two ways to use one:

• Call it — a skill task runs one skill with arguments. Unset optional parameters take their defaults; a missing required one tells the agent to stop rather than guess.
• Attach it — any task type except script can carry Attached skills. The worker installs them where each vendor’s CLI looks for skills and also puts them in the prompt, so every vendor runs every skill.

A research task needs no repository: the description is the prompt and the answer lands in the Task Log — the quickest way to check your agent credentials. It can carry attached skills like any other task.

The Skills page creates, edits, imports (.md, .zip, .skill — each scanned for secrets and malicious directives first) and exports skills, manages libraries (folders, pinned git repositories, archives) and shows usage per skill. Built-in presets include code-review, tdd, diagnosing-bugs, grill-me, senior-code and task-verify. Save as skill on a finished task drafts a reusable, parameterised skill from what the agent did — it is never saved without your confirmation. Only a skill whose frontmatter says git: true may run git commands, and never push.

Script tasks and post-success actions

A script task’s description is the command. Queue it like any task, or run it directly from the Scripts menu on the Sessions toolbar — no queue, no agent turn, no worktree. A repo-less script runs from the project root, a repo-scoped one from the repository’s folder. The output streams into the Ask Agent drawer, and the log viewer reads the last 512 KB back into the dashboard (secrets redacted). A .sh command runs under bash even on Windows when Git for Windows is installed.

New Task and Quick Task carry Run action on completion: a script task, a skill (with default or custom parameters — for example code-review on the task’s changes) or another pending task. Choose when it fires: on success (default), on failure, or always. A skill becomes a child skill task carrying the parent’s PR or branch; a chosen task is queued only while it is still pending, and never the task itself, so a chain cannot loop. An action that cannot start is reported and never changes the finished task’s result.

Review loop (Pro)

A coding task can have its changes reviewed before they are delivered. After the verifier passes, a read-only reviewer agent reads the run’s changes; the task’s own agent session fixes or declines each finding; the flow commits, the verifier runs again, and the next round reviews again — until the review is clean or a stop rule ends it. Then the task ships exactly as it would have (PR, commit, patch or uncommitted edits).

• Set per task: Review loop on/off, the reviewer vendor and model (blank = the task’s own) and 1–10 rounds (default 2).
• Rounds 1–2 must address every finding; from round 3 only blocking ones start a fix round. It stops on a reviewer, fixer or verify failure, the task’s budget, a finding reported fixed three times, or the last round.
• A stop shows Review: needs you on the task page with the open findings. On the remote commit flow, open blocking findings hold the push and Continue resumes it.
• The PR body gets a Review section with every finding and reply. Review rounds never use up the repository’s retries.

Ideas: Expand / Decompose

The Ideas/Backlog tree binds folders to repositories, and the binding is inherited by everything inside. Convert to Task turns an item into a New Task form (title, description, repository) — it is the only hand-off out of the tree.

Expand / Decompose (Pro) reads the whole document, grounds it in the inherited repository’s symbol map, and writes a new folder beside the item with ordered steps, each sized for one agent run and carrying its acceptance criteria, its dependencies and a 0–100 readiness score. The original stays. Nothing becomes a task and nothing is queued until you convert a step. A long document is read in several passes rather than truncated; an already-atomic document is marked as such with the reason. The run streams into the Ask Agent drawer and keeps going if you leave the page.

Repositories

• Gitea, GitHub and Azure DevOps — clone URL plus a personal access token (Azure: Code (Read & Write)). The provider is detected from the URL.
• Local Git — any folder that is already a clone. The agent never pushes; the branch flow pushes best-effort to the checkout’s own origin. Committing flows refuse a dirty working tree.
• Dependent repositories / folders on the repo form let an agent edit and commit (never push) in other directories.

Tasks with different agent vendors run in parallel on one repository; tasks with the same vendor queue behind each other.

Agent vendors and billing

API billing passes the key to the CLI and bills per token. Max (subscription) strips the key so the CLI uses the login you made with claude login / codex login — on the machine the worker runs on. In Max mode cost reads as $0; the Avg Tokens per Task chart still shows size.

Max (subscription) billing requires a licence. It is part of every paid licence and of the first 7 days of a trial; the free edition runs on API billing, so add your vendor’s API key. Without the entitlement the billing selector shows Max locked with a Requires licence link, new tasks and templates default to API, and a task or template saved with Max is refused at creation or stops as blocked before the agent starts — nothing is rewritten. Switch to API billing & retry on the task page moves it over. A trial shows how many Max days are left. Antigravity is the exception on the free edition: a cached agy login wins over an API key, so an unlicensed Google task cannot be guaranteed API billing and is blocked instead.

Ask Agent

The button in the corner of every dashboard page (or Ctrl/⌘ + K) opens a chat drawer running on your configured System LLM. It knows which page — and which task or repository — you are looking at, and answers from a curated handbook shipped with your version. The panel keeps working when the database is down.

Writing a message

• Enter sends; Shift + Enter starts a new line. Ctrl/⌘ + Enter also sends. On a touch device Enter adds a line and only the Send button sends. While an answer is streaming you can type the next message; Stop is the only way to interrupt.
• Type / at the start of the message for the command picker: the panel commands and this deployment’s skills, each with a one-line description. ↑/↓ move, Tab or Enter insert, Esc closes.
• Type @ to mention something: @task:KEY, @repo:name, @backlog:Path or @skill:name.
• The microphone button dictates into the message; see Dictation.
• A model picker in the toolbar chooses the model for the next turn.
• A message that looks like it holds a password, token or API key is not sent — enter secrets only on the Setup or Secrets pages.

Saved conversations

The History menu opens, renames and deletes past conversations and starts a new chat. Conversations are kept in your browser (the last 20), not on the server. Export → Markdown downloads the current one.

Panel commands

Anything else is a question. Ask Agent to fix on a red error bar sends the failing request and its diagnostic as the question; every other button that hands the panel a question only prefills it.

Pro: tools and confirmation cards

With Pro the panel agent gets read-only tools — code and doc search, per-repo memory, live task state, diffs and logs — and sees a compact catalog of your enabled skills, loading a skill’s full text only when it needs it.

Every write the panel agent wants to make is a proposal. Creating, running, continuing, retrying or cancelling a task, saving memory, creating an idea or template, saving a skill, generating the secrets store key, or running a maintenance script (restart the database, migrate, restart, backup) appears as a confirmation card with a summary, a risk badge and the arguments (secret-looking values masked). Run executes it, Edit lets you change the arguments first (they are validated again), Reject tells the agent no. Nothing changes until you click Run.

Session observatory

Sessions (free) is a read-only view of every Claude Code, Codex and Antigravity session on the worker host — not only DevAgentForce’s own agents. It lists sessions per provider, tails a transcript live, links a session to the task and repository that started it (one row per task, newest attempt wins) and opens on the tab of the task running right now. Interactive controls let you approve or reject a plan, answer a side-effect gate, send messages and stop a run. Deleting a session is real and irreversible, and refused while it is live. Text is redacted before it reaches the browser.

Search across all three providers (“which session did I say that in?”) is Pro; clicking a hit opens that session with the term highlighted.

Secrets and sign-in

Secrets store: set VAULT_ENCRYPTION_KEY (or generate it from Ask Agent / devagentforce-admin vault keygen) and secrets move off .env into AES-256-GCM storage. Lookup order is process environment → .env → secrets store. No endpoint returns a secret in cleartext. Losing the key loses the secrets — the backup script does not copy it.

Sign-in page: ENABLE_LOGIN_PAGE=true plus LOGIN_NAME/LOGIN_PASSWORD gates every page and API route. Changing the password signs everyone out; a session is bound to the client address it was issued to. It protects the dashboard only — keep the worker port private. A native install starts with it off; /setup → Dashboard access turns it on with a name and password you choose.

MCP server

devagentforce-mcp lets Claude Code (or any MCP client) drive DevAgentForce; with Pro it adds per-repo memory and code/doc search (memory_search, memory_save, corpus_search_all, …). Every search answers with a retrieval_status so “unavailable” is never mistaken for “no match”.

Tasks are always queued through the dashboard, never written straight into the queue, so both the dashboard and the worker must be up. Inside the Ask Agent panel every write tool becomes a proposal: the operator sees a confirmation card and nothing happens until they click Run. Outside the panel the tools act directly.

Updating

Settings → Updates shows your build and the newest release. The worker never updates itself; a host-side updater does it.

sh ~/.devagentforce/scripts/install-native.sh --update          # native, macOS / Linux
& "$env:LOCALAPPDATA\DevAgentForce\scripts\install-native.ps1" -Update   # native, Windows

A native update downloads only your platform’s archive, pauses the queue (refusing while tasks run unless --force), swaps program files (keeping .env, logs and worktrees), migrates, restarts and rolls back if the new build does not come up. --install-timer (-InstallTimer) registers a scheduled check that applies an update queued from the dashboard. Always move dashboard and worker together — a mismatched pair shows a Version skew banner.

Backup and uninstall

scripts/devagentforce-backup.sh     # pg_dump, settings, .env, worktrees, logs
scripts/devagentforce-restore.sh

Uninstall a native install:

~/.devagentforce/scripts/uninstall.sh [--keep-data] [--purge-secrets]
& "$env:LOCALAPPDATA\DevAgentForce\scripts\uninstall.ps1" [-KeepData] [-PurgeSecrets]

It stops the processes, removes the service, timer and firewall rule, and deletes the install folder. --keep-data keeps .env, logs and worktrees; --purge-secrets also deletes the shared secrets store. The database — including a private one — is never deleted.

Pro edition

The free edition covers task CRUD, all three vendors with failover, error-class retries, repo map, dashboard and analytics, templates, Ideas/Backlog, skills, script tasks and post-success actions, dictation, attachments, the session observatory, the secrets store, Telegram and Discord notifications, backup and restore. Pro adds:

• Max (subscription) billing — every paid licence, and the first 7 days of a trial
• Reality gate (evidence score before an agent run) and strict abstain
• Per-repo memory knowledge base and code/doc corpus search
• Interactive plan gate — approve the plan before code is written
• Budget circuit breaker (cost and wall-clock ceilings per task)
• PR preflight — secret scan, file-size and scope checks before any push
• Review loop — review, fix and re-verify before delivery
• Ideas Expand / Decompose
• Patch export, inter-task messaging, webhook triggers, tracker integrations
• A2A gateway, Crew migration, session search across providers, secrets governance
• Ask Agent tools, skill catalog and Run / Edit / Reject confirmation for every write

A licence is activated on Settings (or with --key at install). Air-gapped hosts use an offline activation token from your account page. When a licence lapses the install drops back to the free edition — nothing is deleted.

FAQ

General questions first, then the problems operators hit most: setup and the database, secrets, backup and restore and stuck tasks. In the dashboard, type /faq in Ask Agent for the short version.

Do I need an API key?

On the free edition, yes — it runs on API billing. Max (subscription) billing, where the CLI uses its own login on the machine the worker runs on, requires a licence (every paid licence, and the first 7 days of a trial).

Can I use my Claude or ChatGPT subscription instead of an API key?

Yes, with a licence: pick Max billing and log the CLI in on the worker machine. Without one, Max is locked; a task saved with Max stops as blocked until you click Switch to API billing & retry or activate a licence.

Can I use it without Gitea or GitHub?

Yes. Register a Local Git repository — any existing clone. You get uncommitted edits, a direct commit, a local branch with patches, or a best-effort push to the clone’s own remote.

I created a task and nothing happened.

The dashboard is the only process that enqueues and the worker the only one that consumes. If the dashboard was down, use Re-run; if the worker is down the task stays queued. Also check the queue is not paused (Settings).

My task failed without doing much.

A gate stopped it on purpose — PR preflight, a budget ceiling, a rejected plan or a reality-gate abstain. The task page names which. Fix the cause and click Continue.

How much does a task cost?

The task page and dashboard analytics show cost in API billing. Max billing reports $0; use the token charts instead.

I changed the database settings and nothing changed.

Connection settings are read when the pool opens — restart.

Do I need a Pro licence?

No. Without one, Pro features are dormant and everything else works on API keys; Max subscription mode needs a licence. To try Pro, generate a 14-day trial key in your account — one per account, one machine. It includes 7 days of Max mode.

Where are the logs?

/logs in the dashboard tails both processes live; on disk, logs/worker.log and logs/web.log. A task’s agent transcript is on its detail page. Registered and licensed users can also submit Bug Reports directly from the Logs page, attaching diagnostic logs automatically in one click.

Where do I start when something is not configured?

Type /setup in Ask Agent. It scans the database and migrations, the secrets store, AI providers, git host tokens, notifications and worker paths, and says what is missing. The forms are on the /setup page (/setup?force=1 reopens it).

Which database settings are used?

DATABASE_URL wins. Without it the PG* variables are used: PGHOST (default 127.0.0.1), PGPORT (5432), PGUSER and PGDATABASE (devagentforce). The worker only uses them when PGPASSWORD is set. Each value is looked up in the process environment, then .env, then the secrets store, so a value exported in the shell beats an edited .env. Changes need a restart.

“password authentication failed for user devagentforce”

The database role is missing, or its password no longer matches .env. Either correct the password in .env (or the secrets store), or reset the role with ALTER ROLE devagentforce PASSWORD '…'. Then restart.

“extension vector is not available”

You need pgvector on PostgreSQL 16 or newer. devagentforce-admin db check tells you which problem you have:

• exit 3: pgvector is not installed on the server
• exit 4: PostgreSQL is too old
• exit 6: pgvector is installed, but this login cannot enable it. Run CREATE EXTENSION vector; once as a superuser in the platform’s database.

Do I run migrations myself?

Usually not. The worker migrates when it starts (MIGRATE_ON_START, on by default). To run them by hand, use scripts/migrate.sh in a checkout or devagentforce migrate on a native install. migrate.sh will not run while some session sits idle in transaction on tasks. Close that client (often a forgotten psql or IDE session) and try again.

Dashboard and worker show “VERSION SKEW”

The dashboard and the worker are running different builds. Update both together, then restart.

How do I set up the secrets store?

First generate the key, once. Use Ask Agent’s /install-keys, the Install Keys button on the Secrets page, or devagentforce-admin vault keygen on the host. Next, move your values in with Import from .env (on a native install, devagentforce secure). Then restart. Last, save the recovery key from /setup → Show recovery key. Until a key exists the store does nothing, and every value is still read from .env.

“Install Keys” says a key is already installed

That is deliberate: a second key would leave everything sealed with the first one unreadable. To change keys, rotate them (see the next question). If a blank VAULT_ENCRYPTION_KEY is exported in the process environment, it takes priority over the key file. Remove it.

“N secrets cannot be decrypted”

The loaded key is not the one those secrets were sealed with. Usually a new key was generated, or VAULT_KEY_FILE points at a different file. To fix it:

1. Put the old key in VAULT_ENCRYPTION_KEY_OLD (comma-separated if there are several).
2. Keep the current key in VAULT_ENCRYPTION_KEY.
3. Restart.
4. Run devagentforce-admin vault rewrap.

I lost the vault key

Get it back from a backup archive that included it, or from wherever you saved the recovery key. If you have neither, the sealed values are gone. There is no back door. Generate a new key and enter the secrets again.

“secrets are stored but no key is configured”

The worker cannot find or read the key. Check VAULT_KEY_FILE, or the default location ~/.devagentforce/vault.key.

I changed a secret and nothing changed

The process environment beats .env, and .env beats the secrets store. A copy left in .env or exported in the shell wins, so delete it there.

How do I restore a backup?

Go to Settings → Backup & Restore and upload or pick an archive. The restore is staged:

1. The passphrase is checked.
2. A safety backup of the current state is saved to backups/safety/.
3. The restore is applied at the next worker start, before the worker opens the database.

The result is written to backups/last-restore.json, and Ask Agent’s /restore shows it. On the host, run scripts/devagentforce-restore.sh: either stop the worker first, or use --stage and then restart.

Restore errors

• Wrong passphrase (or damaged payload). Use the passphrase the archive was created with. If you are sure it is right, the file may have been cut short; download it again.
• Restore onto PostgreSQL N or newer. The dump comes from a newer PostgreSQL major version than this server. Upgrade the server; there is no override.
• The backup is from a newer build. Update this install first, or pass --force. Older backups are migrated forward automatically.
• No PostgreSQL client tools were found. Set PG_BIN_DIR to a folder holding pg_dump, pg_restore and psql at least as new as the server.
• The database part failed. Your data is safe: the database is restored in one transaction, so the old one stays. If the message is restored, but the schema migration failed, the data is in. Run the migrations.

Moving to a new machine

1. Install on the new host.
2. On the old host, take a backup with the key.
3. Restore it on the new host.
4. Stop the old install. Both installs share one licence seat.

The new machine keeps its own DATABASE_URL, PG*, ports, paths and VAULT_*. API keys, tokens, settings and sign-in come from the backup. If the memory and code index are empty afterwards, the backup was made without Include repositories memory. Reindex the repositories.

A task is stuck in queued

Check these in order:

1. Is the queue paused? (Settings.) An update that found it paused leaves it paused.
2. Is the worker running?
3. Is the task waiting its turn? At most WORKER_CONCURRENCY tasks run at once (default 2). On a local repository, tasks for the same vendor take turns. A depends_on prerequisite that has not finished holds the task back.

If none of those applies, wait about five minutes. A queued task with no queue job is put back and re-enqueued automatically.

A task is stuck in running

The session tail on the task page shows whether the agent is still working. If the worker died mid-run, recovery is automatic:

• Its queue job is reclaimed after 3 minutes with no heartbeat.
• A task idle longer than the repository timeout (default 60 minutes) goes back to pending.
• After that, the orphan reaper fails it with no worker activity.

You do not have to wait: click Cancel, then Re-run or Continue.

After a worker restart every task is pending

That is by design. Starting, restarting or stopping the worker from the dashboard puts every running, verifying and queued task back to pending, cancels their queue jobs and releases every repository lock. The tasks are not re-queued for you. Click Re-run on the ones you want.

Re-run, Continue or Compact?

• Re-run starts a fresh attempt.
• Continue resumes the same agent session.
• Compact condenses the history into a short brief and restarts on a clean conversation. Use it for a run that is going in circles.

The worker will not start: “address already in use”

The old worker still holds port 8000. Run scripts/stop.sh, which stops this install’s processes and frees ports 3200 and 8000, then scripts/start.sh.

Troubleshooting

The database is down

Pages show a red database banner and API calls return 503. On a native install with a private database run devagentforce db start (db status tells you why it is not up). Otherwise scripts/dbrestart.sh restarts the host service or data directory and clears a stale postmaster.pid. Then check DATABASE_URL / PGHOST / PGPORT in .env.

A task is stuck in queued

• Is the queue paused? Is the worker online?
• Are WORKER_CONCURRENCY tasks already running, or (on a local repository) another task with the same vendor, or a depends_on prerequisite still unfinished? It will start when they finish.
• An interrupted run is recovered automatically within a few minutes.

An agent CLI is “not found”

Install that CLI on the worker machine, or switch the task to a vendor you have. In Max billing, log the CLI in on the host at least once.

Rate limits (429)

The worker backs off and retries within the same attempt. If it keeps happening, run fewer tasks against one vendor or set a backup vendor.

The agent ran out of turns / goes in circles

Raise Max turns and Continue, or Compact to restart on a clean summary. Tighten the description and acceptance criteria.

The dashboard does not open from another machine

• Check WEB_HOST is 0.0.0.0 (not installed with --local-only).
• Windows: a dismissed firewall prompt leaves a block rule. Re-run install-native.ps1 -Update; it removes the block and re-adds the Tailscale rule.
• With ENABLE_LOGIN_PAGE on, a sign-in from a new address asks you to sign in again — that is the session binding, not a fault.

“This release has no archive for …”

That OS/CPU was not built for the release. Windows on ARM falls back to x64 automatically; otherwise wait for the next release.

macOS says the download is damaged

Only after a browser download (the installer is not affected): xattr -dr com.apple.quarantine ~/.devagentforce.

Restarting everything

scripts/restart.sh        # native install, or --dev / --prod in a checkout
scripts/stop.sh
scripts/migrate.sh        # native: devagentforce migrate

Still stuck? Ask Agent’s /setup scan usually names the cause. Customers can open a ticket from Support.