@mastractl/server

@mastractl/server

The mastractl server runtime — Hono API, agent registry, heartbeat engine, channel adapters (Telegram, Slack), and MCP control plane.

This package is published to npm so mastractl dev (the dockerless mode) can install and fork it without Docker.

Usage (dockerless)

# In your mastractl project:
npm install --save-dev @mastractl/server

# Run migrations:
node node_modules/@mastractl/server/db-migrate.mjs

# Start the server (or use `mastractl dev` which does both automatically):
node node_modules/@mastractl/server/dist/dev.js

Environment variables required:

• DATABASE_URL — Postgres connection string
• BETTER_AUTH_SECRET — 32-byte hex secret (generate with openssl rand -hex 32)
• One LLM provider key: ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, etc.

Extensibility config

Drop a mastractl.config.mjs at your project root to wire custom tools, routes, and lifecycle hooks:

/** @type {import("@mastractl/server").MastractlConfig} */
export default {
  // Inject tools into agents at boot time
  async onAgentBuild(spec, { companyId, env }) {
    if (!spec.capabilities?.includes("crm")) return {};
    // Return any Mastra-compatible tools Record
    return {};
  },

  // Mount custom Hono routes on the existing server
  onApp(app) {
    // app.route("/webhooks/stripe", stripeRoutes);
  },

  // Access the live Mastra instance after the server starts
  onReady({ mastra, logger }) {
    logger.info("server ready — wiring custom jobs");
  },
};

Pass the config path to the server via MASTRACTL_CONFIG env var (absolute path). mastractl dev detects and sets this automatically.

Packages

Package	Description
@mastractl/server	This package — server runtime
@mastractl/client	TypeScript SDK for talking to the server
@mastractl/agent	AgentSpec types + custom agent adapter
@mastractl/shared	Shared error types
mastractl	CLI (mastractl dev, mastractl run, mastractl init, ...)
create-mastractl	Project scaffolder

Requirements

• Node.js >= 22.13.0
• PostgreSQL >= 14

License

Apache-2.0 — see LICENSE.