Operators & Settings

Cargo Operators

Cargo Operators are self-hosted execution agents that run CodeCargo workloads in your own infrastructure. They connect back to the CodeCargo platform and can execute workflows in isolated environments under your control.

Enabling Self-Hosted Operators

Navigate to Organization Settings → Operators to manage your cargo operators. Before creating an operator, you must enable the self-hosted feature using the toggle at the top of the page. Enabling or disabling self-hosted operators requires confirmation.

Creating an Operator

1. Click Create Cargo Operator
2. Provide a name for the operator
3. Optionally set an initial token expiration date
4. Click Create

After creation, you receive an access token and setup instructions for deploying the operator to your Kubernetes cluster.

Operator List

The operators table shows:

Operator status is monitored in real time via NATS — the status badge updates automatically as operators connect and disconnect.

Operator Detail Page

Click an operator name to view its detail page.

Setup Instructions

If the operator is not yet connected, setup instructions are shown automatically. The instructions walk through three steps:

1. Create Namespace & Secret — set up a Kubernetes namespace and store the access token as a secret
2. Install Helm Chart — deploy the cargo operator using the CodeCargo Helm chart from the OCI registry
3. Verify Connection — confirm the operator is connected using kubectl commands

Once connected, you can collapse the instructions and expand them again from the Setup Instructions button if needed.

Status Overview

A summary grid shows four key metrics:

• Status — Connected or Disconnected
• Access Tokens — number of tokens issued for this operator
• Active Instances — number of currently connected operator instances
• Created At — registration timestamp

Access Tokens & Instances

Each operator can have multiple access tokens. Tokens are grouped in the detail view, and each token shows:

• Short ID — truncated token identifier
• Status — Active (green), Expired (red), or Never Used (gray)
• Expiration — expiration date, or "Never expires"
• Instance count — how many operator instances are using this token

Expand a token to see its connected instances, each showing instance name, connection status, connected/disconnected timestamps, and when the token was last used.

You can add new tokens, edit expiration dates, and delete tokens (as long as at least one token remains) from the manage menu on each token.

Organization Settings

Navigate to Organization Settings from the sidebar to manage general organization configuration.

General Settings

• Default Permissions for Project — set the default role (Admin, Viewer, or None) that new users receive when added to projects in this organization
• Manage CodeCargo App — opens the GitHub App installation page to manage repository access
• Resync Organization — triggers a full resync of users, teams, and repositories from GitHub

Prompts Configuration

Prompts in CodeCargo are reusable system prompts that organization administrators define and make available to all users in the GenAI Editor chat. When a user starts a chat session, they can select a prompt to shape how the AI responds — for example, a prompt tuned for Terraform migrations, security reviews, or CI/CD pipeline authoring. Each prompt provides domain-specific instructions so the AI produces more relevant and consistent output for that use case.

The Prompts page under organization settings (Organization Settings → Prompts) lets you create and manage these prompts. Each prompt has:

• Name — a human-readable identifier users see when selecting a prompt in chat
• Instructions — markdown-formatted prompt instructions that guide the AI's behavior when this prompt is selected

You can create, edit, and delete prompts. Instructions support full GitHub-Flavored Markdown with a write/preview toggle for editing.

CargoWall Configuration

The CargoWall settings page lets you enable or disable CargoWall for AI/LLM jobs and manage rules that control network egress from CodeCargo's AI agents.

AI/LLM Configuration

The AI/LLM settings page allows you to configure AI model provisioning and key management for CodeCargo's AI features.

Multi-Model Support

CodeCargo supports multiple AI model providers through LiteLLM integration:

• Managed Keys — CodeCargo provides and manages API keys for supported providers
• Bring Your Own Keys (BYOK) — Use your organization's API keys for AI services
• On-Demand Provisioning — AI models are provisioned automatically when needed
• Per-Task Deployments — Different AI tasks can use different model configurations

Key Management

AI API keys are managed at the organization level with automatic fallback:

• BYOK Priority — Your organization's keys take precedence when available
• Managed Key Fallback — CodeCargo's managed keys are used when BYOK keys are not configured
• Secure Storage — All keys are encrypted and stored securely

Notifications

CodeCargo notifies you about important events — compliance issues, CargoWall alerts, account and access changes, and system updates. You control where notifications go (destinations) and which events reach you (subscriptions), at both the organization and personal level. Organization admins set the defaults; individual users can override them from their profile.

Destinations

Destinations define where CodeCargo sends notifications. Every member always has the in-app notification bell; on top of it you can add Slack channels, webhook endpoints, and email addresses.

Create and manage destinations from Organization Settings → Notifications or Profile → Notification Preferences. Once added, a destination can be used in per-event routing alongside any other channel.

In-App Notification Bell

The notification bell in the top navigation bar scopes its feed and unread count to your active organization. When you switch organizations, the bell updates to show only that org's notifications. Notifications that belong to no specific org — such as a personal access token expiring — remain visible in every org.

Mark all as read and Clear all act on the visible (org-scoped) set, so clearing one org's bell does not affect another org's notifications.

Connecting Slack

Slack notifications use a proper OAuth integration rather than a webhook URL. Setup is a two-step process:

1. Connect the workspace (org admin): Navigate to Organization Settings → Notifications and click Add Slack. This starts an OAuth flow that installs the CodeCargo Slack app into your workspace and stores a bot token for your organization. Only org admins can perform this step.
2. Subscribe a channel (any workspace member): In any channel you want notifications in, run /codecargo subscribe. The bot confirms the subscription in-channel. You can only subscribe to channels you already belong to.

The slash command supports:

Subscribed channels appear in the org's Channels list under notification settings. You can remove one there or by running /codecargo unsubscribe in the channel.

Linking Your Slack Account

Before you can subscribe or unsubscribe channels, your Slack identity must be linked to your CodeCargo account. This lets CodeCargo apply your organization permissions — only CodeCargo org admins can manage subscriptions from Slack.

The first time you run /codecargo in a connected workspace, the command replies with an ephemeral message containing a Connect your CodeCargo account link:

1. Click the link — it opens the /slack/link page in your browser.
2. If you are not already signed in to CodeCargo, you are routed through login and returned to the link page automatically.
3. Review the Slack workspace and user shown, then confirm the connection.

The link is global — you complete it once, and it applies across every CodeCargo organization your account can access.

Webhooks and Email

Add and manage webhook and email destinations from Organization Settings → Notifications or Profile → Notification Preferences:

1. Click Add Destination.
2. Choose the channel type and provide the required URL or email address.
3. Test the destination to confirm it is working.
4. Enable or disable destinations as needed.

Subscriptions

Subscriptions control which notifications you receive and how they are delivered. For each category of event you can configure:

• Severity threshold — the minimum level that triggers a notification (Info, Warning, Error, Critical)
• Delivery — send immediately, or batch into a digest
• Channels — which destinations receive that category

Nudges and Delivery Frequency

CodeCargo also sends nudges automatically for important organizational events:

• Compliance issues — outstanding guardrail failures requiring attention, surfaced through Workflow Compliance
• CargoWall alerts — new destinations to review, blocked egress, and baseline status from CargoWall
• Repository status — repositories not enforcing policies, and stalled baselines

Many nudge categories come from periodic scans rather than real-time events, so they show a Frequency picker rather than a simple immediate/digest choice. The options offered for each category reflect its actual cadence, so the label matches when you can expect delivery:

For hourly categories, Hourly means you are notified within about an hour of the underlying count changing — for example, a new guardrail failure appearing or being resolved. An unchanged backlog does not re-notify you: deduplication collapses repeated scans onto the same notification until the count actually changes. Daily or Weekly batches those changes into a digest. For daily categories such as destinations to review and blocked egress, Daily is the fastest option because the underlying scan runs once per day by design.

Organization vs Personal Settings

Subscriptions work at two levels:

• Organization defaults — set by admins; apply to all members unless overridden
• Personal overrides — individual preferences that take precedence over the org defaults

This lets organizations establish baseline notification policies while giving each member control over their own experience.

For repo-shaped nudges — CargoWall baselines, destinations to review, blocked egress, repos not enforcing, and stalled baselines, as well as guardrail compliance nudges — notifications are delivered per member based on which repositories you can access. Because delivery is personalized, you can set your own frequency, severity threshold, and channel routing for these categories from Profile → Notification Preferences. Your personal preference wins over the org default for those categories.

For broadcast org nudges — such as org sync and LLM budget alerts — notifications are delivered org-wide at the org's cadence and are never routed to a member's personal channels. These categories appear only in Organization Settings → Notifications and are not configurable from your personal profile. The LLM budget category is additionally restricted to org admins.

For categories that are personal by nature (PAT expiry, access granted), there is no org default — they appear only in your personal notification preferences.

Off-App Message Details

When notifications go to Slack, email, or a webhook, CodeCargo adds context that the in-app bell doesn't need.

Organization Name

A single Slack channel, email inbox, or webhook endpoint can receive notifications from multiple organizations. So you can tell which org a message refers to, each off-app notification includes the organization name:

• Slack — a context line Organization: <name> appears under the notification heading
• Email — an Organization: <name> line appears under the notification title (omitted for personal notifications with no org)
• Webhook — an orgName field is included alongside the existing orgId in the JSON payload

Personal notifications (such as PAT expiry alerts) have no associated org and show no org label in any channel.

Action Links

Action links in Slack messages, emails, and webhook payloads are absolute URLs. CodeCargo combines each notification's relative UI path with your deployment's UI base URL before delivery. For example, if your base URL is https://your-deployment.example, /runs/123 becomes https://your-deployment.example/runs/123, so links open correctly in email clients and external tools.