{"id":31770988,"url":"https://github.com/pigmej/aisanity","last_synced_at":"2025-10-10T03:18:31.927Z","repository":{"id":318225109,"uuid":"1064951912","full_name":"pigmej/aisanity","owner":"pigmej","description":"Aisanity is a secure, hassle-free tool for running AI agents in isolated environments, protecting your host OS from risks while enabling seamless development workflows. It provides sandboxed containers with automatic AI integration, git worktree support for parallel development, and compatibility with any IDE or terminal tool.","archived":false,"fork":false,"pushed_at":"2025-10-05T22:25:42.000Z","size":5448,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T23:31:57.018Z","etag":null,"topics":["agentic-ai","devcontainer","docker","opencode"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/pigmej.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,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-26T20:15:05.000Z","updated_at":"2025-10-05T22:25:46.000Z","dependencies_parsed_at":"2025-10-05T23:42:03.934Z","dependency_job_id":null,"html_url":"https://github.com/pigmej/aisanity","commit_stats":null,"previous_names":["pigmej/aisanity"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/pigmej/aisanity","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pigmej%2Faisanity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pigmej%2Faisanity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pigmej%2Faisanity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pigmej%2Faisanity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pigmej","download_url":"https://codeload.github.com/pigmej/aisanity/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pigmej%2Faisanity/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002582,"owners_count":26083420,"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","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agentic-ai","devcontainer","docker","opencode"],"created_at":"2025-10-10T03:18:27.622Z","updated_at":"2025-10-10T03:18:31.922Z","avatar_url":"https://github.com/pigmej.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"logo.png\" alt=\"Aisanity Logo\" width=\"256\"\u003e\n\u003c/div\u003e\n\nAisanity is a secure, hassle-free tool for running AI agents in isolated environments, protecting your host OS from risks while enabling seamless development workflows. It provides sandboxed containers with automatic AI integration, git worktree support for parallel development, and compatibility with any IDE or terminal tool.\n\n## Tool Compatibility\n\nAisanity works with all development tools and IDEs. While opencode is the primary tool of interest and automatically integrated into all development environments, you can use any development tool you prefer:\n\n- **VSCode** - Full devcontainer support with automatic configuration\n- **IntelliJ IDEA** - Compatible with devcontainer environments\n- **Vim/Neovim** - Works seamlessly with containerized development\n- **Emacs** - Full integration with devcontainer workflows via TRAMP (just use /docker)\n- **Any terminal-based tool** - Access containers via `aisanity run`\n\nAll devcontainer templates include automatic opencode installation and configuration, but you're not required to use it.\n\n## Installation\n\n### Prerequisites\n\n**Bun Runtime Required**: Aisanity requires Bun (\u003e=1.0.0) runtime. Installation is quick and simple:\n\n```bash\n# Install Bun runtime (takes \u003c30 seconds)\ncurl -fsSL https://bun.sh/install | bash\n\n# Verify installation\nbun --version\n```\n\n### Option 1: Install with Bun (Recommended)\n\n```bash\n# Install Aisanity globally\nbun install -g aisanity\n```\n\n### Option 2: Standalone Executable\n\nDownload the platform-specific executable from the [GitHub Releases](https://github.com/pigmej/aisanity/releases) page:\n\n#### macOS (Intel)\n```bash\n# Download and verify\ncurl -L -o aisanity-darwin-x64 https://github.com/pigmej/aisanity/releases/latest/download/aisanity-darwin-x64\ncurl -L -o aisanity-darwin-x64.sha256 https://github.com/pigmej/aisanity/releases/latest/download/aisanity-darwin-x64.sha256\n\n# Verify checksum\nsha256sum -c aisanity-darwin-x64.sha256\n\n# Make executable and run\nchmod +x aisanity-darwin-x64\n./aisanity-darwin-x64 --help\n```\n\n#### macOS (Apple Silicon)\n```bash\n# Download and verify\ncurl -L -o aisanity-darwin-arm64 https://github.com/pigmej/aisanity/releases/latest/download/aisanity-darwin-arm64\ncurl -L -o aisanity-darwin-arm64.sha256 https://github.com/pigmej/aisanity/releases/latest/download/aisanity-darwin-arm64.sha256\n\n# Verify checksum\nsha256sum -c aisanity-darwin-arm64.sha256\n\n# Make executable and run\nchmod +x aisanity-darwin-arm64\n./aisanity-darwin-arm64 --help\n```\n\n#### Linux (x64)\n```bash\n# Download and verify\ncurl -L -o aisanity-linux-x64 https://github.com/pigmej/aisanity/releases/latest/download/aisanity-linux-x64\ncurl -L -o aisanity-linux-x64.sha256 https://github.com/pigmej/aisanity/releases/latest/download/aisanity-linux-x64.sha256\n\n# Verify checksum\nsha256sum -c aisanity-linux-x64.sha256\n\n# Make executable and run\nchmod +x aisanity-linux-x64\n./aisanity-linux-x64 --help\n```\n\n#### Linux (ARM64)\n```bash\n# Download and verify\ncurl -L -o aisanity-linux-arm64 https://github.com/pigmej/aisanity/releases/latest/download/aisanity-linux-arm64\ncurl -L -o aisanity-linux-arm64.sha256 https://github.com/pigmej/aisanity/releases/latest/download/aisanity-linux-arm64.sha256\n\n# Verify checksum\nsha256sum -c aisanity-linux-arm64.sha256\n\n# Make executable and run\nchmod +x aisanity-linux-arm64\n./aisanity-linux-arm64 --help\n```\n\n#### Checksum Verification\n\nAll releases include SHA256 checksum files for security verification. Always verify the checksum before running the binary:\n\n```bash\n# The checksum file contains the expected hash\ncat aisanity-linux-x64.sha256\n# Output: a1b2c3d4e5f6...  aisanity-linux-x64\n\n# Verify the downloaded file matches the checksum\nsha256sum -c aisanity-linux-x64.sha256\n# Output: aisanity-linux-x64: OK\n```\n\n**Note**: Standalone executables bundle the Bun runtime, so no separate Bun installation is needed.\n\n### Why Bun?\n\nAisanity requires Bun for optimal performance and modern development experience:\n- **4x faster** startup times (~70ms vs ~300ms)\n- **100x faster** test execution (~50ms vs ~5s)\n- **Native TypeScript** execution without compilation\n- **Modern APIs** for shell commands and process spawning\n- **25-40% less** memory usage\n\n### Development Setup\n\nFor developers contributing to Aisanity:\n```bash\n# Clone repository\ngit clone \u003crepository-url\u003e\ncd aisanity\n\n# Install dependencies with Bun (recommended)\nbun install\n\n# Run development\nbun run dev\n\n# Run tests\nbun test\n\n# Build for distribution\nbun run build\n```\n\n## Usage\n\n### Initialize Workspace\n\nFirst, initialize your workspace:\n\n```bash\naisanity init\n```\n\nThis creates:\n- `.aisanity` configuration file with workspace settings\n- Workspace-specific configuration files\n\n### Git Worktree Commands\n\nAisanity provides comprehensive git worktree support for parallel development workflows.\n\nWorktree support is *disabled* by default, to enable you need to modify the .aisanity setting. Set `worktree: true` and you're good to go.\n\n#### Create a New Worktree\n\nCreate a new worktree with automatic container setup:\n\n```bash\n# Create a new worktree for a feature branch\naisanity worktree create feature-auth\n\n# Create a worktree without switching to it\naisanity worktree create feature-ui --no-switch\n\n# Enable verbose logging\naisanity worktree create feature-bugfix --verbose\n```\n\nThis will:\n- Create a git worktree in `worktrees/\u003cbranch-name\u003e/`\n- Copy `.aisanity` configuration from main workspace\n- Copy `.devcontainer` configuration from main workspace (even if not in .git)\n- Switch to the new worktree (by default)\n\n#### List All Worktrees\n\nView all worktrees and their container status:\n\n```bash\naisanity worktree list\n```\n\nExample output:\n```\nWorktrees for this repository:\n\n→ Main Workspace (active)\n   Path: /path/to/project\n   Branch: main\n   Container: project-main\n   Status: Running (Up 2 hours)\n   Config: /path/to/project/.aisanity\n\nAdditional Worktrees:\n\n  feature-auth\n   Path: /path/to/project/worktrees/feature-auth\n   Branch: feature-auth\n   Container: project-feature-auth\n   Status: Running (Up 1 hour)\n   Config: /path/to/project/worktrees/feature-auth/.aisanity\n\n  feature-ui\n   Path: /path/to/project/worktrees/feature-ui\n   Branch: feature-ui\n   Container: project-feature-ui\n   Status: Stopped (Exited 2 days ago)\n   Config: /path/to/project/worktrees/feature-ui/.aisanity\n\nCurrent worktree: feature-auth\n```\n\n#### Check a Worktree\n\nCheck worktree status and display information:\n\n```bash\naisanity worktree check feature-ui\n```\n\n#### Remove a Worktree\n\nRemove a worktree and clean up associated containers:\n\n```bash\naisanity worktree remove feature-auth\n```\n\nThis will:\n- Stop and remove the worktree's container\n- Delete the worktree directory\n- Clean up git worktree references\n\n### Run Commands in Container\n\nRun any command inside the devcontainer:\n\n```bash\n# Run a shell in current workspace/worktree\naisanity run\n\n# Run in a specific worktree\naisanity run --worktree feature-auth\n\n# Run specific commands\naisanity run echo \"Hello from container!\"\naisanity run npm install\n```\n\n### Check Status\n\nView the status of containers for your workspace:\n\n```bash\n# Status of current workspace/worktree\naisanity status\n\n# Status of specific worktree\naisanity status --worktree feature-auth\n```\n\n### Stop Containers\n\nStop all containers related to your workspace:\n\n```bash\n# Stop current workspace/worktree containers\naisanity stop\n\n# Stop all worktree containers\naisanity stop --all-worktrees\n\n# Stop specific worktree containers\naisanity stop --worktree feature-auth\n```\n\n## Worktree Workflows\n\n### Parallel Development Example\n\n```bash\n# Start in main workspace\ncd /path/to/project\n\n# Create worktree for authentication feature\naisanity worktree create feature-auth\n\n# Create worktree for UI improvements\naisanity worktree create feature-ui\n\n# List all worktrees to see status\naisanity worktree list\n\n# Check authentication worktree status\naisanity worktree check feature-auth\n\n# Work on authentication feature\naisanity run\n# Inside container: work on auth code...\n\n# Check UI worktree status\naisanity worktree check feature-ui\n\n# Work on UI improvements\naisanity run\n# Inside container: work on UI code...\n\n# Both worktrees have isolated containers and can be developed in parallel\n```\n\n### Hotfix Workflow\n\n```bash\n# Working on a feature in a worktree\naisanity worktree create feature-new-api\n\n# Urgent hotfix needed - create hotfix worktree\naisanity worktree create hotfix-security-patch\n\n# Check hotfix worktree status\naisanity worktree check hotfix-security-patch\n\n# Fix the issue\naisanity run\n# Inside container: implement security fix...\n\n# Test and deploy hotfix\ngit commit -m \"Fix security vulnerability\"\ngit push origin hotfix-security-patch\n\n# Check feature worktree status\naisanity worktree check feature-new-api\n```\n\n### Code Review Workflow\n\n```bash\n# Create worktree for reviewer\naisanity worktree create review-pr-123\n\n# Check review worktree status\naisanity worktree check review-pr-123\n\n# Pull the PR branch\ngit fetch origin pull/123/head:pr-123\ngit checkout pr-123\n\n# Review the code in isolated environment\naisanity run\n# Inside container: review and test the PR...\n\n# Remove review worktree when done\naisanity worktree remove review-pr-123\n```\n\n## Migration Notes for Existing Users\n\n### Upgrading from Non-Worktree Workflows\n\nIf you're an existing Aisanity user, your workflows remain unchanged. The worktree integration is completely backward compatible:\n\n1. **Your current workspace continues to work exactly as before**\n2. **Container naming preserves original behavior for main workspace**\n3. **All existing commands (`run`, `stop`, `status`) work without modification**\n\n### Migrating to Worktree Workflows\n\nTo start using worktree features:\n\n```bash\n# Your existing setup continues to work\naisanity run  # Still works in main workspace\n\n# When ready for parallel development:\naisanity worktree create feature-branch\n\n# Worktrees automatically inherit your .aisanity configuration\n# Each worktree gets its own isolated container\n```\n\n### Recommended Directory Structure Changes\n\nWhen you start using worktrees, your project structure will look like:\n\n```\na_project/\n├── a_project/                 # Main workspace .git directory\n│   ├── .git/\n│   ├── .aisanity              # Main workspace config\n│   └── .devcontainer/         # Main workspace devcontainer\n│       └── devcontainer.json\n├── worktrees/                 # Worktree directory\n│   ├── feature-auth/\n│   │   ├── .aisanity          # Worktree-specific config\n│   │   ├── .devcontainer/     # Worktree-specific devcontainer\n│   │   │   └── devcontainer.json\n│   │   └── a_project/         # Linked to main .git\n│   └── feature-ui/\n│       ├── .aisanity          # Worktree-specific config\n│       ├── .devcontainer/     # Worktree-specific devcontainer\n│       │   └── devcontainer.json\n│       └── a_project/         # Linked to main .git\n```\n\n## Configuration\n\nThe `.aisanity` file contains workspace configuration:\n\n```yaml\nworkspace: project_main\ncontainerName: aisanity-project_main\n```\n\n### Worktree-Specific Configuration\n\nEach worktree gets its own `.aisanity` file copied from the main workspace. You can customize worktree-specific settings:\n\n```yaml\n# In worktrees/feature-auth/.aisanity\nworkspace: project_main\nenv:\n  FEATURE_AUTH_ENABLED: \"true\"\n  DATABASE_URL: \"postgresql://localhost:5432/auth_db\"\n```\n\n## Requirements\n\n- Docker\n- Devcontainers CLI (`npm install -g @devcontainers/cli`)\n- **Bun \u003e= 1.0.0** (required)\n\n\n## Opencode integration\n\nBy default, Aisanity uses OpenCode as the preferred AI coding agent. It mounts OpenCode-specific paths to share session logs, state, configuration, and other data. Additionally, OpenCode is installed by default in all containers. There's nothing magical about this integration - it's simply automated setup. If you don't want to use OpenCode, you can modify the generated template (which you'll likely need to customize anyway).\n\n## Devcontainer Integration\n\nAisanity automatically creates devcontainer configurations during `aisanity init` based on your project type. No manual setup is required.\n\nIf you have already .devcontainer based setup then most likely you want to add opencode specific paths in the mounts (or other AI coding agent).\n\n### Automatic Project Detection\n\nWhen you run `aisanity init`, Aisanity detects your project type and generates an appropriate devcontainer configuration:\n\n- **Python projects** - Python 3.11 with uv, ruff, and opencode integration\n- **Node.js projects** - Node.js 18 with TypeScript and Tailwind support\n- **Go projects** - Go 1.21 with Go extensions and tools\n- **Rust projects** - Rust toolchain with rust-analyzer\n- **Java projects** - Java 17 with Java Development Pack\n- **Unknown projects** - Base Ubuntu environment with Node.js\n\n### Auto-Generated Configuration Examples\n\n#### Python Project Example\n```json\n{\n  \"name\": \"Python Development\",\n  \"image\": \"mcr.microsoft.com/devcontainers/python:3.11\",\n  \"features\": {\n    \"ghcr.io/devcontainers/features/node:1\": {\n      \"version\": \"lts\"\n    },\n    \"ghcr.io/gvatsal60/dev-container-features/uv:0\": {},\n    \"ghcr.io/jsburckhardt/devcontainer-features/ruff:1\": {}\n  },\n  \"forwardPorts\": [5000, 8000],\n  \"mounts\": [\n    \"source=${localEnv:HOME}/.config/opencode,target=/home/vscode/.config/opencode,type=bind,consistency=cached\",\n    \"source=${localEnv:HOME}/.local/share/opencode,target=/home/vscode/.local/share/opencode,type=bind,consistency=cached\",\n    \"source=${localEnv:HOME}/.local/state/opencode,target=/home/vscode/.local/state/opencode,type=bind,consistency=cached\"\n  ],\n  \"postCreateCommand\": \"npm install -g opencode-ai\",\n  \"remoteUser\": \"vscode\"\n}\n```\n\n#### Node.js Project Example\n```json\n{\n  \"name\": \"Node.js Development\",\n  \"image\": \"mcr.microsoft.com/devcontainers/javascript-node:18\",\n  \"features\": {\n    \"ghcr.io/devcontainers/features/node:1\": {\n      \"version\": \"lts\"\n    }\n  },\n  \"forwardPorts\": [3000, 3001],\n  \"mounts\": [\n    \"source=${localEnv:HOME}/.config/opencode,target=/home/node/.config/opencode,type=bind,consistency=cached\",\n    \"source=${localEnv:HOME}/.local/share/opencode,target=/home/node/.local/share/opencode,type=bind,consistency=cached\",\n    \"source=${localEnv:HOME}/.local/state/opencode,target=/home/node/.local/state/opencode,type=bind,consistency=cached\"\n  ],\n  \"postCreateCommand\": \"npm install -g opencode-ai\",\n  \"remoteUser\": \"node\"\n}\n```\n\n### Cross-Platform Compatibility\n\nDevcontainers provide consistent development environments across all tools and platforms:\n\n- **Tool Agnostic**: Works with any IDE or development tool\n- **Environment Consistency**: Same dependencies and configurations everywhere\n- **Opencode Integration**: Automatic installation and configuration in all templates\n- **Configuration Mounting**: Your local opencode settings are automatically available in containers\n\nAll templates include automatic opencode installation and proper directory mounting for seamless integration with your existing opencode configuration.\n\n## Architecture\n\n- **Workspace Naming**: `{folder_name}_{branch_name}` (sanitized)\n- **Mounting**: Current directory → `/workspace` in container\n- **Configuration**: Local tool configurations mounted to containers\n- **Container Management**: Uses devcontainers CLI for lifecycle management\n\n\n\n\n## Release Process\n\nAisanity uses automated releases triggered by semantic version tags. When a tag matching `v*.*.*` is pushed to the repository:\n\n1. **Automatic Build**: Cross-compilation builds binaries for all supported platforms\n2. **Checksum Generation**: SHA256 checksums are generated for each binary\n3. **GitHub Release**: A new release is created with all assets and generated notes\n4. **Asset Upload**: All binaries and checksum files are uploaded as release assets\n\n### Supported Platforms\n\n- **Linux x64** (`aisanity-linux-x64`)\n- **Linux ARM64** (`aisanity-linux-arm64`) \n- **macOS Intel** (`aisanity-darwin-x64`)\n- **macOS Apple Silicon** (`aisanity-darwin-arm64`)\n\n### Creating a Release\n\nTo create a new release:\n\n```bash\n# Create and push a semantic version tag\ngit tag v1.0.0\ngit push origin v1.0.0\n\n# The GitHub Actions workflow will automatically:\n# - Build all platform binaries\n# - Generate checksums\n# - Create the GitHub release\n# - Upload all assets\n```\n\n### Development Builds\n\nFor development and testing, you can build binaries locally:\n\n```bash\n# Build all platforms\nbun run build:all\n\n# Build specific platform\nbun run build:linux-x64\nbun run build:darwin-arm64\n\n# Generate checksums\nbun run checksum:generate\n\n# Prepare complete release locally\nbun run release:prepare\n```\n\n## FAQ\n\n### Container Names\n\nIn the .aisanity file, there are two options for naming containers:\n\n1. **Default Naming**: `{workspace}_{branch_name}` (sanitized)\n2. **Custom Naming**: You can specify a custom name using the `containerName` property in the .aisanity file.\n\nWhat's a workspace? It's literally the directory where you run the command. It can also be set to anything you want. Sharing that name with other workspaces will *reuse* the containers BUT also destroy them if you delete the workspace.\n\nWhy would you want to set `containerName`? By default, each branch gets a completely isolated environment to fully isolate the environments. Setting the `containerName` to something static will remove that functionality.\n\n### Worktrees\n\nYou don't need to use worktrees. Aisanity works perfectly with standard branching workflows, but this approach limits your ability to run multiple development sessions simultaneously.\n\n### Rebuild the Container\n\nTo rebuild the container, run the following command:\n\n```bash\naisanity rebuild\n```\n\nIf you want to rebuild the container from scratch, pass the `--clean` flag to the command:\n\n```bash\naisanity rebuild --clean\n```\n\nYou might want to rebuild the container if something goes wrong inside the container and you need to start fresh.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpigmej%2Faisanity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpigmej%2Faisanity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpigmej%2Faisanity/lists"}