backend-setup_skill

Overview

This skill sets up a Node.js backend that runs agent runtimes using @hhopkins/agent-runtime. It covers environment configuration, implementing a PersistenceAdapter, creating the runtime, and exposing REST and WebSocket endpoints. Use it to host agent sandboxes, manage sessions, and stream agent outputs to clients.

How this skill works

You implement a PersistenceAdapter to connect sessions, transcripts, files, and agent profiles to your storage layer. The skill shows how to create and start the agent runtime with Modal credentials and optional timeouts, then expose a REST API and attach a WebSocket server to the same HTTP server. Sandboxes are created lazily on first message, and the runtime manages session lifecycle, syncing, and graceful shutdown.

When to use it

• You need a production-ready backend to host conversational agents with session persistence.
• You want a simple Node.js/TypeScript reference for integrating @hhopkins/agent-runtime.
• You must implement storage integration (in-memory, SQLite, Postgres, Supabase, etc.).
• You need REST endpoints for session lifecycle and WebSocket streaming for real-time updates.
• You plan to use Modal sandboxes and require Modal credential configuration.

Best practices

• Implement PersistenceAdapter to persist sessions, transcripts, workspace files, and agent profiles before production use.
• Use lazy sandbox creation: create session records on create, only start sandboxes on first message to save resources.
• Set sensible idleTimeoutMs and syncIntervalMs to balance resource usage and state durability.
• Protect REST endpoints with an apiKey or other authentication and validate incoming requests.
• Gracefully handle SIGTERM to close HTTP, WebSocket servers and shutdown the runtime to avoid state loss.

Example use cases

• Small dev server with in-memory PersistenceAdapter for local testing and rapid iteration.
• Single-server production using SQLite or Postgres PersistenceAdapter for durable sessions and files.
• Serverless or managed DB backends using Supabase/Convex adapters with the same runtime API.
• Real-time web client that consumes WebSocket block streaming events for UI updates.
• Automated agents that spawn subagents; use sessionManager to inspect, unload, or retrieve session state.