{"id":13456788,"url":"https://github.com/jamsocket/botsh","last_synced_at":"2025-04-12T23:06:39.218Z","repository":{"id":153483248,"uuid":"625723554","full_name":"jamsocket/botsh","owner":"jamsocket","description":"An LLM-based agent that will install the tools it needs.","archived":false,"fork":false,"pushed_at":"2023-05-15T14:39:49.000Z","size":143,"stargazers_count":221,"open_issues_count":1,"forks_count":8,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-12T23:05:58.497Z","etag":null,"topics":["docker","gpt-3","llm"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jamsocket.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-04-10T00:54:04.000Z","updated_at":"2025-03-29T19:57:08.000Z","dependencies_parsed_at":"2023-05-27T15:15:06.054Z","dependency_job_id":null,"html_url":"https://github.com/jamsocket/botsh","commit_stats":null,"previous_names":["jamsocket/botsh"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamsocket%2Fbotsh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamsocket%2Fbotsh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamsocket%2Fbotsh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamsocket%2Fbotsh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamsocket","download_url":"https://codeload.github.com/jamsocket/botsh/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248643006,"owners_count":21138355,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","gpt-3","llm"],"created_at":"2024-07-31T08:01:27.750Z","updated_at":"2025-04-12T23:06:39.182Z","avatar_url":"https://github.com/jamsocket.png","language":"Python","funding_links":[],"categories":["Python","Building","Agent Categories"],"sub_categories":["Tools","\u003ca name=\"Unclassified\"\u003e\u003c/a\u003eUnclassified"],"readme":"# `botsh`\n\n[![PyPI version](https://badge.fury.io/py/botsh.svg)](https://badge.fury.io/py/botsh)\n\n`botsh` attaches a chat agent to a Docker container running Ubuntu.\n\nThis effectively gives the agent access to the entire [APT](https://wiki.debian.org/Apt)\nuniverse, while limiting its blast radius to the current directory (which gets mounted into the container).\n\n## Demo\n\nThis demo uses the prompt `create a sequence of 100 200x200 images which each contain a different number, and turn them into a 30fps video with ffmpeg`.\n\n`botsh`:\n\n- tries to run `imagemagick` and fails (because it is a fresh Ubuntu install)\n- installs `imagemagick`\n- attempts to run `ffmpeg` and fails\n- installs `ffmpeg`\n- attempts to turn frames into a video and fails (because it has not created them)\n- writes a bash for-loop to generate 100 frames with `imagemagick`\n- uses `ffmpeg` to convert them into a video\n\nhttps://user-images.githubusercontent.com/46173/230953506-c8545345-c0a1-46b1-b937-458191fc2456.mp4\n\n## Setup\n\nInstall with:\n\n    pip install botsh\n\n`botsh` expects an OpenAI API key to be provided as the `OPENAI_API_KEY`\nenvironment variable.\n\n`botsh` also requires Docker to be running on the system.\n\n## Examples\n\n    botsh \"convert cat.jpg into a png file\"\n\n    botsh \"use a remote service to find my public ip and base64 encode it\"\n\n    botsh \"run pylint on the codebase in src/\"\n\n## Additional details\n\n`botsh` will create a bare Ubuntu Docker container associated with\nthe current directory, or create one if one does not exist. botsh\nwill then attach the OpenAI API to a shell running in the container\nto attempt to complete the given task.\n\nThe AI is explicitly told that it is allowed to install software,\nand will typically install programs as needed to complete its task.\nInstalled software remains confined to the container.\n\n## Observations\n\nThese observations relate to the default model, `text-davinci-003`. Using GPT-4 may improve things.\n\n- It works best if you explicitly specify the files/paths you want to work with (use relative references).\n  It is not good at figuring out what you mean.\n- It often gets stuck in loops if it can't complete a task rather than giving up, despite the prompt\n  telling it not to.\n- It sometimes needs subtle encouragement to break a task down into multiple parts, instead of chaining together\n  a long shell command, particularly when the command it wants to run has a bug. For example, instead of\n  saying “convert foo.png to a gif and compute its md5 sum”, try “convert foo.png into a gif, and then compute\n  its md5 sum”\n\n## Container re-use\n\nWhen `botsh` is invoked, the current working directory is mounted\ninto the container and can be modified by programs the agent runs.\nThe filesystem outside of the current working directory is sealed\noff from the container.\n\nEach directory that you run `botsh` in will get its own container,\nwhich is reused for future invocations of `botsh` in that container.\n\nYou can pass `--wipe` to discard the existing container and start a\nnew one before running your task. You can also pass `--rm` to remove\na container at the end of your task.\n\nContainers are also removed if you purge containers in Docker with\n`docker container prune`\n\n## Usage\n\n```\nusage: botsh [-h] [--max-rounds MAX_ROUNDS] [--model MODEL] [--image IMAGE] [--shell-command SHELL_COMMAND] [--save-transcript] [--wipe] prompt\n\nTask runner powered by OpenAI and Docker. Invoke botsh by providing a task as a command line argument. botsh will create a bare Ubuntu Docker container associated with the current directory, or create one if one does not exist. botsh will then attach the OpenAI API to a shell running in the container to attempt to complete the given task.\n\npositional arguments:\n  prompt                Prompt to execute.\n\noptions:\n  -h, --help            show this help message and exit\n  --max-rounds MAX_ROUNDS\n  --model MODEL         OpenAI text completion model to use.\n  --image IMAGE         Docker image to use.The current hard-coded prompt works for Debian-derived distributions.\n  --shell-command SHELL_COMMAND\n                        Shell to invoke within the container.\n  --save-transcript     Save transcript to file\n  --wipe                Start with a fresh container even if one exists for this directory.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamsocket%2Fbotsh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamsocket%2Fbotsh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamsocket%2Fbotsh/lists"}