Workstation Won't Start

Port already in use

The workstation uses port 3412 by default. If another process is using it, the workstation will fail to start. Check with:

lsof -i :3412

Kill the conflicting process or configure a different port.

No .ticket-house.json found

The workstation must be started from a directory that contains (or has a parent containing) a .ticket-house.json file. Make sure you're in the right repository.

Connection Failures

Can't reach the remote server

Verify the remote URL in your .ticket-house.json is correct and the server is reachable:

curl -I https://your-server.example.com

Authentication expired

If you see authentication errors, your session may have expired. Re-run the setup script or log in again through the web UI. Session cookies are stored at ~/.ticket-house/session.

Ephemeral Key TTL & Session Timeouts

Workstation authentication uses ephemeral keys with a short time-to-live (TTL). If the workstation loses its connection to the server for longer than the TTL, it will need to re-authenticate. The workstation handles this automatically on restart.

Web UI sessions also have a configurable timeout. If you're logged out unexpectedly, the session may have expired. Log in again to refresh it.

Docker / Container Issues

Containers not provisioning

If containers aren't being created for new worktrees:

  • Verify Docker is running: docker info
  • Check that the container image builds successfully: docker build -f Containerfile -t your-image .
  • Use npx ticket-house debug-daemon to check the pool state

Worktree isolation in containers

Each container gets its own worktree mounted. If files seem shared or out of sync, check that the mount paths are correct and the container isn't reusing a stale volume.

AI Agent Can't Connect

If the AI agent reports MCP connection failures:

  1. Verify the workstation is running (npx ticket-house status)
  2. Check the MCP server configuration in .claude/settings.json
  3. Restart Claude Code to re-establish the MCP connection
  4. Run npx ticket-house debug-daemon to verify the MCP server is accepting connections