feat(docker): docker remote tools

.release-please-manifest.json

@@ -1,4 +1,5 @@
 {
   "packages/core": "0.0.2",
-  "packages/ssh": "0.0.3"
+  "packages/ssh": "0.0.3",
+  "packages/docker": "0.0.1"
 }

eslint.config.js

@@ -50,6 +50,7 @@ export default [
       '@typescript-eslint/prefer-nullish-coalescing': 'error',
       '@typescript-eslint/prefer-promise-reject-errors': 'off',
       '@typescript-eslint/require-await': 'off',
+      '@typescript-eslint/no-unnecessary-condition': 'warn',
     },
   },
   {

examples/README.md

@@ -1,62 +1,60 @@
 # Examples
 
 This directory contains example projects demonstrating how to use
-`@agent-remote/ssh` with the Claude Agent SDK.
+`@agent-remote` tools with various AI frameworks.
 
 ## Available Examples
 
 ### [claude-agent-sdk](./claude-agent-sdk)
 
-A basic example showing how to:
+A complete example showing how to:
 
-- Connect to a remote SSH server
+- Connect to a remote system
 - Create an AI agent with remote execution tools
 - Execute multi-step tasks autonomously
 - Use the Claude Agent SDK with MCP tools
 
-Perfect for getting started and understanding the fundamentals.
+### [claude-code-ssh](./claude-code-ssh)
+
+Configuration examples for using Claude Code with remote systems:
+
+- MCP server configuration for SSH remotes
+- MCP server configuration for Docker remotes
+- Example configurations for both simultaneously
+- Works with the included sandbox environment
+
+Perfect for using Claude Code to work on remote systems.
 
 ## Development Setup (Contributors)
 
 This guide is for developers working on the monorepo who want to test changes to
-`@agent-remote/ssh` in the examples.
+`@agent-remote/ssh` or `@agent-remote/docker` in the examples.
 
 ### Prerequisites
 
 1. **Start the sandbox** (from monorepo root):
 
-   ```bash
-   cd sandbox
-   docker-compose up -d
-   cd ..
-   ```
+```bash
+cd sandbox
+docker compose up -d
+cd ..
+```
 
-   This provides a Docker container with SSH access for testing.
+This provides a Docker container accessible via SSH or Docker exec for testing.
 
-2. **Build the SSH package** (from monorepo root):
+2. **Build the packages** (from monorepo root):
 
    ```bash
+   # Build SSH package
    cd packages/ssh
    pnpm build
    cd ../..
-   ```
-
-### Linking the Local Package
-
-To use your local development version of `@agent-remote/ssh`:
-
-```bash
-cd examples/claude-agent-sdk
-pnpm link ../../packages/ssh
-pnpm install
-```
-
-The `pnpm link` command:
 
-- Creates a symlink from `node_modules/@agent-remote/ssh` to
-  `../../packages/ssh`
-- Adds an override to `examples/pnpm-workspace.yaml` that persists across
-  installs
+   # Build Docker package
+   cd packages/docker
+   pnpm build
+   cd ../..
+   ```
 
 ### Development Workflow
 
@@ -74,7 +72,7 @@ In another terminal, run the example:
 ```bash
 cd examples/claude-agent-sdk
 export ANTHROPIC_API_KEY=your_api_key_here
-pnpm start
+pnpm start:ssh  # or pnpm start:docker
 ```
 
 Now edit files in `packages/ssh/src/` - they'll automatically rebuild, and the
@@ -89,22 +87,9 @@ pnpm build
 
 # Run the example
 cd ../examples/claude-agent-sdk
-pnpm start
+pnpm start:ssh  # or pnpm start:docker
 ```
 
-### Unlinking (Reverting to npm Version)
-
-To stop using the local package and use the published npm version:
-
-1. Remove the `overrides:` section from `examples/pnpm-workspace.yaml`
-2. Reinstall:
-
-   ```bash
-   cd examples/claude-agent-sdk
-   rm pnpm-lock.yaml
-   pnpm install
-   ```
-
 ## Adding New Examples
 
 When adding a new example:

examples/claude-agent-sdk/README.md

@@ -1,13 +1,13 @@
-# Claude Agent SDK with @agent-remote/ssh
+# Claude Agent SDK with Remote Tools
 
-A complete example demonstrating how to use `@agent-remote/ssh` with the Claude
-Agent SDK to create an AI agent that can interact with remote systems via SSH.
+A complete example demonstrating how to use @agent-remote tools with the Claude
+Agent SDK to create an AI agent that can interact with remote systems.
 
 ## What This Example Does
 
 This example creates an autonomous AI agent that:
 
-- Connects to a remote SSH server
+- Connects to a remote system
 - Executes commands, reads files, and searches the filesystem remotely
 - Uses the Claude Agent SDK to run multi-step tasks
 - Provides all remote operations as MCP tools to Claude
@@ -20,7 +20,9 @@ remote system, and work autonomously until the task is complete.
 - Node.js 20+
 - An Anthropic API key (get one at
   [console.anthropic.com](https://console.anthropic.com))
-- Access to an SSH server
+- Either:
+  - Access to an SSH server, or
+  - Docker with a running container
 
 ## Installation
 
@@ -38,6 +40,8 @@ Set your Anthropic API key:
 export ANTHROPIC_API_KEY=your_api_key_here
 ```
 
+### SSH Configuration
+
 Configure SSH connection using environment variables:
 
 | Variable       | Default     | Description                         |
@@ -47,3 +51,91 @@ Configure SSH connection using environment variables:
 | `SSH_USERNAME` | `dev`       | SSH username                        |
 | `SSH_PASSWORD` | `dev`       | SSH password (if not using key)     |
 | `SSH_KEY_PATH` | -           | Path to private key file (optional) |
+
+### Docker Configuration
+
+Configure Docker connection using environment variables:
+
+| Variable           | Default   | Description                  |
+| ------------------ | --------- | ---------------------------- |
+| `DOCKER_CONTAINER` | `sandbox` | Docker container name/ID     |
+| `DOCKER_SHELL`     | `sh`      | Shell to use (sh, bash, zsh) |
+
+## Running the Example
+
+### Using SSH
+
+```bash
+# Uses default SSH settings (localhost:2222, user 'dev', password 'dev')
+pnpm start:ssh
+
+# Or with custom SSH settings
+export SSH_HOST=myserver.com
+export SSH_PORT=22
+export SSH_USERNAME=myuser
+export SSH_KEY_PATH=~/.ssh/id_rsa
+pnpm start:ssh
+```
+
+### Using Docker
+
+```bash
+# Start a Docker container first
+docker run -d --name my-container ubuntu:latest sleep infinity
+
+# Run the example with Docker remote
+export DOCKER_CONTAINER=my-container
+export DOCKER_SHELL=bash
+pnpm start:docker
+```
+
+## How It Works
+
+The example accepts a command-line argument to choose the remote type:
+
+- **SSH mode** (`pnpm start:ssh`): Establishes an SSH connection to a remote
+  server and maintains it throughout the session
+- **Docker mode** (`pnpm start:docker`): Executes commands directly in a Docker
+  container using `docker exec`
+
+Both modes expose the same set of tools to Claude:
+
+- `bash` - Execute commands in a persistent shell session
+- `bash-output` - Retrieve output from background shells
+- `kill-bash` - Kill running background shells
+- `read` - Read files with optional line ranges
+- `write` - Write content to files
+- `edit` - Edit files by replacing text
+- `grep` - Search for patterns in files
+- `glob` - Find files matching glob patterns
+
+## Example Tasks
+
+The example includes a sample task that demonstrates the agent's capabilities.
+You can modify the `task` variable in `index.ts` to try different operations.
+
+## Using with the Local Sandbox
+
+This repository includes a sandbox environment for testing. To use it:
+
+```bash
+# Start the sandbox
+cd ../../sandbox
+docker compose up -d
+
+# Run the example with SSH (default configuration works with the sandbox)
+cd ../examples/claude-agent-sdk
+pnpm start:ssh
+```
+
+Or use the Docker sandbox directly:
+
+```bash
+# The sandbox container is named 'sandbox'
+cd ../../sandbox
+docker compose up -d
+
+cd ../examples/claude-agent-sdk
+export DOCKER_CONTAINER=sandbox
+pnpm start:docker
+```