docs: run extensions in containers (#6971)
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
dianed-square
@@ -664,6 +664,10 @@ For example, to start a session with a Streamable HTTP extension, you'd run:
|
||||
goose session --with-streamable-http-extension "https://example.com/streamable"
|
||||
```
|
||||
|
||||
### Extensions in Containers
|
||||
|
||||
goose can use the `--container` flag to run extensions inside your Docker containers for devcontainer workflows. See [Running Extensions in Docker Containers](/docs/tutorials/goose-in-docker#running-extensions-in-docker-containers) for details.
|
||||
|
||||
## Developing Extensions
|
||||
|
||||
goose extensions are implemented with MCP, a standard protocol that allows AI models and agents to securely connect with local or remote resources. Learn how to build your own [extension as an MCP server](https://modelcontextprotocol.io/quickstart/server).
|
||||
|
||||
@@ -189,6 +189,7 @@ Start or resume interactive chat sessions.
|
||||
- **`-r, --resume`**: Resume a previous session
|
||||
- **`--fork`**: Create a new duplicate session with copied history. Must be used with `--resume`. Provide `--name` or `--session-id` to fork a specific session. Otherwise forks the most recent session.
|
||||
- **`--history`**: Show previous messages when resuming a session
|
||||
- **`--container <container_id>`**: Run extensions inside a [Docker container](/docs/tutorials/goose-in-docker#running-extensions-in-docker-containers).
|
||||
- **`--debug`**: Enable debug mode to output complete tool responses, detailed parameter values, and full file paths
|
||||
- **`--max-tool-repetitions <NUMBER>`**: Set the maximum number of times the same tool can be called consecutively with identical parameters. Helps prevent infinite loops.
|
||||
- **`--max-turns <NUMBER>`**: Set the maximum number of turns allowed without user input (default: 1000)
|
||||
@@ -388,6 +389,7 @@ Execute commands from an instruction file or stdin. Check out the [full guide](/
|
||||
- **`-n, --name <name>`**: Name for this run session (e.g. `daily-tasks`)
|
||||
- **`-r, --resume`**: Resume from a previous run
|
||||
- **`--path <PATH>`**: Path for this run session (e.g. `./playground.jsonl`). Used for legacy file-based session storage.
|
||||
- **`--container <container_id>`**: Run extensions [inside a Docker container](/docs/tutorials/goose-in-docker#running-extensions-in-docker-containers).
|
||||
- **`--no-session`**: Run goose commands without creating or storing a session file
|
||||
|
||||
**Extension Options:**
|
||||
|
||||
@@ -92,6 +92,10 @@ You'll need [Docker](https://www.docker.com/) installed on your system. If you w
|
||||
|
||||
Here's a simple example of updating a file-based to-do app to use a SQLite database plus full testing - all within an isolated container environment.
|
||||
|
||||
:::info
|
||||
See [Isolated Development Environments](/docs/tutorials/isolated-development-environments) for more examples, common workflows, and troubleshooting tips.
|
||||
:::
|
||||
|
||||
#### Prompt
|
||||
|
||||
```
|
||||
|
||||
@@ -1,12 +1,14 @@
|
||||
---
|
||||
title: Building goose in Docker
|
||||
title: goose in Docker
|
||||
sidebar_label: goose in Docker
|
||||
description: Run goose inside Docker containers, or run extensions in existing containers for devcontainer workflows
|
||||
---
|
||||
|
||||
:::info Tell Us What You Need
|
||||
There are various scenarios where you might want to build goose in Docker. If the instructions below do not meet your needs, please contact us by replying to our [discussion topic](https://github.com/block/goose/discussions/1496).
|
||||
:::
|
||||
This guide covers two Docker-related scenarios:
|
||||
1. **Running goose inside Docker** - Build and run the goose process itself in a container
|
||||
2. **Running extensions in Docker** - Run goose on your host but execute extensions inside a container
|
||||
|
||||
## Running goose Inside Docker
|
||||
|
||||
You can build goose from the source file within a Docker container. This approach not only provides security benefits by creating an isolated environment but also enhances consistency and portability. For example, if you need to troubleshoot an error on a platform you don't usually work with (such as Ubuntu), you can easily debug it using Docker.
|
||||
|
||||
@@ -18,7 +20,9 @@ To begin, you will need to modify the `Dockerfile` and `docker-compose.yml` file
|
||||
|
||||
- **Optional:** Mounting your personal goose settings and hints files in the `docker-compose.yml` file. This allows you to use your personal settings and hints files within the Docker container.
|
||||
|
||||
|
||||
:::tip Automated Alternative
|
||||
For an automated approach to running goose in containers, see the [Container-Use MCP extension](/docs/mcp/container-use-mcp), which creates and manages containers for you through conversation.
|
||||
:::
|
||||
|
||||
After setting the credentials, you can build the Docker image using the following command:
|
||||
|
||||
@@ -48,4 +52,37 @@ After that, you can start a session:
|
||||
goose session
|
||||
```
|
||||
|
||||
You should now be able to connect to goose with your configured extensions enabled.
|
||||
You should now be able to connect to goose with your configured extensions enabled.
|
||||
|
||||
## Running Extensions in Docker Containers
|
||||
|
||||
The `--container` flag allows you to run goose extensions inside your Docker containers.
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
goose session --container <container-id-or-name>
|
||||
```
|
||||
|
||||
Extensions configured in your `config.yaml` will automatically run inside the specified container. Find your container ID or name with `docker ps`.
|
||||
|
||||
### Requirements
|
||||
|
||||
- Extensions must exist in the container and be accessible via the same paths used in your extension config
|
||||
- To run built-in extensions, the goose CLI must be [installed](/docs/getting-started/installation) inside the container
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Start an interactive session with extensions from config.yaml
|
||||
goose session --container my-dev-container
|
||||
|
||||
# Start a non-interactive session with instructions
|
||||
goose run --container my-dev-container --text "your instructions here"
|
||||
|
||||
# Specify an extension to run in the container
|
||||
goose session --container 4c76a1beed85 --with-extension "uvx mcp-server-fetch"
|
||||
|
||||
# Workaround: Use full path if container can't find the command
|
||||
goose session --container 4c76a1beed85 --with-extension "/root/.local/bin/uvx mcp-server-fetch"
|
||||
```
|
||||
|
||||
@@ -6,7 +6,7 @@ import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
This guide shows you how to set up isolated development environments using the **[Container Use MCP](https://github.com/dagger/container-use)** with goose. With this setup, your development work will be isolated to both git branches and containers, allowing you to experiment freely without affecting your main system state.
|
||||
Note that the container-use MCP is very new and emerging, but offers powerful ways to do isolated development which are very agent friendly (build on tools like Docker, copy on write filesystems and more)
|
||||
The Container Use MCP offers powerful ways to do isolated development which are very agent friendly (build on tools like Docker, copy on write filesystems, and more).
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -18,81 +18,19 @@ The **[Container Use MCP](https://github.com/dagger/container-use)** server prov
|
||||
- Maintain clean separation between different projects and experiments
|
||||
- Work on things in parallel
|
||||
|
||||
:::info Already Using Devcontainers?
|
||||
If you develop inside Docker containers (like VS Code Remote-Containers), see how you can [run extensions in your existing containers](/docs/tutorials/goose-in-docker#running-extensions-in-docker-containers).
|
||||
:::
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker ([Podman](https://docs.dagger.io/ci/integrations/podman), [NerdCtl](https://docs.dagger.io/ci/integrations/nerdctl/) or [Container](https://docs.dagger.io/ci/integrations/apple-container/)) installed and running on your system
|
||||
- Git installed and configured
|
||||
- goose installed and configured
|
||||
|
||||
## Installation
|
||||
## Setup
|
||||
|
||||
### Install Container Use
|
||||
|
||||
Head on over to the [Container Use README](https://github.com/dagger/container-use/blob/main/README.md) for up-to-date install instructions for this fast moving project.
|
||||
|
||||
## Adding to goose
|
||||
|
||||
### Method 1: Quick Setup Link
|
||||
|
||||
Click this link to automatically add the extension to goose:
|
||||
|
||||
**[Add Container-Use to goose](goose://extension?cmd=cu&arg=stdio&id=container-use&name=container%20use&description=use%20containers%20with%20dagger%20and%20git%20for%20isolated%20environments)**
|
||||
|
||||
### Method 2: Manual Configuration
|
||||
|
||||
<Tabs groupId="interface">
|
||||
<TabItem value="ui" label="goose Desktop" default>
|
||||
|
||||
1. Click `...` in the top right corner of the goose Desktop.
|
||||
2. Select `Advanced Settings` from the menu.
|
||||
3. Under `Extensions`, click `Add custom extension`.
|
||||
4. Fill in the details:
|
||||
- **Type**: `Standard IO`
|
||||
- **ID**: `container-use`
|
||||
- **Name**: `Container Use`
|
||||
- **Description**: `Use containers with dagger and git for isolated environments`
|
||||
- **Command**: `cu`
|
||||
- **Arguments**: `stdio`
|
||||
5. Click `Add` button
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="cli" label="goose CLI">
|
||||
|
||||
1. Run the configuration command:
|
||||
```bash
|
||||
goose configure
|
||||
```
|
||||
|
||||
2. Select `Add Extension` from the menu.
|
||||
|
||||
3. Choose `Command-line Extension`.
|
||||
|
||||
4. Follow the prompts:
|
||||
- **Extension name**: `Container Use`
|
||||
- **Command**: `cu stdio`
|
||||
- **Timeout**: `300` (or your preferred timeout)
|
||||
- **Environment variables**: None needed
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="config" label="Config File">
|
||||
|
||||
Add the following configuration to your `~/.config/goose/config.yaml` file:
|
||||
|
||||
```yaml
|
||||
extensions:
|
||||
container-use:
|
||||
name: container-use
|
||||
type: stdio
|
||||
enabled: true
|
||||
cmd: cu
|
||||
args:
|
||||
- stdio
|
||||
envs: {}
|
||||
timeout: 300
|
||||
```
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
For installation and configuration instructions, see the [Container Use Extension](/docs/mcp/container-use-mcp) tutorial.
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
Reference in New Issue
Block a user