{"id":47811423,"url":"https://github.com/frequenz-floss/contai","last_synced_at":"2026-04-03T18:12:32.325Z","repository":{"id":342083407,"uuid":"1098287445","full_name":"frequenz-floss/contai","owner":"frequenz-floss","description":"A very opinionated Docker-based sandbox for AI CLI tools","archived":false,"fork":false,"pushed_at":"2026-01-28T16:01:59.000Z","size":25,"stargazers_count":51,"open_issues_count":2,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-04T23:47:19.083Z","etag":null,"topics":["ai","cli","container","sandbox","tool"],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/frequenz-floss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-17T13:54:03.000Z","updated_at":"2026-03-02T19:55:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/frequenz-floss/contai","commit_stats":null,"previous_names":["frequenz-floss/contai"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/frequenz-floss/contai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frequenz-floss%2Fcontai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frequenz-floss%2Fcontai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frequenz-floss%2Fcontai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frequenz-floss%2Fcontai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/frequenz-floss","download_url":"https://codeload.github.com/frequenz-floss/contai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/frequenz-floss%2Fcontai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31368162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["ai","cli","container","sandbox","tool"],"created_at":"2026-04-03T18:12:31.754Z","updated_at":"2026-04-03T18:12:32.312Z","avatar_url":"https://github.com/frequenz-floss.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Contain AI! 📦🤖\n\n`contai` is a very opinionated Docker-based sandbox for running AI CLI tools\nfor people paranoid enough to not wanting to give them access to their whole\nsystem (i.e. normal people).\n\n## Features\n\n- **Sandboxed Environment**: Runs AI CLI tools in an isolated Docker container\n  to protect your host system\n- **Pre-installed AI CLI Tools**: Includes [OpenCode](https://opencode.ai/),\n  [OpenAI Codex](https://developers.openai.com/codex/cli/),\n  [GitHub Copilot](https://github.com/features/copilot/cli),\n  [Google Gemini](https://github.com/google-gemini/gemini-cli), and\n  [Claude Code](https://www.claude.com/product/claude-code) out of the box\n- **User Permission Mapping**: Maintains your host UID/GID for seamless file\n  access and ownership\n- **Persistent Home Directory**: Stores configuration and data in\n  `~/.local/share/contai/home` across container sessions\n- **Current Directory Mounting**: Automatically mounts and uses your current\n  working directory\n- **Development Tools Included**: Comes with ripgrep, bat, git, Python,\n  Node.js, and other essential tools\n- **On-demand Tool Installation**: Includes [pkgx](https://pkgx.dev/) for\n  installing additional tools without root access\n- **Symlink-friendly**: Can be symlinked as different tool names (e.g.,\n  `opencode` symlink runs OpenCode directly)\n\n## Build\n\nTo build the container image:\n\n```sh\n./build.sh\n```\n\nThis will create a Docker image tagged as `contai:latest` with your host user's\nUID/GID for proper file permissions.\n\n## Installation\n\nAfter building, you can install `contai` to your PATH:\n\n```sh\n# Create a bin directory in your home (if it doesn't exist)\nmkdir -p ~/bin\n\n# Copy the contai script\ncp contai ~/bin/\n\n# Make sure ~/bin is in your PATH (add to ~/.bashrc or ~/.zshrc if needed)\nexport PATH=\"$HOME/bin:$PATH\"\n```\n\n### Optional: Create Symlinks for Direct Tool Access\n\nYou can create symlinks to run specific AI tools directly:\n\n```sh\ncd ~/bin\nln -s contai opencode\nln -s contai copilot\nln -s contai codex\nln -s contai gemini\nln -s contai claude\n```\n\nNow you can run tools directly (e.g., `opencode` instead of `contai opencode`).\n\n### Install AI Agent Instructions\n\nTo enable AI agents to work best inside the container (e.g., using `pkgx` for\nmissing tools instead of `apt-get`), install the provided `agent-instructions.md`\nfile to the appropriate location for your AI tool:\n\n```sh\n# Create the container's home config directories\nhome=~/.local/share/contai/home\nmkdir -p \"$home\"\n```\n\n#### OpenCode\n\n```sh\n# OpenCode\nmkdir -p \"$home/.config/opencode\"\ncp agent-instructions.md \"$home/.config/opencode/AGENTS.md\"\n```\n\n#### Claude Code\n\n```sh\nmkdir -p \"$home/.claude\"\ncp agent-instructions.md \"$home/.claude/CLAUDE.md\"\n```\n\n#### Google Gemini CLI\n\n```sh\nmkdir -p \"$home/.gemini\"\ncp agent-instructions.md \"$home/.gemini/GEMINI.md\"\n```\n\n#### OpenAI Codex CLI\n\n```sh\nmkdir -p \"$home/.codex\"\ncp agent-instructions.md \"$home/.codex/AGENTS.md\"\n```\n\n#### GitHub Copilot CLI\n\nGitHub Copilot CLI only supports project-level instructions (not global), so\nyou would need to copy the file to each project's\n`.github/copilot-instructions.md`.\n\n## Usage\n\nRun AI tools in the sandboxed environment:\n\n```sh\n# Run a specific tool\ncontai opencode\n\n# Or use symlinks for direct access\nopencode\n\n# The container automatically mounts your current directory\ncd /path/to/your/project\ncontai opencode\n```\n\nYour configuration and data will be persisted in `~/.local/share/contai/home`\nacross container sessions.\n\n## Environment Variables\n\nYou can define environment variables in the container by writing to a\n`~/.local/share/contai/env.list` file. The file is expected to have the\nstandard [docker `--env-file`\nformat](https://docs.docker.com/reference/cli/docker/container/run/#env).\n\n## Known Issues\n\n* Tested almost exclusively with OpenCode for now.\n\n* When configuring MCP servers that need OAuth, for example using\n  [`mcp-remote`](https://github.com/geelen/mcp-remote), for completing the\n  OAuth flow, you need to open a browser on your host machine. For now, you need\n  to run the OAuth flow outside the container, as the container does not\n  have access to your host's browser, and then copy the credentials manually.\n\n  For example:\n\n  ```sh\n  cp -r ~/.mcp-auth/* ~/.local/share/contai/home/.mcp-auth/\n  ```\n\n## Roadmap\n\n- [ ] Add installer script and/or Debian package for easier installation\n  (including symlinks to the shipped tools)\n- [ ] Add pre-built images (needs some thought about how to deal with user IDs)\n- [ ] Add auto-image build when invoking `contai` if image is not found\n- [ ] Find a way to complete OAuth flows from within the container\n- [ ] Integrate with `docker-compose` for easier multi-container setups, for\n  cases where other services are needed, like MCP servers\n- [ ] Support forwarding environment variables from the current environment.\n- [ ] Add configuration file to be able to customize, for example:\n\n  * Mapping of directories to mount into the container\n  * Extra packages to install to the image\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrequenz-floss%2Fcontai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrequenz-floss%2Fcontai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrequenz-floss%2Fcontai/lists"}