Target Management

Manage where your code runs — locally or on remote servers.

What are Targets

A target is a machine where Berth can deploy and run code. Every Berth installation has a built-in local target. You can add remote targets by connecting to Linux servers running the Berth agent.

Local Target

The local target is built-in and always available. It runs on your Mac and requires no configuration. All runtimes (Python, Node.js, Go, etc.) must be installed on your Mac.

The local target is the default for all commands unless you specify --target.

Adding Remote Targets

In the App

1. Go to Targets in the sidebar
2. Click Add Target
3. Enter the target name and connection details:
   • Name: A friendly name (e.g. "my-vps", "staging")
   • Host: Agent IP address or hostname
   • Port: Agent port (default: 50051)
   • NATS Agent ID: (optional) For NATS-enabled targets
4. If using NATS, enter the pairing code from the agent logs

Via CLI

berth targets add my-vps --host 192.168.1.100
berth targets add staging --host staging.example.com --port 50051

Via MCP

berth_add_target(name: "my-vps", host: "192.168.1.100", port: 50051)

NATS-Enabled Targets

Targets with a NATS Agent ID route all communication through Synadia Cloud. This means:

• Zero inbound ports on either side
• Works behind NAT, firewalls, and VPNs
• No direct network path needed between your Mac and the server

NATS-enabled targets display a green NATS badge in the targets list.

Enabling NATS on a Target

1. Install the agent with NATS credentials (see Agent Installation)
2. Configure NATS credentials in the desktop app Settings
3. When adding the target, enter the agent's NATS Agent ID
4. Complete the pairing process

sudo journalctl -u berth-agent | grep "agent_id"

Health Checks

Check if a remote agent is online and get system information:

In the App

The targets list shows a status indicator for each target:

• Green — Agent online and healthy
• Red — Agent offline or unreachable
• Gray — Status unknown (not checked yet)

Via CLI

berth targets ping my-vps

Returns: agent version, uptime, operating system, architecture, CPU usage, and memory usage.

Via MCP

berth_list_agents()

Pings all configured targets and returns their health status.

Deploying to Targets

In the App

In any project's detail view, use the target dropdown to select where to run it. Click Run and Berth handles the rest — packaging code, sending it to the agent, installing dependencies, and streaming logs back.

Via CLI

# Deploy code to a remote target
berth deploy ./my-project --target my-vps

# Run an existing project on a remote target
berth run my-project --target my-vps

# Stop on a remote target
berth stop my-project --target my-vps

# View remote logs
berth logs my-project --target my-vps --follow

What Happens During Remote Deploy

1. Berth packages your code into a tar archive
2. The archive is sent to the agent (via NATS or gRPC)
3. The agent extracts the code to ~/.berth/deploys/{project_id}/v{n}/
4. Dependencies are installed (pip install, npm install, etc.)
5. The project runs and logs stream back in real-time

Removing Targets

In the App

In the targets list, click the delete button next to the target you want to remove.

Via CLI

berth targets remove my-vps

Via MCP

berth_remove_target(name: "my-vps")