Berth Remote Agent

Architecture, protocol, deployment, and security reference for the Berth agent system.

Overview

The Berth Remote Agent is a persistent Rust binary that runs on Linux servers as a systemd service. It receives code deployments from the Berth macOS app (or CLI) over gRPC or NATS, manages execution history in a local SQLite database, runs scheduled jobs independently, publishes services via cloudflared tunnels, and supports remote self-upgrade.

Architecture

System Topology

Component Interaction

gRPC Protocol

Defined in proto/berth.proto. The agent implements a single gRPC service with 16 RPCs:

Service: AgentService

Message Definitions

ExecuteRequest

message ExecuteRequest {
  string project_id  = 1;  // Unique project identifier
  string runtime     = 2;  // "python", "node", "go", "shell", "rust"
  string entrypoint  = 3;  // Filename: "main.py", "index.js", "run.sh"
  bytes  code        = 4;  // Inline code content (the file bytes)
  string working_dir = 5;  // Fallback working directory (if no inline code)
}

ExecuteResponse (streamed)

message ExecuteResponse {
  string stream    = 1;  // "stdout" or "stderr"
  string text      = 2;  // One line of output
  string timestamp = 3;  // RFC 3339 timestamp
}

HealthResponse

message HealthResponse {
  string agent_version    = 1;  // e.g. "0.1.9"
  string status           = 2;  // "healthy"
  uint64 uptime_seconds   = 3;  // Seconds since agent started
  string os               = 6;  // e.g. "linux" (from std::env::consts::OS)
  string arch             = 7;  // e.g. "x86_64" (from std::env::consts::ARCH)
  repeated string tunnel_providers = 9;  // e.g. ["cloudflared"] — installed tunnel binaries
}

StatusResponse

message StatusResponse {
  string agent_id             = 1;  // Hostname of the server
  string status               = 2;  // "running"
  double cpu_usage            = 3;  // Global CPU % (via sysinfo)
  uint64 memory_bytes         = 4;  // Used memory in bytes
  repeated ProjectStatus projects = 5;
}

NATS Command Channel

The primary transport for remote agent communication. Both the desktop app and the agent connect outbound to Synadia Cloud — zero inbound ports required on either side. Works behind NAT, firewalls, and across different networks.

AgentTransport Trait

Defined in crates/berth-core/src/agent_transport.rs. A unified async trait that abstracts the transport layer:

// Both AgentClient (gRPC) and NatsAgentClient implement this trait.
// Transport is selected per target based on the nats_enabled flag.
//
// If target has nats_enabled=true + nats_agent_id → NatsAgentClient
// Otherwise → AgentClient (gRPC fallback)

NatsCommandKind

The NatsCommandKind enum defines 15 command variants sent over NATS:

Subject Hierarchy

berth.<agent_id>.cmd.<type>         # Commands from desktop → agent
berth.<agent_id>.resp.<request_id>  # Streaming responses from agent → desktop
berth.<agent_id>.events             # Store-and-forward events (JetStream)
berth.<agent_id>.logs               # Log streaming (JetStream)
berth.<agent_id>.heartbeat          # Periodic heartbeat (JetStream)

NatsCommandHandler (Agent Side)

Defined in crates/berth-agent/src/nats_cmd_handler.rs. Subscribes to berth.<agent_id>.cmd.> and dispatches incoming commands to the corresponding PersistentAgentService::do_*() methods. Uses request-reply for simple RPCs and publish+subscribe for streaming operations (Execute, Deploy, Logs).

NatsAgentClient (Desktop Side)

Defined in crates/berth-core/src/nats_cmd_client.rs. Implements the AgentTransport trait over NATS. Uses request-reply for unary RPCs and publish+subscribe for streaming responses.

Transport Selection

The get_agent_client() function in agent_transport.rs returns a Box<dyn AgentTransport>. If the target has nats_enabled=true and a nats_agent_id, communication routes through NATS. Otherwise, it falls back to direct gRPC.

Public URL Publishing

Running projects can be published to a public URL via cloudflared tunnels. The architecture is pluggable — adding a new tunnel provider (ngrok, bore, custom) requires changes to one file only (tunnel.rs).

TunnelManager

Defined in crates/berth-core/src/tunnel.rs. Manages the lifecycle of tunnel processes:

• TunnelProvider enum: Pluggable provider selection. Only cloudflared implemented initially.
• Spawn: Runs cloudflared tunnel --url http://127.0.0.1:{port}, parses the public URL from stderr (30s timeout).
• Stderr drain: A background task continuously drains cloudflared's stderr to prevent SIGPIPE.
• Lifecycle: Active tunnels are kept in memory. Stopping a project also stops its tunnel.

Capability Detection

The HealthResponse includes a tunnel_providers field (repeated string) that reports which tunnel binaries are installed on the agent. The available_providers() function checks for installed binaries at health-check time.

Full Stack Integration

SQLite Storage

Two columns on the projects table: tunnel_url and tunnel_provider. Updated via set_tunnel_url() and clear_tunnel_url() store methods.

Self-Upgrade

The agent supports remote self-upgrade using a cloudflared-inspired model: download binary, verify, atomic swap, exit with code 42, systemd restarts with the new binary. Tested end-to-end (v0.1.7 → v0.1.8).

Upgrade Flow

systemd Configuration for Upgrade

SuccessExitStatus=42                              # Prevents rate-limiting on intentional restart
ExecStopPost=+/usr/local/lib/berth/rollback.sh    # Runs as root — restores old binary on failure

Rollback

• If probation fails, the agent exits with code 1.
• The rollback.sh script (runs as root via + prefix) restores berth-agent.old to berth-agent.
• Maximum 2 rollback attempts to prevent infinite loops.
• Backup binary always preserved as berth-agent.old.

CLI and Remote Upgrade

# CLI self-serve upgrade (on the agent machine)
berth-agent update [--version X.Y.Z] [--yes]

# Remote upgrade via NATS (desktop sends URL + checksum, agent downloads and swaps)
NatsCommandKind::UpgradeDownload { url, checksum }

Environment Variables

Per-project environment variables are stored on the desktop side only and passed to the agent at runtime. Values are never persisted on the remote agent.

Architecture

• Storage: project_env_vars table in desktop SQLite. Methods: set_env_var(), get_env_vars(), delete_env_var().
• Runtime delivery: Env vars loaded from store and passed via ExecuteParams.env_vars HashMap at execute time.
• Log masking: Values of 3 or more characters are replaced with *** in all log output, using longest-first matching to prevent partial leaks. Implemented in crates/berth-core/src/env.rs.
• .env import: parse_dotenv() in env.rs handles comments, quoted values, and export prefix. Import merges via upsert.
• All values treated as secrets: No "secret" vs "non-secret" distinction. Every value is masked.

Interfaces

Service Mode

Projects can run in oneshot mode (run once, exit) or service mode (keep running, auto-restart on crash).

Configuration

• run_mode field on the Project model: oneshot (default) or service.
• service_port field for web services — used by tunnel publishing to know which port to expose.

Supervisor Loop

When run_mode = service, the agent's supervisor loop monitors the spawned process:

• Auto-restart: On unexpected exit (non-zero or signal), the process is restarted automatically.
• Exponential backoff: Restart delay starts at 1 second and doubles on each consecutive failure, capped at 60 seconds. Resets after a period of stable running.
• Uptime tracking: Total uptime and restart count are tracked per project.
• Graceful stop: The Stop command terminates the supervisor loop, preventing further restarts.

Data Flow

Remote Execution Flow

When a user clicks Run with a remote target selected in the UI:

Sequence Diagram

Deployment

Method 1: Build from Source

For development and testing. Requires Rust toolchain and protoc on the target server.

# On the Linux server:
sudo apt install -y protobuf-compiler build-essential
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source ~/.cargo/env

# Copy source and build
rsync -avz --exclude target --exclude node_modules your-mac:~/berth/ ~/berth/
cd ~/berth
cargo build -p berth-agent --release

# Run (bind to all interfaces for network access)
./target/release/berth-agent --listen-all --port 50051

Method 2: Install Script

For production servers. Downloads a pre-built binary and installs as a systemd service.

# Install
curl -sSL https://get.berth.dev | sudo bash

# Uninstall
curl -sSL https://get.berth.dev | sudo bash -s -- --uninstall

The install script (scripts/install-agent.sh) performs:

systemd Service Configuration

[Unit]
Description=Berth Agent
After=network.target

[Service]
Type=simple
User=berth
ExecStart=/usr/local/bin/berth-agent --port 50051
Restart=always
RestartSec=5
SuccessExitStatus=42
ExecStopPost=+/usr/local/lib/berth/rollback.sh
Environment=RUST_LOG=info

[Install]
WantedBy=multi-user.target

Post-Install Commands

# Check status
systemctl status berth-agent

# View logs
journalctl -u berth-agent -f

# Restart
sudo systemctl restart berth-agent

Method 3: Register in Berth App

After the agent is running, register it as a target:

# Via CLI
berth targets add my-server --host 192.168.1.100 --port 50051
berth targets ping my-server

# Via UI
# Targets page → + Add Target → fill name/host/port → Add → Ping
# Optional: enter NATS Agent ID for zero-port communication

Agent CLI Flags

Security

Current Security Model

mTLS Infrastructure (Implemented, Not Yet Wired)

The TLS module (crates/berth-core/src/tls.rs) provides certificate generation and tonic TLS configuration, ready to be activated:

Certificate Chain

TLS Functions

Enabling mTLS (When Ready)

// Agent server startup (main.rs):
let ca_pem = fs::read_to_string("ca.crt")?;
let server_bundle = tls::load_bundle("server")?;
let tls_config = tls::server_tls_config(&server_bundle, &ca_pem)?;

Server::builder()
    .tls_config(tls_config)?
    .add_service(AgentServiceServer::new(service))
    .serve(addr).await?;

// App client connection (agent_client.rs):
let ca_pem = fs::read_to_string("ca.crt")?;
let client_bundle = tls::load_bundle("client")?;
let tls_config = tls::client_tls_config(&client_bundle, &ca_pem)?;

Channel::from_shared(endpoint)?
    .tls_config(tls_config)?
    .connect().await?;

Credential Storage

The credentials module (crates/berth-core/src/credentials.rs) stores secrets in the macOS Keychain:

Security Recommendations

• Use NATS transport: NATS uses TLS to Synadia Cloud, providing encrypted communication without additional setup.
• LAN only for gRPC: Without mTLS, only use direct gRPC on trusted networks.
• SSH tunnel: For internet-facing gRPC agents, use ssh -L 50051:localhost:50051 user@server and connect to localhost:50051.
• Firewall: Restrict port 50051 to known IPs via ufw or security groups.
• Agent user: The install script creates a berth system user with no shell — processes run without root privileges.
• Env var masking: All environment variable values are masked in logs automatically. Values are never persisted on the remote agent.

Agent Binary

Source Location

crates/berth-agent/
├── Cargo.toml               # Deps: berth-core, tonic, clap, sysinfo, rusqlite, chrono, uuid
├── build.rs                 # Compiles berth.proto via tonic-build
└── src/
    ├── main.rs              # CLI, SQLite init, gRPC server, NATS handler, scheduler loop spawn
    ├── service.rs           # Legacy re-export (AgentServiceImpl from berth-core)
    ├── persistent_service.rs # PersistentAgentService (16 RPCs with SQLite persistence)
    ├── agent_store.rs       # AgentStore: SQLite at ~/.berth/agent.db (5 tables)
    ├── agent_scheduler.rs   # Independent scheduler (tick every 30s, runs cron jobs)
    ├── nats_cmd_handler.rs  # NATS command subscriber and dispatcher
    ├── nats_publisher.rs    # NATS event/log/heartbeat publisher
    └── update.rs            # CLI `berth-agent update` self-upgrade command

Process Management

The agent uses a HashMap<String, RunningChild> protected by a tokio::sync::Mutex to track running processes:

struct RunningChild {
    abort_handle: tokio::task::AbortHandle,
    started_at: chrono::DateTime<chrono::Utc>,
}

// On Execute: insert(project_id, child)
// On Stop:    remove(project_id) → abort_handle.abort()
// On exit:    remove(project_id) automatically
// Service mode: supervisor loop re-inserts on crash (with backoff)

Runtime Support

Resource Monitoring

The Status RPC reports real system metrics via the sysinfo crate:

• CPU: Global CPU usage percentage
• Memory: Used memory in bytes
• Hostname: System hostname (used as agent_id)
• Running projects: List of active project_ids with start times

Client Library

The gRPC client (crates/berth-core/src/agent_client.rs) is used by both the Tauri app and the CLI:

use berth_core::agent_client::AgentClient;

// Connect
let mut client = AgentClient::connect("http://192.168.1.100:50051").await?;

// Health check
let health = client.health().await?;
println!("v{}, uptime {}s", health.version, health.uptime_seconds);

// Execute code remotely
let code = std::fs::read("main.py")?;
let logs = client.execute(
    "my-project",    // project_id
    "python",        // runtime
    "main.py",       // entrypoint
    "/tmp",          // working_dir
    Some(&code),     // inline code bytes
).await?;

for line in &logs {
    println!("[{}] {}", line.stream, line.text);
}

// Stop
client.stop("my-project").await?;

// System status
let status = client.status().await?;
println!("CPU: {:.1}%, Memory: {}MB", status.cpu_usage, status.memory_bytes / 1024 / 1024);

UI Integration

Target Selector (ProjectDetail page)

The project detail view shows pill-style target buttons when remote targets are configured:

Tauri Commands

Event Bridge

Remote execution reuses the same Tauri events as local execution — the Terminal component needs no changes:

Current Limitations

Roadmap

Berth Remote Agent Documentation — Updated March 2026