Kortix AI Management System

The production web environment is hosted on AWS ECS Fargate. This stack manages the kortix-prod-web ECS service and the domain prod-fe-ecs.kortix.com.

Key operational details:

• Infrastructure: Runs two on-demand Fargate tasks across private subnets.
• Scaling: Uses CPU and memory target tracking to scale the service from two to twelve tasks.
• Reliability: Employs an ECS deployment circuit breaker to automatically roll back unhealthy task revisions.
• Dependencies: Reads from the production VPC, subnets, and the kortix-prod-web-env secret.
• State Management: Uses the remote state key prod/ecs-web.tfstate.

Note on Deployment: This stack does not manage kortix.com. Vercel remains active during parallel validation, and production protection is disabled in the rendered web profile.

The cost-anomaly-detection skill is a daily, reusable-session runbook designed to detect AWS cloud spend anomalies. It uses AWS Cost Explorer to maintain a per-service and per-account spend baseline. When spend exceeds a defined threshold, the skill attributes the likely driver (e.g., new resource, traffic surge, region shift) and posts an alert to a specified Slack channel.

Key Characteristics:

• Proactive & Scheduled: Designed to run via a daily cron job.
• Read-Only: It only queries AWS Cost Explorer; it never modifies, deletes, or creates AWS resources or budgets.
• Alert-Only: The primary output is a Slack message to {{alert_channel}}.
• Stateful: It uses a durable ledger to maintain cumulative baselines and track known patterns.

The kortix-staging-web stack manages the staging web environment using AWS ECS Fargate. It is hosted at staging-fe-ecs.kortix.com and is designed for parallel validation alongside Vercel.

Key Infrastructure Details:

• Service: kortix-staging-web ECS service.
• Scaling: Starts with one on-demand Fargate task. It scales between one and four tasks based on CPU and memory target tracking.
• Resiliency: Uses the ECS deployment circuit breaker to automatically roll back unhealthy task revisions.
• Dependencies: Reads from the staging VPC, subnets, and the kortix-staging-web-env secret.
• State Management: Uses the remote state key staging/ecs-web.tfstate.

The @kortix/sandbox-agent-server is a thin daemon that runs inside every Kortix project-session sandbox. It acts as a process supervisor, reverse proxy, and static web server to manage the sandbox environment.

Core Responsibilities:

• Process Supervision: Manages the opencode serve process.
• Reverse Proxy: Fronts the opencode HTTP and SSE surface on KORTIX_SERVICE_PORT (default 8000).
• System-Skill Injection: Injects managed Kortix system-skills into the OpenCode discovery directory.
• Static Web Server: Serves HTML/assets written to disk on KORTIX_STATIC_PORT (default 3211). It injects a <base> tag to ensure relative assets resolve correctly through the sandbox proxy.
• Control Surface: Provides health monitoring and repository refresh capabilities via specific HTTP routes.

The document you are currently reading (KAAB_DEPTH_PLAN.md) is historical and superseded. It records the implementation state as of 2026-07-27.

For the current contract, implementation details, and up-to-date usage instructions, refer to the official guide: Drive Kortix as a Backend.

The Sandbox Mid-Session Stop plan aims to prevent the accidental termination of sandboxes that a user still legitimately owns, and to ensure that legitimate terminations are not reported as OpenCode crashes.

Core Architecture Changes:

• deadline_at remains the single source of truth for stopping sandboxes.
• Implementation of control-plane-attested observations for three specific states:
  • Waiting on a human.
  • LLM-silent tool work.
  • A reopened session being read.
• Every 'parked' sandbox must include a recorded reason.
• The /start endpoint is designated as the owner of the 'wake' mechanism to prevent parallel health checks (503s) from being misread as terminal failures.

Tech Stack:

• API: Bun, Hono, Drizzle (apps/api)
• Database: node-pg-migrate (packages/db)
• Frontend/SDK: React, @kortix/sdk (packages/sdk, apps/web)

OpenCode is the open-source coding-agent runtime that executes every session. It is managed by the kortix-agent daemon, which runs the command opencode serve.

The daemon is configured to use the project's .kortix/opencode/ directory as its configuration source.

The Kortix Sandbox is an isolated Linux environment with the following characteristics:

• User: The runtime user is kortix and has passwordless sudo access.
• Workspace: The project repository and configuration are located at /workspace.
• JavaScript/TypeScript: Use pnpm for dependencies and pnpm dlx for temporary package commands. Use Bun only if specifically required by a project.
• Python: Python 3 is available via python or python3. Use uv for dependency management.
• Path: Node.js, npm, pnpm, Python, uv, Bun, OpenCode, and the kortix CLI are all available on the PATH.
• Browser: agent-browser and Chromium are installed for accessing local pages.
• Other Tools: Git, curl, tmux, ffmpeg, LibreOffice, Pandoc, LaTeX, Poppler, qpdf, and Tesseract are pre-installed.

Kortix uses different environments for development, testing, and production. Deployment targets vary between Amazon ECS Fargate and Vercel depending on the environment.

Note: Dev and Preview environments are ECS-only. Staging and Production use parallel paths for ECS and Vercel.