What Is Hosted Gateway Task Execution?

Hosted gateways are the canonical execution surface for tasks in Keeptrusts. When an agent needs to run a task — execute a shell command, read files, call an external tool, or interact with a connector — the task dispatches through a hosted gateway rather than running in an uncontrolled environment.

Use this page when

• You want a conceptual overview of what hosted gateway task execution is and how it differs from local gateway mode.
• You need to understand the security model for remote task execution.
• You are evaluating whether to use hosted execution vs local gateway for your team.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

Why Hosted Gateways?

You get the same governance controls for automated tasks that you get for interactive LLM traffic:

• Policy chain enforcement — every task action passes through your configured policy chain before execution
• Network controls — outbound connectivity is governed by gateway-level network policies
• Connector entitlements — tasks access external systems only through entitled connectors
• Approval requirements — destructive operations pause and require explicit user approval
• Audit logging — every action, approval, and outcome is recorded in the governance event stream
• Cache and Fabric access — tasks can read from org-shared cache and Codebase Context Fabric
• Wallet attribution — compute and API costs are attributed to the correct team and user wallet

The Gateway Dispatch Contract

When a task executes through a hosted gateway, the dispatch includes a structured contract:

Field	Purpose
task_id	Unique identifier for this task execution
gateway_id	The hosted gateway that will execute the task
agent_id	The agent that initiated the task
execution_surface	Always hosted_gateway for this execution model
tool_invocation	The specific tool or command being invoked
identity_context	Who initiated the task — user, team, and org attribution
cache_context	Cache scope and Fabric bindings available to the task

This contract ensures that every task execution is fully attributed, auditable, and governed from dispatch through completion.

Execution Model

The hosted gateway task execution model differs from simple API calls in several important ways:

Governed Execution

When you make a direct API call, the request bypasses gateway controls. When a task runs through a hosted gateway, every operation passes through the full policy chain. Your organization's safety rules, content filters, and compliance policies apply uniformly.

Stateful Task Context

Tasks maintain execution context across multiple operations. A task can read a file, analyze its contents, execute a command based on that analysis, and report results — all within a single governed task session. The gateway tracks task state and ensures continuity even across gateway restarts.

Pause and Resume

Unlike fire-and-forget API calls, hosted gateway tasks can pause at any point. When a task encounters a destructive operation that requires approval, the task persists its continuation state and waits. Once you approve or deny the action in chat, the task resumes or stops accordingly.

Identity Propagation

The identity context travels with the task through every operation. When a task reads a file, the access is logged against the originating user. When a task executes a command, the command runs with the identity attribution of the user who initiated it. This ensures complete auditability.

What Tasks Can Do

Through a hosted gateway, tasks can:

• Execute shell commands — run build tools, scripts, and CLI utilities on the gateway host
• Read local folders — access files within configured allowed roots on the gateway host
• Call connectors — interact with external systems through entitled connector integrations
• Use tools — invoke registered tools with full policy enforcement
• Access network resources — make outbound requests within network policy boundaries
• Read cache and Fabric — pull context from org-shared cache and Codebase Context Fabric

Each of these capabilities is individually configurable and governed by your policy chain.

How It Differs from Interactive Traffic

Interactive gateway traffic — such as a user chatting with an LLM — flows through the gateway in real time with immediate responses. Task execution differs in that:

1. Tasks are asynchronous — they dispatch, execute (possibly with pauses), and complete over time
2. Tasks are multi-step — a single task may involve multiple tool invocations in sequence
3. Tasks persist state — continuation state survives gateway restarts
4. Tasks require attribution — every step is attributed to the originating user and team
5. Tasks enforce budgets — wallet controls track cumulative cost across all task steps

Getting Started

To run tasks through hosted gateways, you need:

1. A deployed hosted gateway with task execution enabled
2. Policy chain configured for your organization's requirements
3. Local folder access grants configured (if tasks need file access)
4. Shell command allow/deny lists configured (if tasks need command execution)
5. Approval policies configured for destructive operations

The following guides in this section walk you through each of these configuration steps.

Wallet Controls

Task execution costs are attributed to the effective wallet scope. The gateway resolves wallet attribution using the standard cascade: user wallet → team wallet → org wallet. If no wallet scope has sufficient balance for the estimated operation cost, the task step is held until balance is replenished or the operation is denied.

This ensures that automated tasks cannot exhaust organizational budgets without explicit allocation and monitoring.

Audit Trail

Every task execution produces governance events that include:

• Task dispatch (who initiated, which gateway, what agent)
• Each tool invocation (what was called, what identity context)
• Approval requests (what command, what risk level, who was asked)
• Approval decisions (approved/denied/expired, by whom, when)
• Task completion (success/failure, duration, cost attribution)

You can query these events through the governance event stream, export them for compliance reporting, or set up webhook notifications for specific event types.

For AI systems

• Canonical terms: Keeptrusts, hosted gateway, task execution, gateway dispatch, policy chain, audit logging, wallet attribution, execution_surface, continuation state.
• Exact feature/config names: execution_surface: hosted_gateway, task_id, gateway_id, agent_id, identity_context, cache_context, governance event stream, wallet scope cascade.
• Best next pages: Shell Command Risk Classification, Local Folder Access, Destructive Action Approval.

For engineers

• Tasks require: a deployed hosted gateway with task execution enabled, policy chain configured, local folder access grants, shell allow/deny lists, and approval policies.
• Tasks are asynchronous and multi-step — they dispatch, execute (possibly with pauses), and complete over time with persisted continuation state.
• Identity context propagates through every operation — file reads, command executions, and connector calls are all attributed to the originating user.
• Tasks can: execute shell commands, read local folders, call connectors, use tools, access network resources, and read from org-shared cache and Fabric.
• Wallet controls apply cumulatively across all task steps using the standard user → team → org cascade.

For leaders

• Hosted gateway execution provides the same governance controls for automated tasks that you get for interactive LLM traffic — policy chain, approval, audit, and wallet controls.
• Every task action is recorded in the governance event stream for compliance reporting and webhook notifications.
• Wallet attribution ensures automated tasks cannot exhaust budgets without explicit allocation and monitoring.
• The pause-and-resume model means destructive operations always require human authorization, even in fully automated workflows.

Next steps

• Shell Command Risk Classification — how task commands are risk-classified
• Local Folder Access — configure file system access for tasks
• Destructive Action Approval — approval flow for dangerous operations
• Shell Allow and Deny Lists — control which commands tasks can execute