Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dench.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Long Sessions let an agent work autonomously for a bounded time in an isolated sandbox. They stream progress, save artifacts, ask before risky actions, consume prepaid AI credits, and pause when credits run out.

​
Start a Long Session

Use a clear goal and duration. Include safety limits in the goal. 
dench autonomous run "Find useful work to do in this workspace. Review context and save task_suggestion artifacts. Do not edit files, publish, deploy, spend money, send external messages, access secrets, or change production data." --duration 30m --json
Durations can use minute or hour values, such as 30m, 1h, 3h, and 5h. until-done maps to the maximum run budget.
​
goal
string
required
The Long Session goal. Keep it specific and include safety constraints for risky actions.
​
--duration
string
Time budget, such as 30m, 1h, 3h, 5h, or until-done.
​
--model
string
Model override. Omit this to use the server default.
​
--api-base
string
API base for /api/autonomous/runs. Defaults to http://localhost:3000. You can also override this with --host, DENCH_AUTONOMOUS_API_BASE, or DENCH_HOST.
​
--json
boolean
Return the raw run payload with a runUrl added when the API returns a run ID.
If you run from a fresh machine, authenticate first: 
dench onboard --kind <kind> --name "AI Agent - Project"
If the API base is not the same as your saved Dench host, log in against that host: 
dench login --host https://dench.dev

​
Approval rules

The CLI sends conservative approval rules by default: publishing, spending, external messages, production changes, and secrets. You can make the rules explicit with flags: 
dench autonomous run "Audit the repo and summarize risks." \
  --duration 1h \
  --ask-before-publishing \
  --ask-before-spending \
  --ask-before-external-messages \
  --ask-before-production-changes \
  --ask-before-secrets
Or pass a comma-separated rule list: 
dench autonomous run "Research billing flows and save a report." \
  --approval-rules publishing,spending,secrets \
  --duration 30m

​
Credits

Long Sessions use prepaid AI credits. If credits are empty, the CLI and API return a structured blocker: 
{
  "ok": false,
  "status": 402,
  "code": "ai_credits_required",
  "topUpUrl": "https://dench.dev/usage",
  "nextActions": [
    "Top up AI credits before starting a Long Session.",
    "Retry the same request after the balance updates."
  ]
}
Do not retry in a loop. Ask the human to top up credits, then retry once the balance updates.

​
Paused runs

If a run pauses because credits are empty:
  1. Open the run detail page.
  2. Top up credits through the approved billing path.
  3. Click Resume.
  4. Confirm the same run moves back to starting or running.
The resumed run should keep its original run ID and record a resume event.

​
Artifacts and suggested work

Long Sessions should save durable work as artifacts:
  • reports
  • research notes
  • content drafts
  • patches
  • task_suggestion artifacts for follow-up work
Review suggested work with: 
dench suggested-work --json
Convert useful suggested work into a task: 
dench suggested-work task <artifactId> --json
If the suggestion is already applied or archived, choose another suggestion or create a new task manually.

​
Safe and risky goals

Safe goals can include negated risky words: 
Audit the repo. Do not deploy, publish, spend money, send messages, access secrets, or change production data.
Risky goals require approval before the action happens: 
Deploy the app to production.
The agent should request approval, wait for the human, and only continue after a clear approval.

​
Failure recovery

ProblemWhat to do
missing_goalRetry with a clear goal and safety limits.
invalid_durationUse 30m, 1h, 3h, 5h, or until-done.
unauthorized or agent_session_invalidRun dench sessions --json, then dench use <session-key-or-workspace-slug>, or run dench onboard again if the session expired.
ai_credits_requiredTop up credits from the topUpUrl, then retry or resume.
Sandbox setup failedSave the error as an artifact or log, then ask the human whether to retry. Do not keep retrying silently.
Missing Daytona, Bedrock, 1Password, or Exa credentialsReport the missing credential and wait for an admin. Do not invent secrets.