Standalone Tasks

Every unit of agent work in Optio is a Task. When a Task has a repo attached (a Repo Task), the agent clones the repo and opens a PR. When it doesn't (a Standalone Task), the agent runs in an isolated pod with no git checkout and produces logs + side effects through its Connections.

Use Standalone Tasks for generating reports, analyzing data, triaging alerts, drafting documentation, or anything repeatable that doesn't need a repo checkout.

Standalone vs Repo Tasks

Creating a Standalone Task

Navigate to Tasks → New Task in the dashboard. A standalone task definition includes:

• Name and description — identify the task in the dashboard and logs
• Agent runtime — choose from Claude Code, OpenAI Codex, GitHub Copilot, Google Gemini, or OpenCode
• Prompt template — the agent prompt, with {{PARAM}} placeholders for dynamic values
• Parameter schema — optional JSON Schema that validates inputs before each run
• Environment — Docker image, setup commands, secrets, and network configuration
• Limits — max turns, budget (USD), max concurrent runs, and retry count

POST /api/tasks
{
  "type": "standalone",
  "name": "Weekly Security Report",
  "description": "Scans dependencies and generates a vulnerability summary",
  "agentRuntime": "claude-code",
  "model": "sonnet",
  "promptTemplate": "Analyze the dependency list for {{REPO_NAME}} and produce a security report. Focus on: {{FOCUS_AREAS}}",
  "paramsSchema": {
    "type": "object",
    "properties": {
      "REPO_NAME": { "type": "string" },
      "FOCUS_AREAS": { "type": "string", "default": "CVEs, outdated packages, license issues" }
    },
    "required": ["REPO_NAME"]
  },
  "maxTurns": 20,
  "maxRetries": 2,
  "maxConcurrent": 1
}

Prompt Templates

Standalone task prompts use {{PARAM_NAME}} syntax. When a run is created, each placeholder is replaced with the corresponding value from the run's parameters. Unmatched placeholders are left as-is.

Summarize the latest {{COUNT}} support tickets for {{TEAM}}.
Group by category and highlight any recurring issues.
Output as markdown.

If a paramsSchema is defined, Optio validates the parameters against it before starting the run.

Triggers

Each standalone task can have up to three triggers — one of each type. Triggers determine how and when a standalone task run starts.

Manual

Run the task on demand from the dashboard or via the API. Pass parameters in the request body.

POST /api/tasks/:id/runs
{
  "params": {
    "REPO_NAME": "optio",
    "FOCUS_AREAS": "CVEs, outdated packages"
  }
}

Schedule

Run the task on a cron schedule. The trigger worker checks for due schedules every 60 seconds.

POST /api/tasks/:id/triggers
{
  "type": "schedule",
  "config": {
    "cronExpression": "0 9 * * 1",
    "paramMapping": {
      "REPO_NAME": "optio"
    }
  }
}

The dashboard includes presets for common schedules: every hour, daily at midnight, weekdays at 9 AM, and weekly on Monday.

Webhook

Trigger the task from an external system via HTTP POST. Each webhook trigger gets a unique path that you can point third-party services at.

POST /api/tasks/:id/triggers
{
  "type": "webhook",
  "config": {
    "path": "security-scan",
    "secret": "whsec_...",
    "paramMapping": {
      "REPO_NAME": "$.repository.name"
    }
  }
}

The webhook endpoint is POST /api/hooks/security-scan. If a secret is configured, Optio validates the X-Optio-Signature header using HMAC-SHA256. The paramMapping field uses JSONPath expressions to extract values from the incoming webhook payload.

Execution

When a run is created, it enters the queued state and is picked up by the worker. The worker:

1. Renders the prompt template with the run's parameters
2. Provisions a Kubernetes pod (or reuses one from the warm pool)
3. Executes the agent with the rendered prompt
4. Streams logs to the dashboard in real time via WebSocket
5. Captures output, cost, and token usage when the agent completes

Concurrency and Retries

Two concurrency limits apply:

• Global: OPTIO_MAX_WORKFLOW_CONCURRENT (default: 5) — total standalone task runs
• Per-task: maxConcurrent (default: 2) — parallel runs of the same standalone task

Failed runs are automatically retried up to maxRetries times (default: 1) with exponential backoff starting at 5 seconds.

Monitoring Runs

The detail page shows all runs with their status, duration, cost, and parameters. Click a run to view its full log stream, output, and metadata. You can also retry failed runs or cancel running ones from the dashboard.

GET /api/tasks/:id/runs

GET /api/workflow-runs/:runId
GET /api/workflow-runs/:runId/logs

Next Steps