Hot App

The Hot App is a web-based management and observability platform for your Hot projects. It provides visibility into executions, events, and streams, along with project configuration and team management.

Access the Hot App:

• Local development: Run hot dev and open http://localhost:4680
• Hot Cloud: Sign up at app.hot.dev

Navigation & Scope

The sidebar provides navigation to the environment-scoped features of the Hot App. A sticky header above the page content contains two key selectors:

• Organization - Select which organization to view
• Environment - Select which environment within that organization (e.g., development, staging, production)

These selectors control the scope of operational pages. When you select an organization and environment, runs, tasks, events, streams, projects, files, stores, and other environment data are filtered to that context. Account, organization, team, and billing pages are not environment-scoped.

From each selector dropdown, you can also access management screens:

• Organizations - Create new organizations, manage users, configure teams, and handle billing
• Environments - Create new environments, edit environment settings

This scoping model keeps your data organized and allows you to easily switch between different projects or deployment stages.

Dashboard

The Dashboard is your home screen, providing an at-a-glance overview of your Hot environment:

• Issues banner - A compact alert bar linking directly to failed runs, failed tasks, unhandled events, build version warnings, and failing agents
• Hero metrics - Four cards showing totals and status breakdowns for Runs, Tasks (including CUS), Events, and Streams
• Agent Health - A rollup of healthy, degraded, failing, and idle agents, followed by up to five agents that need attention
• Activity charts - A scrollable grid covering run activity and types, run waiting versus execution latency, task activity and CUS, task waiting versus execution latency, event activity and types, and stream activity and composition
• Issues - Expanded tables for failed runs, failed tasks, and unhandled events

Use the filters at the top (project, time range, granularity) to scope the data. The dashboard auto-refreshes via server-sent events (SSE), and all charts and metrics update when filters change.

Runs

The Runs view shows all executions of your Hot code:

• Status - Running, succeeded, failed, cancelled, or pending retry
• Type - How it was triggered (call, event, schedule, run, eval, repl)
• Duration - How long the run took
• Timestamp - When the run started

Click any run to see the full execution trace, including:

• Input parameters
• Each expression evaluated with timing
• Return values or error details
• File attachments (if any)
• Parent/child run hierarchy

You can retry failed runs or rerun any completed run directly from the detail view.

Run states

State	Description
running	Run is currently executing
succeeded	Run completed successfully
failed	Run failed with an error
cancelled	Run was cancelled
pending_retry	Run failed and is waiting for an automatic retry

Tasks

The Tasks view shows asynchronous and container-based jobs:

• Status - Queued, running, completed, failed, timed out, or cancelled
• Duration - How long the task ran
• CUS - Compute units consumed by the task
• Timestamp - When the task was created

Click any task to see:

• Task configuration and metadata
• Timing breakdown (queue time, container pull, execution)
• Call data from the task's execution
• Container logs (for ::hot::box tasks)
• Stream graph showing the task in context with its originating run

Task states

State	Description
queued	Task is waiting to be picked up
running	Task is currently executing
completed	Task finished successfully
failed	Task failed with an error
timed_out	Task exceeded its timeout
cancelled	Task was cancelled before completion

Events

The Events view shows all events received by your Hot application:

• Event type - The event name (e.g., user:created)
• Payload - The event data
• Handled status - Whether the event triggered a handler
• Timestamp - When the event was received

Click any event to see:

• Full event payload
• Which runs were triggered by this event
• Event metadata

Events are the primary way to trigger Hot functions. See Events & Handlers for more on defining event handlers.

Streams

Streams group related runs and events together, providing a unified view of a logical workflow or request. When a run triggers other runs or emits events, they're all linked under the same stream.

• Stream ID - Unique identifier for the stream
• Run count - Number of runs in this stream
• Event count - Number of events in this stream
• Timeline - Visual flow of runs and events

Streams are especially useful for tracing complex workflows that span multiple function calls and events.

Workflows & Agents

The Workflows & Agents view brings together named workflows, agents, and project-level workflows inferred from deployed handlers, triggers, and sends.

• All Workflows — Cards identify each item as a workflow, agent, or unnamed workflow group and show its name, namespace, description, tags, handler count, project, and recent health when applicable. Search by name, namespace, or project, or filter agents by health status.
• Graph — The separate Graph tab shows topology across workflows and agents. Filter by workflow, agent, project, or tag, search for nodes, change the graph direction, and open the inspector.
• Agent details — Click an agent to open its default Graph tab, an interactive topology visualization of the agent's handlers, triggers, and event sends. Click a node to inspect its namespace, source location, description, retry configuration, and handled or sent events. Additional tabs show Handlers, Runs, and Streams.
• Dashboard health widget — The main Dashboard summarizes healthy, degraded, failing, and idle agents for the selected window and lists up to five degraded or failing agents.

Agents are defined using agent metadata on types and meta {agent: TypeName} on handler functions. See Agents for the full definition and patterns.

Files

The Files view lets you browse and download files stored by your Hot functions:

• View file metadata (size, content type, timestamps)
• Download files directly
• See which run created each file

Files can be created in your Hot code using functions in the ::hot::file namespace.

Stores

The Stores view lets you inspect persistent maps created with ::hot::store:

• Search stores by name and view entry count, size, creation time, embedding configuration, and text-search support
• Open a store to search its keys and values and inspect individual entries
• Administrators can reveal values, which are hidden by default, and delete entries

Stores are scoped to the selected organization and environment. They are created automatically when Hot code first uses a ::hot::store/Map.

Scheduled Runs

The Scheduled Runs view shows all functions with schedule metadata:

• Function and schedule - The scheduled function and cron expression
• Configuration - Schedule type, retry policy, source location, and active status
• Execution log - Recent scheduled executions with scheduled and actual execution times, event and stream links, and backfill status

See Schedules for more on defining scheduled functions.

Event Handlers

The Event Handlers view lists all functions that handle events:

• Event pattern - Which events this handler responds to
• Function - The handler function name
• Project - Which project contains this handler

MCP Services

The MCP Services view groups functions exposed as Model Context Protocol tools into service cards. Search the overview by service name or project, then open a service to see its endpoint and a searchable table of tools, including project, tool and function names, authentication, description, and source location.

MCP tools are driven by mcp metadata in your source code — they're automatically registered on deploy and unregistered when removed. See MCP Services for how to define tools and configure the MCP endpoint.

Webhooks

The Webhooks view lists all functions exposed as webhook endpoints. Endpoints are grouped by service, showing method, path, function, auth mode, and description. Each service detail page shows the base URL for the webhook.

Webhook endpoints are driven by webhook metadata in your source code — they're automatically registered on deploy and unregistered when removed. See Webhooks for how to define endpoints and configure authentication.

Alerts

The Alerts view lets you configure monitoring and notifications for your Hot applications — run failures, deployment issues, and custom alerts from your code. Configure destinations (email, Slack, PagerDuty, webhook), channels, and subscriptions.

See Alerts for the full documentation on channels, destinations, subscriptions, and sending alerts from code.

Projects

Projects represent deployed Hot applications. The project list and detail pages show:

• Active status - Whether the project is currently active
• Overview - Project identifiers, current deployed build, timestamps, and activation controls
• Builds - Deployment history with the ability to deploy previous builds

Use the global Docs page to browse auto-generated documentation for deployed projects.

Context Variables

Context Variables store configuration values accessible to your Hot code at runtime—things like API keys, feature flags, and environment-specific settings.

Context variables can be defined at two levels:

• Environment level - Shared across all projects in that environment
• Project level - Specific to a single project, overrides environment-level values

This hierarchy lets you set common defaults at the environment level while allowing individual projects to override specific values when needed.

Access context values in your Hot code:

api-key ::hot::ctx/get("API_KEY")
debug-mode ::hot::ctx/get("DEBUG", false)

Local Development

hot dev loads hot/ctx.hot. Use it to map values from .env to the context keys your Hot code reads:

::hot::run::ctx ns
::env ::hot::env

::hot::ctx/set({
  "anthropic.api.key": ::env/get("ANTHROPIC_API_KEY", "")
})

hot init adds both .env and hot/ctx.hot to .gitignore.

Deployed Projects

Deployed projects do not use hot/ctx.hot. Add the same keys under Context Variables in the Hot App. Environment-level values apply to every project in the environment; project-level values override them. Hot stores these values encrypted in the database and loads them at runtime.

Docs

The Docs section provides auto-generated documentation for your deployed Hot projects:

• Browse namespaces and functions
• View function signatures and types
• Search across your codebase
• Explore package dependencies

Each build includes documentation for both your project's source code and the specific package dependencies included in that build. This ensures the docs always match the exact versions deployed.

The hot-std standard library documentation is always available publicly at hot.dev, independent of any specific build.

API Keys

API Keys authenticate your requests to the Hot API with configurable permissions and fine-grained resource/action scoping.

Service Keys

Service Keys are customer-facing credentials with granular permissions, designed for external integrations and white-label use.

See Authentication for full documentation on API keys, service keys, sessions, and the permissions model.

Custom Domains

Custom Domains let you map your own domain names to your Hot Dev environment for branded MCP, webhook, and API endpoints.

See Custom Domains for setup instructions, DNS configuration, and verification.

Access Attribution

Run and event detail pages display access attribution when the action was initiated via the API. This shows which credential (API key, service key, or session) made the request, along with the IP address, user agent, and HTTP request details.

For actions initiated from the dashboard (e.g., re-running a function), the originating user is shown instead.

Organizations & Teams

Hot supports multi-tenant organization structures:

• Organizations - Top-level accounts with billing and user management
• Child organizations - Workspaces an organization creates and manages, for example one per customer
• Teams - Groups within an organization for access control
• Environments - Isolated execution contexts (dev, staging, production)

User Roles

Role	Permissions
Admin	Full access, manage users, billing, projects, settings
Member	View and execute, limited configuration

Child Organizations

An organization account can own child organizations. Each child has its own environments, deployments, credentials, and data. The parent keeps billing and account members, and its plan limits are shared with its children. The plan can also limit how many children an account has. A key for one child can't reach the parent or another child.

Root administrators manage children from the organization's Children tab:

• Create a child. Enter a name, a handle, and an optional customer reference. Handles are unique across Hot.
• Grant access. Root administrators can open every child. Give other account members access to a child as a Member or an Administrator, or remove their access.
• Change status. A child is active, suspended, or archived. Suspending a child holds its new work. Restore an archived child to suspended before you activate it. Suspending the account itself holds new work in every child.
• Issue management credentials. A management credential lets your own systems create and manage children through the management API. Choose its capabilities, the children it can reach (all children is required to create new ones), an expiry of up to 90 days, and a permission ceiling for the runtime keys it issues. The token is shown once. Revoking it also disables the keys issued through it.

The tab also shows an account overview: runs, failures, file bytes, and environments for the root and each child.