Installation

Installing Trellis

Trellis consists of two static binaries with no external dependencies beyond tmux:

  • trellis — The main server (web UI, API, service management)
  • trellis-ctl — The command-line tool for interacting with the server

Requirements

  • tmux (required) - Terminal multiplexer for session management
  • Go 1.25+ (required) - Trellis is installed by building from source

Install tmux

Trellis requires tmux for terminal management.

macOS:

brew install tmux

Ubuntu/Debian:

sudo apt install tmux

Fedora/RHEL:

sudo dnf install tmux

Build from Source

There are currently no prebuilt binaries — install Trellis by building it from source. With Go installed, this takes under a minute:

# Clone the repository
git clone https://github.com/wingedpig/trellis.git
cd trellis

# Build both binaries
make build

# This creates:
#   trellis       - The main server
#   trellis-ctl   - The CLI tool

Verify Installation

# Check trellis version
./trellis -v

# Check tmux is available
tmux -V

Optional: Install Globally

Move the binaries to a location in your PATH:

sudo mv trellis trellis-ctl /usr/local/bin/

Or add the Trellis directory to your PATH:

export PATH="$PATH:/path/to/trellis"

AI Assistant Integration

Trellis includes a skill file that teaches AI coding assistants (Claude Code, Codex, etc.) how to use trellis-ctl effectively.

Claude Code

Trellis installs the skill automatically: on startup it writes .claude/skills/trellis/SKILL.md into the repo and every worktree (and into new worktrees as they’re created), refreshing it when the bundled version changes after an upgrade. Installed copies carry a managed-by: trellis marker; remove the marker line to take ownership of a copy and stop updates, or disable installation entirely in trellis.hjson:

agent: {
  install_skill: false
}

To install manually instead (e.g. with auto-install disabled), copy the skill file to your project’s Claude skills directory:

mkdir -p .claude/skills/trellis
cp /path/to/trellis/SKILL.md .claude/skills/trellis/SKILL.md

Or create a symlink to always use the latest version:

mkdir -p .claude/skills/trellis
ln -s /path/to/trellis/SKILL.md .claude/skills/trellis/SKILL.md

Codex

Codex uses AGENTS.md files placed in your repository. Copy the Trellis skill content to your project root:

cp /path/to/trellis/SKILL.md AGENTS.md

Or append to an existing AGENTS.md:

cat /path/to/trellis/SKILL.md >> AGENTS.md

Codex discovers AGENTS.md files hierarchically from the Git root down to your current directory, concatenating them. See the Codex AGENTS.md documentation for details.

What the Skill Provides

The skill file teaches AI assistants to:

  • Check service status and view logs
  • Filter logs by time, level, and pattern
  • Run workflows and switch worktrees
  • Debug crashes using crash reports
  • Investigate production errors with distributed tracing
  • Send notifications when tasks complete

Initialize a Project

After installation, use trellis init to create a configuration file:

cd your-project
trellis init

This interactive command walks you through:

  • Project name
  • Server port
  • Services to manage
  • Build workflow
  • Log format

The generated trellis.hjson is fully commented to help you understand and customize all options.

For manual configuration or to see what options are available, see the Configuration Reference.

Troubleshooting

tmux not found

Trellis requires tmux for terminal management. Install it using your package manager:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# Fedora/RHEL
sudo dnf install tmux

Port already in use

If port 1234 (or your configured port) is in use:

# Find what's using the port
lsof -i :1234

# Use a different port
./trellis -port 8080

Or change the port in your trellis.hjson:

server: {
  port: 8080
}

Permission denied for log files

When using file-based log viewers, ensure Trellis has read access to the log files:

# Check permissions
ls -la /var/log/myapp/

# Add user to appropriate group (example for syslog group)
sudo usermod -a -G adm $USER

SSH key prompts for remote logs

Remote log viewers and terminals use SSH. To avoid password prompts:

  1. Ensure your SSH key is added to ssh-agent: ssh-add ~/.ssh/id_rsa
  2. Verify you can connect without prompts: ssh hostname
  3. Check ~/.ssh/config for proper host configuration

Docker socket access denied

For Docker log viewers, your user needs access to the Docker socket:

# Add user to docker group
sudo usermod -a -G docker $USER

# Log out and back in, then verify
docker ps

kubectl context issues

For Kubernetes log viewers, ensure your context is set correctly:

# List contexts
kubectl config get-contexts

# Switch context
kubectl config use-context my-cluster

# Test access
kubectl get pods -n my-namespace

Services not restarting on binary change

  1. Verify watch_binary path matches the actual binary location
  2. Check the watch.debounce setting isn’t too high
  3. Ensure watching: true (the default) isn’t set to false

Next Steps

Continue to Quickstart to configure your first project.

For where Trellis stores its runtime state (crash reports, traces, tmux sessions) and how to reset it, see State and Files.