PRODUCT DOCUMENTATION
User guide
A practical guide to creating, observing, automating and operating AI jobs safely.
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.
Before retrying, check the working directory, runtime/profile/model, dependencies and stderr; a retry is not a substitute for finding the cause.
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.
A lower priority is processed first when other conditions are equal; status and logs are the diagnostic source of truth.
Projects and workspaces
A project groups jobs, working directories, diagrams and shared parameters.
Manage a project
- Create a project with a unique name, description and location; mark one as default when appropriate.
- Choose Jobs to filter by project and view job, status and token-usage summaries.
- Use diagrams and project parameters for stable shared context.
- Import archives/Git only into approved directories; check repository and write permissions before running.
The working directory is the actual execution context; do not select directories containing out-of-scope secrets.
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.
Do not put tokens, private keys, passwords or personal data in a shared rule/template.
Create and queue a job
The Add job form collects project, context, runtime, prompt, attachments and limits before queueing.
Recommended workflow
- Choose the project, working directory and job name; names can be generated from the prompt.
- Choose profile/model, runtime, resume mode and history strategy; use Test dry-run to inspect the command.
- Write Base prompt, select rules, add Extra prompt and review parameter injection.
- Set priority, timeout and retries; use Queue first or Force start only after assessing load.
- Save as Draft for review; Queue for worker pickup; use the shortcuts shown on the form.
You can add runtime arguments, pre/post commands, dependency IDs and child/follow-up jobs. Hooks run without a shell; validate commands before production.
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.
Resume is not rollback. If a session is wrong, create a new job with an explicit prompt and retain logs.
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.
Attachments may contain code, customer data or credentials; upload only authorized data.
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.
Kill is forceful and may leave side effects; use it only when graceful cancellation is unsuitable.
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.
A valid schedule does not guarantee success; observe queue, dependencies and notifications after changes.
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.
Notifications are auxiliary signals; they do not replace healthchecks, logs or queue state.
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.
Tokens, logs/results, attachments and terminal output may contain project data; redact before sharing and revoke tokens.
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.
High privileges do not make terminal, backup/restore, migration or deletion automatically safe; check rollback.
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.
Do not delete databases, volumes, attachments or backups for routine troubleshooting; preserve evidence when unsure.
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.
These surfaces can access filesystem/processes; enable them only for authorized accounts.
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.
Connectors/data-plane may depend on deployment; check capability, policy and health first.
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.
Risks to SSH, data or uptime require stopping and following the runbook/window; do not kill/delete/overwrite-restore without rollback.
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.
If UI, API or deployment differs, trust the runtime contract and record drift for the next release.
No matching content was found.