Berth

Mac-native deployment control plane for AI-generated code. — v0.5.1

System Architecture

Workspace Crates

Data Flow

Project Execution Flow

Project Creation Flow

Rust Crates Detail

berth-core::project

pub struct Project {
    pub id: Uuid,
    pub name: String,
    pub path: String,
    pub runtime: Runtime,
    pub entrypoint: Option<String>,
    pub status: ProjectStatus,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

pub enum ProjectStatus {
    Idle,       // Not running
    Running,    // Process active
    Stopped,    // Manually stopped
    Failed,     // Non-zero exit code
}

impl Project {
    pub fn new(name: String, path: String, runtime: Runtime) -> Self
    // Generates UUID v4, sets status to Idle, timestamps to now
}

berth-core::runtime

pub enum Runtime {
    Python, Node, Go, Rust, Shell, Unknown,
}

pub struct RuntimeInfo {
    pub runtime: Runtime,
    pub version_file: Option<String>,
    pub entrypoint: Option<String>,
    pub confidence: f32,          // 0.0 - 1.0
    pub dependencies: Vec<String>,
    pub scripts: HashMap<String, String>,
}

pub fn detect_runtime(path: &Path) -> RuntimeInfo

Detection Matrix

berth-core::executor

pub struct LogLine {
    pub stream: LogStream,        // Stdout or Stderr
    pub text: String,
    pub timestamp: DateTime<Utc>,
}

pub enum LogStream { Stdout, Stderr }

pub async fn spawn_and_stream(
    runtime: Runtime,
    entrypoint: &str,
    working_dir: &str,
) -> anyhow::Result<(Child, mpsc::Receiver<LogLine>)>

Command Mapping

All commands run with kill_on_drop(true), piped stdout/stderr, and two background tokio tasks reading into a 256-capacity mpsc channel.

berth-core::store

pub struct ProjectStore { conn: Connection }

impl ProjectStore {
    pub fn open(path: &str) -> Result<Self>
    pub fn open_in_memory() -> Result<Self>
    pub fn list(&self) -> Result<Vec<Project>>
    pub fn insert(&self, project: &Project) -> Result<()>
    pub fn get(&self, id: Uuid) -> Result<Option<Project>>
    pub fn update_status(&self, id: Uuid, status: ProjectStatus) -> Result<()>
    pub fn record_run_start(&self, id: Uuid) -> Result<()>
    pub fn record_run_end(&self, id: Uuid, exit_code: Option<i32>) -> Result<()>
    pub fn delete(&self, id: Uuid) -> Result<()>

    // Schedule CRUD
    pub fn insert_schedule(&self, schedule: &Schedule) -> Result<()>
    pub fn list_schedules(&self) -> Result<Vec<Schedule>>
    pub fn get_schedules_for_project(&self, project_id: Uuid) -> Result<Vec<Schedule>>
    pub fn update_schedule_after_run(&self, ...) -> Result<()>
    pub fn set_schedule_enabled(&self, id: Uuid, enabled: bool) -> Result<()>
    pub fn delete_schedule(&self, id: Uuid) -> Result<()>
}

Database Schema

SQLite — ~/Library/Application Support/com.berth.app/berth.db

Status State Machine

Agent SQLite — ~/.berth/agent.db (remote agent only)

Column Formats

Tauri Commands

Managed State

// Embedded local agent (in-process, UDS transport)
// AgentClient connects via ~/.berth/agent.sock
// Lockfile coordination via ~/.berth/agent.lock
// No ProcessRegistry — agent owns all process lifecycle

pub struct AppState {
    pub store: ProjectStore,
    // Agent started on app init, shared across commands
}

Tauri Events

Event Payloads

// LogEvent (Rust -> Frontend)
{
  "project_id": "8bda6c73-...",
  "stream": "stdout",          // "stdout" | "stderr"
  "text": "[1/10] AAPL: $215.13 (+4.64%)",
  "timestamp": "2026-03-06T09:15:42.123+00:00"
}

// StatusEvent (Rust -> Frontend)
{
  "project_id": "8bda6c73-...",
  "status": "running"          // "idle" | "running" | "stopped" | "failed"
}

Frontend Components

Component Tree

TypeScript Interfaces

interface Project {
  id: string;
  name: string;
  path: string;
  runtime: string;
  entrypoint: string | null;
  status: "idle" | "running" | "stopped" | "failed";
  created_at: string;
  updated_at: string;
}

interface RuntimeInfo {
  runtime: string;
  version_file: string | null;
  entrypoint: string | null;
  confidence: number;           // 0.0 - 1.0
}

interface LogEvent {
  project_id: string;
  stream: "stdout" | "stderr";
  text: string;
  timestamp: string;
}

interface StatusEvent {
  project_id: string;
  status: "idle" | "running" | "stopped" | "failed";
}

Invoke Functions

listProjects(): Promise<Project[]>
createProject(name: string, path: string): Promise<Project>
detectRuntime(path: string): Promise<RuntimeInfo>
deleteProject(id: string): Promise<void>
runProject(id: string): Promise<void>
stopProject(id: string): Promise<void>

Design Tokens

Dark Mode (default)

Light Mode

Typography

font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text",
             "Helvetica Neue", Helvetica, Arial, sans-serif;
-webkit-font-smoothing: antialiased;
user-select: none;

Protobuf / gRPC

syntax = "proto3";
package berth;

service AgentService {
  // Core RPCs (Phase 1-3)
  rpc Execute(ExecuteRequest)           returns (stream ExecuteResponse);
  rpc Status(StatusRequest)             returns (StatusResponse);
  rpc StreamLogs(LogStreamRequest)      returns (stream LogStreamResponse);
  rpc Stop(StopRequest)                 returns (StopResponse);
  rpc Health(HealthRequest)             returns (HealthResponse);
  rpc Deploy(DeployRequest)             returns (DeployResponse);

  // Persistent Agent RPCs (Phase 3.5)
  rpc GetExecutions(GetExecutionsRequest)       returns (GetExecutionsResponse);
  rpc GetExecutionLogs(GetExecutionLogsRequest)  returns (stream LogStreamResponse);
  rpc GetEvents(GetEventsRequest)               returns (GetEventsResponse);
  rpc AckEvents(AckEventsRequest)               returns (AckEventsResponse);
  rpc AddSchedule(AddScheduleRequest)           returns (AddScheduleResponse);
  rpc RemoveSchedule(RemoveScheduleRequest)     returns (RemoveScheduleResponse);
  rpc ListSchedules(ListSchedulesRequest)       returns (ListSchedulesResponse);
  rpc Upgrade(stream UpgradeChunk)              returns (UpgradeResponse);
}

Message Types

MCP Server Done

26 tools implemented via JSON-RPC 2.0 stdio transport (MCP protocol version 2024-11-05). E2E tested: deploy inline code, run, capture output, delete.

Transport: stdio (primary, for Claude Code). HTTP via axum planned for Phase 3.

Claude Code integration: .mcp.json config included in repo root.

MCP Architecture

crates/berth-mcp/
  src/
    main.rs       -- Entry point, tokio::main, calls server::run_stdio()
    lib.rs        -- Module exports (protocol, server, tools)
    protocol.rs   -- JSON-RPC 2.0 types, MCP types (InitializeResult, Tool, CallToolResult)
    server.rs     -- Stdio loop: read line -> parse JSON-RPC -> dispatch -> write response
    tools.rs      -- Tool definitions (list_tools) + handlers (call_tool)

Public URL Publishing Done

Berth can publish any running project to a public URL via pluggable tunnel providers. Zero Berth-side infrastructure — tunnels run on the user's machine.

Architecture

Key Components

Provider Design (Pluggable)

Adding a new provider (e.g. ngrok) requires changes to one file only: tunnel.rs.

1. Add variant to TunnelProvider enum
2. Add match arm in TunnelManager::start()
3. Implement start_ngrok() with provider-specific URL parsing
4. Add detection in available_providers()

No proto changes, no transport changes, no new Tauri commands needed.

Proto Messages

rpc Publish(PublishRequest) returns (PublishResponse);
rpc Unpublish(UnpublishRequest) returns (UnpublishResponse);

message PublishRequest {
  string project_id = 1;
  uint32 port = 2;
  string provider = 3;       // "cloudflared" (default)
  string provider_config = 4; // reserved for future provider options
}
message PublishResponse {
  bool success = 1;
  string url = 2;            // e.g. "https://random-words.trycloudflare.com"
  string message = 3;
  string provider = 4;
}
// HealthResponse includes: repeated string tunnel_providers = 9;

Database

-- Added columns to projects table:
ALTER TABLE projects ADD COLUMN tunnel_url TEXT;
ALTER TABLE projects ADD COLUMN tunnel_provider TEXT;

-- Methods: store.set_tunnel_url(), store.clear_tunnel_url()

CLI Done

berth list                                    # List all projects (table format)
berth deploy <path> [--name N] [--target T]   # Create project + run
berth run <project>                           # Run by name or UUID
berth stop <project>                          # Stop a project
berth logs <project> [-f|--follow]            # Run and capture output
berth status <project>                        # Detailed project info
berth import <path> [--name N]                # Import code as project
berth detect <path>                           # Detect runtime + deps + scripts
berth delete <project>                        # Delete a project
berth health                                  # System health check
berth targets list                            # List deploy targets
berth targets add <name> --host <host>       # Add target (Phase 3)
berth schedule add <project> --cron <expr>   # Add schedule (@every 5m, @hourly, etc.)
berth schedule list                           # List all schedules
berth schedule remove <id>                    # Remove a schedule
berth schedule enable <id>                    # Enable a schedule
berth schedule disable <id>                   # Disable a schedule
berth schedule tick                           # Run one scheduler tick
berth publish <project> --port 8080           # Publish via cloudflared tunnel
berth unpublish <project>                     # Stop the public URL tunnel

File Map

Roadmap & Status

Phase 1: Foundation Complete

Phase 2: MCP + CLI Complete

Phase 3: Remote Agents Complete

Persistent remote agent with SQLite store, 14 gRPC RPCs, agent-side scheduler, store-and-forward events, remote upgrade, dependency install during deployment. Agent install script, gRPC communication, remote deploy, agent health monitoring, mDNS LAN discovery, agent-only execution architecture (UDS for local, TCP gRPC for remote). NATS relay for NAT traversal, mTLS, berth-proto shared contract crate, message authentication, environment variable management, template store, opt-in telemetry, onboarding flow. Deployed and verified on remote Linux server.

Phase 4: Cloud Targets Not Started

AWS Lambda, Cloudflare Workers, deployment history, code signing, Homebrew cask.

Phase 5: Growth Not Started

Pro tier, team features, web dashboard, Windows/Linux builds.

Tech Stack Summary

Berth v0.5.1 — Documentation generated March 2026
github.com/berth-app/berth