{
  "markdown": "# Async Remote Agent Extension for Gemini CLI\n\nThis Gemini CLI extension allows you to manage remote agent sandboxes on a GKE cluster with [agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox) installed.\n\n## Features\n\n- **Create sandboxes**: Create isolated agent runtime environments on your GKE cluster\n- **Check status**: Monitor the status of your sandboxes\n- **Execute commands**: Send prompts/commands to sandboxes and get results\n- **List sandboxes**: View all sandboxes in your cluster\n- **Delete sandboxes**: Clean up sandboxes when done\n\n## Prerequisites\n\n1. A GKE cluster with [agent-sandbox](https://github.com/kubernetes-sigs/agent-sandbox) installed\n2. The sandbox proxy deployed on your GKE cluster (see `~/workspaces/remote-agent-sandbox-proxy`)\n3. Node.js and npm installed\n4. Gemini CLI installed\n\n**Note:** No kubectl or kubeconfig required! All Kubernetes operations are handled by the proxy.\n\n## Installation\n\n1. Clone or download this extension:\n   ```bash\n   cd /path/to/async-remote-agent-extension\n   ```\n\n2. Install dependencies:\n   ```bash\n   npm install\n   ```\n\n3. Build the extension:\n   ```bash\n   npm run build\n   ```\n\n4. Link the extension to Gemini CLI:\n   ```bash\n   gemini extensions link .\n   ```\n\n## Configuration\n\nCreate a configuration file at `~/.config/gemini-remote-sandbox/config.json`:\n\n```bash\nmkdir -p ~/.config/gemini-remote-sandbox\ncp config.template.json ~/.config/gemini-remote-sandbox/config.json\n```\n\nEdit the config file with your settings:\n\n```json\n{\n  \"proxyUrl\": \"http://35.123.45.67\",\n  \"username\": \"alice\",\n  \"namespace\": \"default\",\n  \"defaultImage\": \"us-central1-docker.pkg.dev/agent-sandbox-476202/agent-sandbox/sandbox-runtime:latest\",\n  \"defaultPort\": 8888\n}\n```\n\nConfiguration options:\n- `proxyUrl`: **REQUIRED** - URL of the sandbox proxy LoadBalancer (get this with: `kubectl get service sandbox-proxy`)\n- `username`: Username for sandbox routing (default: \"default\"). Sandboxes created will have a `user` label with this value.\n- `namespace`: Kubernetes namespace where sandboxes will be created (default: \"default\")\n- `defaultImage`: Default container image for sandboxes (optional)\n- `defaultPort`: Default port for the sandbox API (default: 8888)\n\n## Usage\n\nAfter linking the extension, restart your Gemini CLI session. The following commands and tools will be available:\n\n### Commands\n\n#### `/remote:create <sandbox-name>`\n\nCreates a new sandbox on your GKE cluster.\n\nExample:\n```\n/remote:create my-sandbox\n```\n\n#### `/remote:status <sandbox-name>`\n\nGets the status of a sandbox.\n\nExample:\n```\n/remote:status my-sandbox\n```\n\n#### `/remote:prompt <sandbox-name> <command>`\n\nExecutes a command in the sandbox and returns the results.\n\nExample:\n```\n/remote:prompt my-sandbox ls -la\n```\n\n### Tools\n\nThe extension also provides MCP tools that can be used directly:\n\n- `create_sandbox`: Creates a new sandbox\n- `get_sandbox_status`: Gets sandbox status\n- `send_prompt_to_sandbox`: Sends a command to the sandbox\n- `list_sandboxes`: Lists all sandboxes\n- `delete_sandbox`: Deletes a sandbox\n\nYou can invoke these tools by asking Gemini to use them:\n```\nList all my sandboxes\n```\n```\nDelete the sandbox named test-sandbox\n```\n\n## Building Your Sandbox Image\n\nTo use this extension, you need a container image that runs the sandbox runtime API. You can use the example from agent-sandbox:\n\n1. Navigate to the python-runtime-sandbox example:\n   ```bash\n   cd ~/workspaces/agent-sandbox/examples/python-runtime-sandbox\n   ```\n\n2. Build the image:\n   ```bash\n   docker build -t sandbox-runtime:latest .\n   ```\n\n3. Push to your container registry:\n   ```bash\n   docker tag sandbox-runtime:latest gcr.io/your-project/sandbox-runtime:latest\n   docker push gcr.io/your-project/sandbox-runtime:latest\n   ```\n\n4. Update your config.json to use the pushed image:\n   ```json\n   {\n     \"defaultImage\": \"gcr.io/your-project/sandbox-runtime:latest\"\n   }\n   ```\n\n## How It Works\n\nThis extension uses the agent-sandbox Kubernetes CRD to create isolated sandbox environments. Each sandbox:\n\n1. Runs as a Kubernetes pod in your GKE cluster\n2. Exposes a FastAPI server with endpoints for executing commands\n3. Provides isolation using your cluster's configured runtime (e.g., gVisor)\n4. Can persist data using PersistentVolumeClaims\n\n### Architecture\n\nThe extension communicates **entirely through the proxy** - no direct Kubernetes access needed:\n\n```\nGemini CLI Extension (local workstation)\n    ↓ All operations via HTTP to proxy\nSandbox Proxy (GKE with public IP)\n    ↓ Manages Kubernetes resources via k8s API\n    ↓ Routes requests to sandboxes\nSandbox Pods (internal Kubernetes services)\n```\n\n**Proxy API Endpoints:**\n- `POST /api/sandboxes` - Create sandbox (proxy creates k8s resources)\n- `GET /api/sandboxes` - List all sandboxes\n- `GET /api/sandboxes/:username/:name` - Get sandbox status\n- `DELETE /api/sandboxes/:username/:name` - Delete sandbox\n- `POST /:username/:name/v1/shell/exec` - Execute command in sandbox\n\n**Benefits:**\n- ✅ No kubectl required - works from anywhere with internet access\n- ✅ No kubeconfig needed - proxy handles all k8s authentication\n- ✅ Fast - no port-forwarding overhead\n- ✅ Simple - just HTTP requests\n- ✅ Scalable - proxy can handle many concurrent requests\n- ✅ Secure - only proxy needs k8s access, sandboxes remain internal\n\n**Setup:**\nThe proxy service is in `~/workspaces/remote-agent-sandbox-proxy`. Deploy it to your GKE cluster and configure the LoadBalancer IP in this extension's config.\n\n## Troubleshooting\n\n### \"proxyUrl is required in config.json\"\nMake sure you have created the config file at `~/.config/gemini-remote-sandbox/config.json` with at least a `proxyUrl` field.\n\n### \"Failed to create sandbox\" / Connection errors\n- Check that the proxy is running: `kubectl get deployment sandbox-proxy`\n- Verify the proxy LoadBalancer IP: `kubectl get service sandbox-proxy`\n- Test proxy health: `curl http://PROXY_IP/health`\n- Ensure your `proxyUrl` in config.json matches the proxy's external IP\n\n### \"Sandbox not ready\"\nWait 30-60 seconds for the sandbox pod to start. You can check the status with `/remote:status <name>` or `list all sandboxes`.\n\n### \"Sandbox not found\" 404 errors\n- Verify the sandbox exists: ask Gemini to \"list all sandboxes\"\n- Check that your `username` in config.json matches the sandbox's `user` label\n- The proxy may need time to discover new sandboxes (30 second refresh interval)\n\n### \"Failed to execute command\"\nEnsure your sandbox image includes the FastAPI runtime server as shown in the agent-sandbox examples.\n\n## Development\n\nTo make changes to the extension:\n\n1. Edit the TypeScript source files\n2. Rebuild:\n   ```bash\n   npm run build\n   ```\n3. Restart Gemini CLI to pick up the changes\n\n## License\n\nApache-2.0\n",
  "bytes": 6756,
  "sha": "ec5420b5be2cec76857c24fabf10258e72f9f962eebb36fd62a18c68c1c73153",
  "repo_slug": "derrickchwong/remote-agent-extension",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_derrickchwong_remote_agent_extension_d7c42d91/readme"
}