{"id":50100833,"url":"https://github.com/hop-top/aps","last_synced_at":"2026-05-23T07:16:00.584Z","repository":{"id":349601869,"uuid":"1135390739","full_name":"hop-top/aps","owner":"hop-top","description":"Agent Profile System","archived":false,"fork":false,"pushed_at":"2026-05-16T02:25:04.000Z","size":2500,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T03:36:50.532Z","etag":null,"topics":["agent-2-agent","agent-client-protocol","agent-protocol","ai-agent","ai-agents","ai-agents-cli","ai-agents-core","ai-agents-for-business","ai-assistant","ai-assistants"],"latest_commit_sha":null,"homepage":"https://hop.top/aps","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hop-top.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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":null,"dco":null,"cla":null}},"created_at":"2026-01-16T03:05:28.000Z","updated_at":"2026-05-11T17:36:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hop-top/aps","commit_stats":null,"previous_names":["hop-top/aps"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/hop-top/aps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Faps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Faps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Faps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Faps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hop-top","download_url":"https://codeload.github.com/hop-top/aps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Faps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33386350,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: 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":["agent-2-agent","agent-client-protocol","agent-protocol","ai-agent","ai-agents","ai-agents-cli","ai-agents-core","ai-agents-for-business","ai-assistant","ai-assistants"],"created_at":"2026-05-23T07:15:59.849Z","updated_at":"2026-05-23T07:16:00.577Z","avatar_url":"https://github.com/hop-top.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"#\" width=\"340\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"#\" width=\"340\"\u003e\n    \u003cimg src=\"#\" width=\"340\" alt=\"APS Logo\"\u003e\n  \u003c/picture\u003e\n  \u003cbr\u003e\n  \u003ca href=\"https://github.com/hop-top/aps/releases\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/release/hop-top/aps.svg\" alt=\"Latest Release\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://pkg.go.dev/hop.top/aps\"\u003e\n    \u003cimg src=\"https://godoc.org/hop.top/aps?status.svg\" alt=\"GoDoc\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/hop-top/aps/actions\"\u003e\n    \u003cimg src=\"https://github.com/hop-top/aps/workflows/CI/badge.svg\" alt=\"Build Status\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/hop-top/aps\"\u003e\n    \u003cimg src=\"https://codecov.io/gh/hop-top/aps/branch/main/graph/badge.svg\" alt=\"Coverage\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# APS (Agent Profile System)\n\n\u003e [!WARNING]\n\u003e **🚧 Do Not Use — History Will Be Rewritten 🚧**\n\u003e\n\u003e This repo is undergoing major restructuring as we selectively\n\u003e open-source internal tools built at\n\u003e [Idea Crafters LLC](https://ideacrafters.com). Git history **will be\n\u003e force-pushed and rewritten** multiple times. Do not fork, clone, or\n\u003e depend on this repo in any capacity until we tag a stable release.\n\nAPS is a local-first Agent Profile System that enables running commands and agent workflows under isolated profiles.\n\n## Quick Start\n\n### Install\n\n```bash\n# Build from source\ngit clone https://github.com/hop-top/aps.git\ncd aps\nmake build\n```\n\n### Create Your First Profile\n\n```bash\n./aps profile create myagent --display-name \"My AI Agent\" --email \"agent@example.com\"\n```\n\n### Choose Your Isolation Level\n\n```bash\n# Process isolation (default, fastest)\n./aps profile create myagent\n\n# Platform isolation (macOS/Linux only, user-level sandbox)\n./aps profile create myagent --isolation-level platform\n\n# Container isolation (strongest isolation, requires Docker)\n./aps profile create myagent --isolation-level container\n```\n\n### Run Commands\n\n```bash\n# Run a command under your profile\n./aps myagent -- echo \"Hello from agent!\"\n\n# Run git with profile's git config\n./aps myagent -- git status\n\n# Start an interactive shell\n./aps myagent\n```\n\nProfile secrets (`secrets.env`) are injected as environment variables, so\nexternal LLM CLIs inherit the selected profile's API keys:\n\n```bash\n# Profile-scoped LLM sessions. Each CLI reads API keys from\n# myagent's secrets.env, without APS logging the secret values.\n./aps run myagent -- claude \"summarize this branch's changes\"\n./aps run myagent -- codex \"write tests for this package\"\n./aps run myagent -- gemini \"summarize docs/user\"\n./aps run myagent -- opencode \"inspect the failing test\"\n\n# Shorthand form is equivalent:\n./aps myagent claude \"review this branch\"\n```\n\nNative `aps chat \u003cprofile\u003e` — REPL with the profile as the assistant\nidentity, persona-as-system-prompt, sessions persisted in the registry —\nis on the roadmap (story 055). The commands above are the supported\nexternal-CLI bridge.\n\n### Generate Documentation\n\n```bash\n./aps docs\n```\n\nDocumentation will be generated at `~/.agents/docs/`.\n\n**Then read:**\n- `~/.agents/docs/README.md` - Getting started guide\n- `~/.agents/docs/CLI.md` - Complete command reference\n- `~/.agents/docs/PROFILES.md` - Profile management guide\n- `~/.agents/docs/ISOLATION.md` - Isolation levels and configuration\n- `~/.agents/docs/SESSIONS.md` - Session management guide\n- `~/.agents/docs/EXAMPLES.md` - Practical examples\n- `~/.agents/docs/WEBHOOKS.md` - Webhook setup guide\n- `~/.agents/docs/SECURITY.md` - Security best practices\n\n**Additional documentation available in the repository:**\n- `docs/dev/implementation/guides/migration-guide.md` - Migration guide from process to platform/container isolation\n- `docs/dev/testing/performance-benchmarks.md` - Performance benchmarks and optimization\n- `docs/dev/security/security-audit.md` - Comprehensive security audit report\n- `docs/dev/operations/releases/release-notes.md` - Release notes and version history\n- `docs/dev/platforms/macos/overview.md` - macOS platform isolation setup\n- `docs/dev/platforms/linux/overview.md` - Linux platform isolation setup\n- `docs/dev/platforms/container/overview.md` - Container isolation setup and configuration\n\n## Features\n\n- **Profile Isolation**: Separate environments for different agents, environments, or contexts with configurable isolation levels (process, platform, container)\n- **Platform Isolation**: User-level sandboxing on macOS (via `dscl`) and Linux (via `useradd`) with ACL-based access control\n- **Container Isolation**: Docker-based isolation with automatic Dockerfile generation, volume mounting, and resource limits\n- **Session Management**: Track and manage long-running sessions with inspect, logs, and terminate commands\n- **Session Attachment**: SSH-based session attachment for platform and container isolation\n- **Secrets Management**: Secure credential storage with automatic environment injection\n- **Action Automation**: Custom scripts triggered by CLI or webhooks\n- **Git Integration**: Automatic gitconfig and SSH key management\n- **Webhook Support**: Event-driven automation from GitHub, GitLab, and more\n- **TUI Interface**: Interactive terminal user interface for easy profile management\n- **Voice Sessions**: Speech-to-speech backend integration (PersonaPlex, Moshi) with web, terminal, messenger, and telephony channels\n- **Graceful Degradation**: Automatic fallback to available isolation levels when requested level is unavailable\n- **Cross-Platform Support**: macOS, Linux, and Windows (platform isolation varies by OS)\n\n## Directory Structure\n\nAll APS data lives under `~/.agents/`:\n\n```\n~/.agents/\n  profiles/\n    myagent/\n      profile.yaml\n      secrets.env\n      gitconfig\n      actions/\n      notes.md\n  docs/\n    README.md\n    CLI.md\n    PROFILES.md\n    SECURITY.md\n    EXAMPLES.md\n    WEBHOOKS.md\n    ISOLATION.md\n    SESSIONS.md\n\n~/.aps/\n  sessions/\n    registry.json\n  keys/\n    \u003csession-id\u003e/\n      admin_key\n      admin_key.pub\n  tmux.conf\n```\n\n## Shell Integration\n\n### Auto-completion\n\n```bash\n# For zsh\necho 'source \u003c(./aps completion zsh)' \u003e\u003e ~/.zshrc\n\n# For bash\necho 'source \u003c(./aps completion bash)' \u003e\u003e ~/.bashrc\n```\n\n### Profile Aliases\n\n```bash\neval \"$(./aps alias)\"\n```\n\nThen run:\n```bash\nmyagent echo \"Hello!\"\n```\n\n## Configuration\n\nGlobal configuration at `~/.config/aps/config.yaml`:\n\n```yaml\nprefix: MYTOOL\nisolation:\n  default_level: process  # process | platform | container\n  fallback_enabled: true   # Allow fallback to lower isolation levels\n```\n\nThis changes environment variables from `APS_*` to `MYTOOL_*` and configures the default isolation behavior.\n\n### Profile Isolation\n\nProfiles can also specify isolation settings in `profile.yaml`:\n\n```yaml\nisolation:\n  level: process  # process | platform | container\n  strict: false   # Fail if requested level is unavailable\n  fallback: true  # Allow fallback to lower isolation levels\n  platform:\n    # macOS/Linux specific settings\n    # See docs/dev/platforms/macos/overview.md or docs/dev/platforms/linux/overview.md\n  container:\n    # Container specific settings\n    image: \"ubuntu:22.04\"    # Base Docker image\n    volumes:                # Volume mounts\n      - source: /tmp\n        target: /workspace\n    resources:              # Resource limits\n      memory: \"1g\"\n      cpu: \"0.5\"\n```\n\n## Build Instructions\n\n### Prerequisites\n- Go 1.25.5+\n- [mise](https://mise.jdx.dev) (recommended for dev tools)\n\n```bash\n# Install all required tools (go, goreleaser, act, etc.)\nmise install\n```\n\n### Platform Requirements\n\n**macOS Platform Isolation:**\n- macOS 10.15 (Catalina) or later\n- Xcode Command Line Tools\n- OpenSSH Server (`sudo systemsetup -setremotelogin on`)\n\n**Linux Platform Isolation:**\n- Linux kernel 3.10+\n- `useradd`, `setfacl` commands\n- OpenSSH Server\n\n**Container Isolation:**\n- Docker installed and running\n- Admin privileges for Docker operations\n\n### Build for all platforms\n\n```bash\nmake build\n```\n\n### Build for current platform\n\n```bash\nmake build-local\n```\n\n### Test\n\n```bash\n# Unit tests\ngo test -v ./tests/unit\n\n# E2E tests\ngo test -v ./tests/e2e\n\n# Platform-specific tests (macOS only)\ngo test -v -tags darwin ./tests/unit/core/isolation\n\n# Platform-specific tests (Linux only)\ngo test -v -tags linux ./tests/unit/core/isolation\n\n# Docker user journey tests\nmake docker-test-e2e-user\n```\n\n### Docker Testing\n\nAPS includes a Docker-based testing environment for testing in an isolated Linux environment that simulates a user's machine. This is particularly useful for testing installation, setup, and workflows without affecting your local development environment.\n\n```bash\n# Build the test environment\nmake docker-build-test\n\n# Run all user journey tests\nmake docker-test-e2e-user\n\n# Start an interactive test environment\nmake docker-test-up\nmake docker-test-shell  # For manual testing\n\n# Cleanup\nmake docker-test-cleanup\n```\n\nFor detailed documentation, see [Docker testing user guide](docs/agent/docker-testing.md) or [Docker testing strategy for developers](docs/dev/testing/docker-testing-strategy.md).\n\n## Commands\n\n```bash\naps                    # Launch TUI\naps help               # Show help\naps profile list       # List all profiles\naps profile create \u003cid\u003e   # Create a new profile\naps profile show \u003cid\u003e  # Show profile details\naps run \u003cid\u003e -- \u003ccmd\u003e  # Run command under profile\naps action list \u003cid\u003e   # List profile actions\naps action run \u003cid\u003e \u003caction\u003e  # Run action\naps session list      # List active sessions\naps session attach \u003cid\u003e  # Attach to a session\naps session detach \u003cid\u003e  # Detach from a session\naps session inspect \u003cid\u003e # Inspect session details\naps session logs \u003cid\u003e    # Show session logs\naps session terminate \u003cid\u003e # Terminate a session\naps voice service start|stop|status  # Manage voice backend\naps voice start [--profile \u003cid\u003e] [--channel web|tui|telegram|twilio]\naps voice session list   # List active voice sessions\naps docs               # Generate documentation\n```\n\n## Examples\n\nSee `~/.agents/docs/EXAMPLES.md` for detailed examples including:\n- GitHub issue triage\n- OpenAI chat assistant\n- Data processing pipelines\n- Multi-environment deployment\n- Webhook integrations\n- Containerized workflows\n- Platform isolation use cases\n- And more\n\n**Platform-specific examples:**\n- `docs/dev/platforms/macos/overview.md` - macOS sandbox examples\n- `docs/dev/platforms/linux/overview.md` - Linux sandbox examples\n- `docs/dev/platforms/container/overview.md` - Container isolation examples\n\n## Isolation Levels\n\nAPS supports multiple isolation levels for running commands and actions:\n\n- **process** (default): Runs commands in isolated processes with injected environment\n- **platform**: Uses platform-specific sandboxing (macOS, Linux)\n- **container**: Runs commands in isolated containers (Docker)\n\nIf the requested isolation level is unavailable, APS can gracefully degrade to a lower level based on configuration.\n\n### Performance Comparison\n\n| Isolation Level | Setup Time | Execution Overhead | Memory Overhead |\n|---------------|------------|-------------------|----------------|\n| Process | 0ms | \u003c 5ms | ~10MB |\n| Platform | 150-400ms* / \u003c 50ms | 10-40ms | ~50-60MB |\n| Container | 2-5s / 100-500ms | 20-50ms | 100-200MB |\n\n\\*First run includes user account creation. Subsequent runs are cached.\n\nSee `docs/dev/testing/performance-benchmarks.md` for detailed benchmarks.\n\n### Platform Isolation\n\n- **macOS**: User account sandboxing via `dscl`, ACL-based access control\n- **Linux**: User account isolation via `useradd`, namespace/chroot/cgroups support\n- Requires: Admin/sudo access, SSH server, admin public key\n\n### Container Isolation\n\n- Docker-based isolation with automatic Dockerfile generation\n- Volume mounting, network configuration, resource limits\n- SSH server and tmux integration for session management\n- Requires: Docker installed\n\nSee `docs/dev/platforms/container/overview.md`, `docs/dev/platforms/macos/overview.md`, and `docs/dev/platforms/linux/overview.md` for platform-specific setup guides.\n\n## Capability Management\n\nAPS can manage external tools, configurations, and dotfiles as \"Capabilities\". These are stored in `~/.aps/capabilities/` and can be linked into your workspace.\n\n### Commands\n\n```bash\n# Install a capability from a directory\naps capability install ./my-tool --name my-tool\n\n# List installed capabilities\naps capability list\n\n# Link a capability to your current workspace\naps capability link my-tool --target ./local/path\n\n# \"Smart Link\" a known tool (e.g., windsurf, copilot)\n# This automatically resolves the target path based on standard conventions\naps capability link copilot\n\n# \"Adopt\" an existing file into APS management\naps capability adopt ./my-config.yaml --name my-config\n\n# \"Watch\" an external file (symlink into APS)\naps capability watch ./external/file --name my-ref\n\n# Delete a capability\naps capability delete my-tool\n```\n\n### Environment Integration\n\nYou can automatically export environment variables for all your capabilities (e.g., `APS_MY_TOOL_PATH`).\n\nAdd this to your shell profile (`~/.zshrc` or `~/.bashrc`):\n\n```bash\neval \"$(aps env)\"\n```\n\nThis ensures that whenever you install or remove a capability, your environment variables are updated (on next shell load or re-eval).\n\n### Configuration\n\nYou can configure additional source directories for capabilities in `~/.config/aps/config.yaml`:\n\n```yaml\ncapability_sources:\n  - /shared/team/capabilities\n  - ~/personal/capabilities\n```\n\n## Session Management\n\nAPS provides session tracking for long-running operations:\n\n```bash\n# List all active sessions\naps session list\n\n# List sessions for a specific profile\naps session list --profile myagent\n\n# Filter by status or tier\naps session list --status active\naps session list --tier premium\n\n# Inspect session details\naps session inspect \u003csession-id\u003e\n\n# View session logs\naps session logs \u003csession-id\u003e\n\n# Terminate a session gracefully\naps session terminate \u003csession-id\u003e\n```\n\n### Session Attachment\n\n- **Process Isolation**: Direct shell access\n- **Platform Isolation**: SSH to sandbox user (macOS/Linux)\n- **Container Isolation**: SSH into container\n\nSessions are tracked in `~/.aps/sessions/registry.json` and include metadata like PID, status, and heartbeat tracking.\n\n## Testing\n\nTo run the E2E test suite:\n\n```bash\ngo test -v ./tests/e2e\n```\n\n## Contributing\n\nContributions are welcome!\n\n### Documentation Structure\n\n*   **[User Documentation](docs/user/README.md)**: Guides for installing and using APS.\n*   **[Developer Documentation](docs/dev/readme.md)**: Architecture, design specs, and implementation details.\n*   **[Agent Documentation](docs/agent/README.md)**: Context and patterns for AI agents working on the codebase.\n\nSee `docs/dev/operations/releases/release-notes.md` for recent changes and version history.\n\nFor developers working on the codebase, see `AGENTS.md` for implementation guidance and architecture details.\n\n## License\n\n[MIT](https://github.com/hop-top/aps/raw/main/LICENSE)\n\n## Support\n\nFor issues, questions, or contributions, please visit:\n- GitHub: https://github.com/hop-top/aps\n- Issues: https://github.com/hop-top/aps/issues\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhop-top%2Faps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhop-top%2Faps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhop-top%2Faps/lists"}