| commit | 138ec2436631f136dd2e8b4891211f896587ff00 | [log] [tgz] |
|---|---|---|
| author | Sean McCullough <banksean@gmail.com> | Mon Jun 02 22:42:06 2025 +0000 |
| committer | Sean McCullough <banksean@gmail.com> | Mon Jun 02 17:52:38 2025 -0700 |
| tree | 80afc394ad900e6e7a0a7b524972a303ef90ef15 | |
| parent | 457dfd12f281dbe9b1af8d1a7429f2977e234a6f [diff] |
loop: automatic host/container ssh port tunneling Fix for #47 Add comprehensive port event monitoring and automatic SSH tunnel management system that enables real-time port forwarding for container services. Container processes need automatic port forwarding when services start or stop listening on ports during agent execution. Previously, users had to manually create SSH tunnels using commands like 'ssh -L8000:localhost:8888 container', which required manual intervention and knowledge of when ports become available. - Extended PortMonitor with thread-safe event storage using circular buffer - Added PortEvent struct with type (opened/closed), port info, and timestamps - Maintained backward compatibility with existing logging functionality - Events stored in 100-item circular buffer with efficient timestamp filtering - Added /port-events endpoint in loophttp.go for container-to-host communication - Supports optional 'since' query parameter for incremental event fetching - Returns JSON array of recent port events with proper error handling - Integrated with existing Agent interface via GetPortMonitor() method - Created TunnelManager component for host-side tunnel orchestration - Polls container /port-events endpoint every 10 seconds for new events - Automatically creates SSH tunnels when ports open using same port numbers - Properly cleans up tunnels when ports close or context cancels - Skips common system ports (SSH, HTTP, SMTP) to avoid conflicts - Integrated TunnelManager into dockerimg.LaunchContainer() workflow - Starts tunnel manager alongside existing container management goroutines - Only activates when SSH is available and configured properly - Uses existing SSH infrastructure and container naming conventions - Container PortMonitor detects port changes via ss -lntu command - Events stored with RFC3339 timestamps for precise filtering - Thread-safe access patterns with dedicated mutex protection - Circular buffer prevents unbounded memory growth - RESTful GET /port-events endpoint with time-based filtering - Proper JSON encoding/decoding with error handling - Integration with existing HTTP server infrastructure - Non-blocking polling pattern with configurable intervals - Uses existing SSH theater configuration and host keys - Creates tunnels with format: ssh -L hostPort:localhost:containerPort container - Background monitoring of tunnel processes with automatic cleanup - Proper context cancellation and resource management - Added comprehensive port event storage and filtering tests - HTTP endpoint testing with mock agents and proper status codes - Verified thread-safe access patterns and circular buffer behavior - All existing loop package tests continue to pass - Confirmed HTTP endpoint returns proper JSON responses - Validated tunnel manager integrates with container launch process - Verified SSH tunnel creation follows existing authentication patterns - Build verification confirms no regressions in existing functionality - Automatic port forwarding eliminates manual SSH tunnel management - Real-time port detection provides immediate service accessibility - Transparent integration with existing Sketch container workflow - Maintains all existing SSH functionality and manual override options - Clean separation between container monitoring and host tunnel management - Extensible event-based architecture for future port-related features - Minimal performance impact with efficient polling and filtering - Robust error handling and graceful degradation when SSH unavailable This enhancement provides seamless port forwarding automation while maintaining the reliability and security of the existing SSH infrastructure, significantly improving the developer experience when working with containerized services. Co-Authored-By: sketch <hello@sketch.dev> Change-ID: s6bc363ed64835e5dk
- dockerimg/dockerimg.go[diff]
- dockerimg/tunnel_manager.go[Added - diff]
- dockerimg/tunnel_manager_test.go[Added - diff]
- loop/agent.go[diff]
- loop/port_monitor.go[diff]
- loop/port_monitor_test.go[diff]
- loop/server/loophttp.go[diff]
- loop/server/loophttp_test.go[diff]
- .github/
- .vscode/
- bin/
- browser/
- claudetool/
- cmd/
- dockerimg/
- experiment/
- git_tools/
- httprr/
- llm/
- loop/
- skabandclient/
- skribe/
- termui/
- test/
- webui/
- .clabot
- .dockerignore
- .gitignore
- CONTRIBUTING.md
- dear_llm.md
- go.mod
- go.sum
- LICENSE
- README.md
Sketch
Sketch is an agentic coding tool. It draws the 🦉
🚀 Overview
Sketch runs in your terminal, has a web UI, understands your code, and helps you get work done. To keep your environment pristine, sketch starts a docker container and outputs its work onto a branch in your host git repository.
Sketch helps with most programming environments, but Sketch has extra goodies for Go.
📋 Quick Start
go install sketch.dev/cmd/sketch@latest sketch
🔧 Requirements
Currently, Sketch runs on macOS and Linux. It uses Docker for containers.
| Platform | Installation |
|---|---|
| macOS | brew install colima (or Docker Desktop/Orbstack) |
| Linux | apt install docker.io (or equivalent for your distro) |
| WSL2 | Install Docker Desktop for Windows (docker entirely inside WSL2 is tricky) |
The sketch.dev service is used to provide access to an LLM service and give you a way to access the web UI from anywhere.
🤝 Community & Feedback
- Discord: Join our community at https://discord.gg/6w9qNRUDzS
- GitHub Issues: Submit feedback at https://github.com/boldsoftware/sketch/issues
📖 User Guide
Getting Started
Start Sketch by running sketch in a Git repository. It will open your browser to the Sketch chat interface, but you can also use the CLI interface. Use -open=false if you want to use just the CLI interface.
Ask Sketch about your codebase or ask it to implement a feature. It may take a little while for Sketch to do its work, so hit the bell (🔔) icon to enable browser notifications. We won't spam you or anything; it will notify you when the Sketch agent's turn is done, and there's something to look at.
How Sketch Works
When you start Sketch, it:
- Creates a Dockerfile
- Builds it
- Copies your repository into it
- Starts a Docker container with the "inside" Sketch running
This design lets you run multiple sketches in parallel since they each have their own sandbox. It also lets Sketch work without worry: it can trash its own container, but it can't trash your machine.
Sketch's agentic loop uses tool calls (mostly shell commands, but also a handful of other important tools) to allow the LLM to interact with your codebase.
Getting Your Git Changes Out
Sketch is trained to make Git commits. When those happen, they are automatically pushed to the git repository where you started sketch with branch names sketch/*.
Finding Sketch branches:
git branch -a --sort=creatordate | grep sketch/ | tail
The UI keeps track of the latest branch it pushed and displays it prominently. You can use standard Git workflows to pull those branches into your workspace:
git cherry-pick $(git merge-base origin/main sketch/foo)
or merge the branch
git merge sketch/foo
or reset to the branch
git reset --hard sketch/foo
Ie use the same workflows you would if you were pulling in a friend's Pull Request.
Advanced: You can ask Sketch to git fetch sketch-host and rebase onto another commit. This will also fetch where you started Sketch, and we do a bit of "git fetch refspec configuration" to make origin/main work as a git reference.
Don't be afraid of asking Sketch to help you rebase, merge/squash commits, rewrite commit messages, and so forth; it's good at it!
Reviewing Diffs
The diff view shows you changes since Sketch started. Leaving comments on lines adds them to the chat box, and, when you hit Send (at the bottom of the page), Sketch goes to work addressing your comments.
Connecting to Sketch's Container
You can interact directly with the container in three ways:
- Web UI Terminal: Use the "Terminal" tab in the UI
- SSH: Look at the startup logs or click the information icon to see a command like
ssh sketch-ilik-eske-tcha-lott. We have automatically configured your SSH configuration to make these special hostnames work. - Visual Studio Code: Look for a command line or magic link behind the information icon, or when Sketch starts up. This starts a new VSCode session "remoted into" the container. You can edit the code, use the terminal, review diffs, and so forth.
Using SSH (and/or VSCode) allows you to forward ports from the container to your machine. For example, if you want to start your development webserver, you can do something like this:
# Forward container port 8888 to local port 8000 ssh -L8000:localhost:8888 sketch-ilik-epor-tfor-ward go run ./cmd/server
This makes http://localhost:8000/ on your machine point to localhost:8888 inside the container.
Using Browser Tools
You can ask Sketch to browse a web page and take screenshots. There are tools both for taking screenshots and "reading images", the latter of which sends the image to the LLM. This functionality is handy if you're working on a web page and want to see what the in-progress change looks like.
❓ FAQ
"No space left on device"
Docker images, containers, and so forth tend to pile up. Ask Docker to prune unused images and containers:
docker system prune -a
🛠️ Development
See CONTRIBUTING.md for development guidelines.
📄 Open Source
Sketch is open source. It is right here in this repository! Have a look around and mod away.
If you want to run Sketch entirely without the sketch.dev service, you can set the flag -skaband-addr="" and then provide an ANTHROPIC_API_KEY environment variable. (More LLM services coming soon!)