Runtime Hosting Modes

Helm ADE supports two runtime hosting modes for running your AI agents: Helm Cloud (cloud-hosted) and Self-Hosted Local (run on your own infrastructure). This article explains how to configure your project's runtime mode and set up a local runtime agent.

Overview

Runtime hosting modes determine where your AI agent workloads execute:

Mode	Description	Best For
Helm Cloud	Agents run on Helm's managed infrastructure	Teams wanting zero infrastructure management
Self-Hosted Local	Agents run on your own machines or servers	Teams with security requirements, air-gapped environments, or custom compute needs

Both modes use GitHub-backed project sync to keep project state consistent across team members, regardless of their runtime mode.

Accessing Runtime Settings

Runtime mode is configured per-project in Project Settings:

Navigate to the Project Dashboard (select your project from the header)

Click the Settings button (gear icon) in the Quick Actions area

On the Project Settings page, find the Runtime Hosting section

Choosing a Runtime Mode

Helm Cloud Mode

Helm Cloud is the default runtime mode. With this mode:

• Agents execute on Helm's managed Modal infrastructure
• No local setup required
• Automatic scaling and resource management
• Logs and metrics available in the Helm dashboard

To select Helm Cloud:

Open Project Settings

In the Runtime Mode section, select Helm Cloud

Click Save to apply the change

Self-Hosted Local Mode

Self-Hosted Local mode runs agents on your own infrastructure. This requires setting up a local runtime agent.

To select Self-Hosted Local:

Open Project Settings

In the Runtime Mode section, select Self-Hosted Local

A Local Agent Setup panel will appear below the mode selector

Setting Up a Local Runtime Agent

When you select Self-Hosted Local mode, you need to register a local runtime agent:

Step 1: Install the Local Agent

Download and install the Helm local runtime agent on your machine or server:

# Using npm (Node.js 18+ required)
npm install -g @helm-ade/runtime-agent

Or using the standalone binary
curl -fsSL https://get.helm-ade.dev/agent | sh

Step 2: Generate an Agent Token

In the Local Agent Setup panel:

Enter a name for your local agent (e.g., "dev-machine" or "build-server")

Click Register Agent

Copy the generated Agent Token — you'll need this to authenticate

> Security Note: Agent tokens are shown only once. Store them securely. If you lose a token, you'll need to generate a new one.

Step 3: Start the Agent

Start the local agent with your token:

helm-agent start --token YOUR_AGENT_TOKEN

The agent will connect to Helm and appear as "Online" in the Local Agent Setup panel.

Step 4: Verify Connection

Once the agent is running:

• The Connection Status indicator will show Connected (green)
• The Runtime Status Badge in your project header will show the active runtime mode
• You can now run agent sessions that execute locally

Understanding Runtime Status

The project UI displays runtime status in several places:

Runtime Status Badge

A badge in the project header shows your current runtime mode:

• Cloud (blue badge) — Using Helm Cloud runtime
• Local (green badge) — Using self-hosted local runtime
• Local (Disconnected) (yellow badge) — Local mode configured but agent offline

Health Indicators

In Project Settings, the Local Agent panel shows:

Indicator	Meaning
Connected	Agent is online and ready to accept workloads
Disconnected	Agent is not reachable; check if it's running
Initializing	Agent is starting up

Permission Requirements

Runtime mode changes require appropriate permissions:

Action	Required Role
View runtime mode	Any project member
Change runtime mode	Project Admin or Organization Admin
Register local agents	Project Admin or Organization Admin
Revoke agent tokens	Organization Admin

If you see a permission error when trying to change runtime settings, contact your organization admin.

Troubleshooting

Local agent won't connect

Verify the agent is running: helm-agent status

Check your network allows outbound connections to api.helm-ade.dev

Ensure the agent token is correct and hasn't been revoked

Check firewall rules for WebSocket connections on port 443

"Agent offline" but agent is running

The agent may have lost its connection. Try:

Restart the agent: helm-agent restart

Check your internet connection

Look for errors in agent logs: helm-agent logs

Can't change runtime mode

You may not have permission to modify project settings. Contact a project or organization admin to change the runtime mode.

Sessions fail with "No runtime available"

This occurs when:

• Helm Cloud mode: Helm's infrastructure is temporarily unavailable (rare)
• Self-Hosted Local mode: Your local agent is offline or unreachable

Check the Runtime Status Badge and ensure your chosen runtime is available.

GitHub Repository Sync

Helm ADE uses GitHub-backed sync to keep project state consistent across team members using different runtime modes (cloud vs. local). This ensures everyone works from the same project state regardless of where their agents run.

Configuring Repository Binding

To enable sync between runtime modes:

Open Project Settings

In the Runtime Hosting section, find GitHub Repository

Enter your GitHub repository URL (e.g., https://github.com/your-org/your-project)

Select the branch to sync (defaults to main)

Click Save

> Permission Note: You must have write access to the repository. If you see a 403 error, verify your GitHub permissions.

How Sync Works

Direction	Description
Push	Upload local changes to GitHub
Pull	Download remote changes from GitHub
Bidirectional	Sync both directions (used automatically)

Sync happens automatically when:

• You switch runtime modes
• Another team member pushes changes
• You manually trigger a sync

Handling Sync Conflicts

When cloud and local runtime edits conflict, Helm provides actionable merge guidance:

The sync status will show Conflict

Open the sync details to see conflicting files

Follow the merge guidance to resolve:

- Review conflicting files - Choose which changes to keep - Commit resolved files - Retry the sync

Viewing Sync Status

The sync status appears in several places:

• Runtime Status Badge — Shows current sync state (Syncing, Synced, Conflict, Error)
• Project Settings — Detailed sync history and current status
• AI Tools — Query sync status via get_project_sync_status

Sync Troubleshooting

#### "No GitHub repository configured"

You need to bind a GitHub repository before syncing. See "Configuring Repository Binding" above.

#### "You do not have access to this repository"

Your GitHub account doesn't have write access to the repository. Ask a repository admin to grant you access.

#### Sync stuck in "Syncing" state

Check your network connection

Verify GitHub is accessible

Wait a few moments and refresh

If persistent, contact support

#### Repeated sync conflicts

Consider:

Coordinating with team members to avoid simultaneous edits

Using more granular sync intervals

Reviewing your branching strategy

Related Topics

• App Workspace Overview — Overview of the main workspace
• Organization and Project Switching — Navigate between projects