PRODUCT DOCUMENTATION

User guide

A practical guide to creating, observing, automating and operating AI jobs safely.

Back to dashboard

Start here

Choose a topic or search by heading, status, path or feature. The guide follows the lifecycle: prepare → create → observe → operate → secure and troubleshoot.

Operator tip

Before retrying, check the working directory, runtime/profile/model, dependencies and stderr; a retry is not a substitute for finding the cause.

01

Dashboard and filters

The dashboard is the starting point for queue status, job search and common actions.

Follow the job list

  • Filter by status, project, working directory, profile, model, creation source or starred jobs.
  • Use search for job ID, name, prompt and metadata; use pagination for large result sets.
  • Open a job by ID; Clone creates a variant and retains selected fields.
  • Mission Control provides realtime status, the next queue items and stdout/stderr for running jobs.
Operator tip

A lower priority is processed first when other conditions are equal; status and logs are the diagnostic source of truth.

02

Projects and workspaces

A project groups jobs, working directories, diagrams and shared parameters.

Manage a project

  1. Create a project with a unique name, description and location; mark one as default when appropriate.
  2. Choose Jobs to filter by project and view job, status and token-usage summaries.
  3. Use diagrams and project parameters for stable shared context.
  4. Import archives/Git only into approved directories; check repository and write permissions before running.
Operator tip

The working directory is the actual execution context; do not select directories containing out-of-scope secrets.

03

Rules, templates and prompts

Rules and prompt templates standardize tasks, acceptance criteria and recurring policy.

Build the final prompt

  • A rule has a unique name, Markdown/text, category and tags; Default rules are preselected.
  • A template stores a reusable prompt structure; job creation can still edit context and prompt.
  • Final prompt order: Base prompt → selected Rules → Extra prompt.
  • Search, export/import and manage categories/tags for a consistent guidance library.
Operator tip

Do not put tokens, private keys, passwords or personal data in a shared rule/template.

04

Create and queue a job

The Add job form collects project, context, runtime, prompt, attachments and limits before queueing.

Recommended workflow

  1. Choose the project, working directory and job name; names can be generated from the prompt.
  2. Choose profile/model, runtime, resume mode and history strategy; use Test dry-run to inspect the command.
  3. Write Base prompt, select rules, add Extra prompt and review parameter injection.
  4. Set priority, timeout and retries; use Queue first or Force start only after assessing load.
  5. Save as Draft for review; Queue for worker pickup; use the shortcuts shown on the form.
Operator tip

You can add runtime arguments, pre/post commands, dependency IDs and child/follow-up jobs. Hooks run without a shell; validate commands before production.

05

Runtime, sessions and resume

Runtime configuration selects executable/config, session or fork ID, resume mode and history strategy.

Preflight checks

  • The runtime and executable must be available on the worker; config/reference paths are not logged.
  • Fresh creates new context; Resume/Last session reuses context; Fork branches from a session.
  • Fresh/Append/Reuse changes how context is supplied; choose for the task and token limit.
  • Use command preview and dry-run before jobs with write effects or significant cost.
Operator tip

Resume is not rollback. If a session is wrong, create a new job with an explicit prompt and retain logs.

06

Images, files and diagrams

Attachments are stored with the job; project diagrams can add visual context.

Upload rules

  • Choose multiple files or paste images from the clipboard; review the preview before submitting.
  • The form currently limits uploads to 8 files and 8 MiB each; non-images are attached by path.
  • When cloning, choose old files to keep, add new files or remove all.
  • Select project diagrams or let policy attach defaults.
Operator tip

Attachments may contain code, customer data or credentials; upload only authorized data.

07

Job lifecycle and details

The detail page is where you inspect prompts, metadata, dependencies, attachments, stdout/stderr and history.

Core states

  • DRAFT is saved but not picked up; QUEUED waits for conditions/worker; RUNNING is executing.
  • SUCCEEDED completed; FAILED needs stderr review; CANCELLED was stopped by a user or system.
  • An unmet dependency may show WAITING/BLOCKED; resolve dependencies first.
  • QUEUED can be edited/prioritized/cancelled; RUNNING can be cancelled/killed; clone terminal jobs.
Operator tip

Kill is forceful and may leave side effects; use it only when graceful cancellation is unsuitable.

08

Automation, calendar and follow-up jobs

Automations create jobs from schedules/triggers; the calendar helps avoid overlap.

Operate safely

  • Check timezone and schedule; automation times are stored and executed in UTC.
  • Set an explicit project, template, profile/model and concurrency.
  • Pause/disable an automation before maintenance or duplicate creation.
  • Follow-up/child jobs follow policy and success conditions; set explicit limits.
Operator tip

A valid schedule does not guarantee success; observe queue, dependencies and notifications after changes.

09

Reports, notifications and Mission Control

Separate realtime monitoring, historical reports and notifications for fast investigation.

Choose the right tool

  • Use Mission Control for status, queue pulse and stdout/stderr streams.
  • Reports analyze throughput, retries, tokens, duration and success/failure by system or personal scope.
  • Notifications show events and unread counts; check permissions before archiving sensitive content.
  • Test Telegram/webhook/email from Config; content may include job ID, profile/model and token usage.
Operator tip

Notifications are auxiliary signals; they do not replace healthchecks, logs or queue state.

10

Configuration, API and integrations

Config manages runtime, notifications, remote sync, terminal, OpenVSCode and prompt policy.

Integration principles

  • Create tokens at /api-tokens, copy once, use HTTPS and Bearer or X-API-Token.
  • Choose the narrowest scope: read, write, logs, attachments or admin.
  • Use an idempotency key for job creation and timeout/backoff for polling; do not retry unsafe requests without one.
  • Use /api/v1/openapi.json and the API guide for endpoints, schemas, status codes and errors.
Operator tip

Tokens, logs/results, attachments and terminal output may contain project data; redact before sharing and revoke tokens.

11

Accounts, permissions and security

The UI uses session/CSRF; roles/capabilities control actions; accounts can enable 2FA.

Security checklist

  • Grant least privilege; separate access to logs, jobs, config, terminal and OpenVSCode.
  • Enable/verify 2FA in profile/security and store recovery material by policy.
  • Review Audit logs for tokens, notifications, ownership and policy.
  • Keep database, attachments, backups and custom config outside public static paths; use TLS/reverse proxy.
Operator tip

High privileges do not make terminal, backup/restore, migration or deletion automatically safe; check rollback.

12

Operations, maintenance and recovery

Maintenance provides backup, database, environment and recovery tools; run changes in the right window.

Before and after a change

  • Record version, database path, worker count, health and a backup before upgrade/migration.
  • Run the health endpoint, a smoke-test job and log checks after start/reload.
  • Restore into an isolated location before trusting a production backup.
  • After worker restart, verify RUNNING recovers to QUEUED and read logs before retry.
Operator tip

Do not delete databases, volumes, attachments or backups for routine troubleshooting; preserve evidence when unsure.

13

Mobile, terminal and OpenVSCode

Mobile supports narrow screens; Terminal and OpenVSCode are separate capabilities with quotas.

Usage boundaries

  • Mobile includes dashboard, jobs, projects, rules, templates, config, maintenance and a desktop link.
  • Terminal is bounded by quotas, shell allowlist and idle/lifetime/output limits.
  • OpenVSCode uses configured workspace/server data; check bind address, proxy and permissions.
  • Do not put secrets in command lines/output; close sessions and remove access.
Operator tip

These surfaces can access filesystem/processes; enable them only for authorized accounts.

14

Data operations

Data operations covers connectors, context, output/delivery and data contracts beyond the basic queue.

Data principles

  • Choose an explicit connector and scope; default to read-only or deny-by-default.
  • Bound query/search, timeout, bytes/rows and redaction; do not bypass scope with global search.
  • Check provenance, integrity and audit events before publishing output.
  • Track failure/quarantine and use a contract-based forward-fix or rollback.
Operator tip

Connectors/data-plane may depend on deployment; check capability, policy and health first.

15

Troubleshooting

Start from job state, read logs and inspect the relevant configuration layer; do not fix from one error.

Quick checks

  • Queued too long: verify database, worker, working directory, dependencies and concurrency.
  • Fails immediately: read stderr, executable/runtime, profile/model, permissions and pre-command.
  • Profile/model empty: check the catalog, service account .codex and runtime availability.
  • Notification fails: run the Config test, check DNS/TLS/firewall and use redacted secrets.
  • Search returns nothing: use Esc/Clear, try an unaccented term and check the TOC.
Operator tip

Risks to SSH, data or uptime require stopping and following the runbook/window; do not kill/delete/overwrite-restore without rollback.

16

Glossary and states

These concepts are used throughout the UI, API and reports.

Core terms

  • A job is one execution containing prompt, context, configuration, attachments and result.
  • Profile/model/runtime: profile supplies configuration; model is the model; runtime is the executor.
  • Rule/template: a rule is reusable guidance; a template is a structured prompt.
  • Queue/dependency/automation: scheduling, blocking conditions and scheduled/triggered job creation.
  • DRAFT, QUEUED, RUNNING, SUCCEEDED, FAILED, CANCELLED; WAITING/BLOCKED describe dependencies.
Operator tip

If UI, API or deployment differs, trust the runtime contract and record drift for the next release.