{"id":34935103,"url":"https://github.com/nshkrdotcom/sandbox","last_synced_at":"2026-05-23T02:32:26.701Z","repository":{"id":305426579,"uuid":"1021703195","full_name":"nshkrdotcom/sandbox","owner":"nshkrdotcom","description":"Isolated OTP application management system for Elixir/Erlang","archived":false,"fork":false,"pushed_at":"2026-01-18T05:19:09.000Z","size":559,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-18T12:51:51.329Z","etag":null,"topics":["application-isolation","application-management","beam","elixir","erlang-vm","functional-programming","isolation","nshkr-testing","otp","otp-applications","process-isolation","sandbox-environment","testing","testing-tools"],"latest_commit_sha":null,"homepage":null,"language":"Elixir","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/nshkrdotcom.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":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":null,"dco":null,"cla":null}},"created_at":"2025-07-17T20:09:10.000Z","updated_at":"2026-01-18T05:19:12.000Z","dependencies_parsed_at":null,"dependency_job_id":"2342035f-b28c-485e-963d-0630cdbaa629","html_url":"https://github.com/nshkrdotcom/sandbox","commit_stats":null,"previous_names":["nshkrdotcom/sandbox"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nshkrdotcom/sandbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fsandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fsandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fsandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fsandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nshkrdotcom","download_url":"https://codeload.github.com/nshkrdotcom/sandbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nshkrdotcom%2Fsandbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33380555,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T01:21:08.577Z","status":"online","status_checked_at":"2026-05-23T02:00:05.530Z","response_time":53,"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":["application-isolation","application-management","beam","elixir","erlang-vm","functional-programming","isolation","nshkr-testing","otp","otp-applications","process-isolation","sandbox-environment","testing","testing-tools"],"created_at":"2025-12-26T18:01:23.151Z","updated_at":"2026-05-23T02:32:26.692Z","avatar_url":"https://github.com/nshkrdotcom.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/sandbox.svg\" width=\"200\" alt=\"Sandbox Logo\"\u003e\n\u003c/p\u003e\n\n# Sandbox\n\nIsolated OTP application management with hot-reload capabilities for Elixir.\n\nSandbox enables you to create, manage, and hot-reload isolated OTP applications (sandboxes) within your Elixir system. Each sandbox runs with its own supervision tree and namespace-transformed modules, providing process-level separation suitable for plugin systems, development workflows, and learning environments.\n\n## Features\n\n- **Process Isolation**: Each sandbox has its own supervision tree and process hierarchy\n- **Hot Reload**: Update running sandboxes without restarting\n- **Version Management**: Track and rollback module versions\n- **Fault Tolerance**: Sandbox crashes don't affect the host application\n- **Resource Control**: Compile-time limits and process monitoring\n- **Isolated Compilation**: Compile code in a separate process with configurable timeouts\n\n## Documentation\n\nComprehensive guides are available to help you get the most out of Sandbox:\n\n### Getting Started\n- **[Getting Started](guides/getting_started.md)** - Installation, setup, and your first sandbox\n\n### Core Guides\n- **[Hot Reload](guides/hot_reload.md)** - Live code updates, version management, and state preservation\n- **[Module Transformation](guides/module_transformation.md)** - Namespace isolation and virtual code tables\n- **[Compilation](guides/compilation.md)** - Compilation backends, caching, and security\n- **[Configuration](guides/configuration.md)** - All configuration options and security profiles\n\n### Architecture\n- **[Architecture](guides/architecture.md)** - System design, components, and extension points\n- **[Evolution Substrate](guides/evolution_substrate.md)** - Vision for genetic programming and self-modifying systems\n\n\u003e **Note**: For API documentation, run `mix docs` to generate HTML documentation locally, or visit the [HexDocs](https://hexdocs.pm/sandbox).\n\n## Installation\n\nAdd `sandbox` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:sandbox, \"~\u003e 0.1.0\"}\n  ]\nend\n```\n\n## Quick Start\n\n### 1. Start Sandbox\n\nAdd Sandbox to your supervision tree:\n\n```elixir\nchildren = [\n  Sandbox,\n  # ... other children\n]\n\nSupervisor.start_link(children, strategy: :one_for_one)\n```\n\n### 2. Create a Sandbox\n\n```elixir\n# Create a sandbox with a supervisor module\n{:ok, sandbox} = Sandbox.create_sandbox(\"my-sandbox\", MyApp.Supervisor)\n\n# Or with custom options\n{:ok, sandbox} = Sandbox.create_sandbox(\"plugin-1\", :my_plugin,\n  supervisor_module: MyPlugin.Supervisor,\n  sandbox_path: \"/path/to/plugin/code\"\n)\n```\n\n### 3. Hot Reload Code\n\n```elixir\n# Compile new code\n{:ok, compile_info} = Sandbox.compile_file(\"updated_module.ex\")\n\n# Hot reload the module\n{:ok, :hot_reloaded} = Sandbox.hot_reload(\"my-sandbox\", \n  compile_info.beam_files |\u003e hd() |\u003e File.read!())\n```\n\n### 4. Manage Sandboxes\n\n```elixir\n# List all sandboxes\nsandboxes = Sandbox.list_sandboxes()\n\n# Get sandbox info\n{:ok, info} = Sandbox.get_sandbox_info(\"my-sandbox\")\n\n# Restart a sandbox\n{:ok, _} = Sandbox.restart_sandbox(\"my-sandbox\")\n\n# Destroy a sandbox\n:ok = Sandbox.destroy_sandbox(\"my-sandbox\")\n```\n\n## Advanced Usage\n\n### Module Version Management\n\nSandbox tracks all module versions and supports rollback:\n\n```elixir\n# Check current version\n{:ok, version} = Sandbox.get_module_version(\"my-sandbox\", MyModule)\n\n# List all versions\nversions = Sandbox.list_module_versions(\"my-sandbox\", MyModule)\n\n# Rollback to a previous version\n{:ok, :rolled_back} = Sandbox.rollback_module(\"my-sandbox\", MyModule, 2)\n\n# Get version history with statistics\nhistory = Sandbox.get_version_history(\"my-sandbox\", MyModule)\n# =\u003e %{current_version: 3, total_versions: 3, versions: [...]}\n```\n\n### Custom State Migration\n\nWhen hot-reloading GenServers, you can provide custom state migration logic:\n\n```elixir\n{:ok, :hot_reloaded} = Sandbox.hot_reload(\"my-sandbox\", beam_data,\n  state_handler: fn old_state, old_version, new_version -\u003e\n    # Migrate state from old version to new version\n    %{old_state | version: new_version, upgraded_at: DateTime.utc_now()}\n  end\n)\n```\n\n### Isolated Compilation\n\nCompile code in a separate process with configurable timeouts:\n\n```elixir\n# Compile a directory\n{:ok, compile_info} = Sandbox.compile_sandbox(\"/path/to/sandbox\",\n  timeout: 60_000,\n  validate_beams: true\n)\n\n# Compile a single file\n{:ok, compile_info} = Sandbox.compile_file(\"my_module.ex\")\n\n# Access compilation results\ncompile_info.beam_files     # List of compiled BEAM files\ncompile_info.output         # Compiler output\ncompile_info.compilation_time # Time taken in milliseconds\n```\n\n## Use Cases\n\n### Plugin Systems\n\nCreate a plugin system where each plugin runs in its own supervision tree:\n\n```elixir\ndefmodule MyApp.PluginManager do\n  def load_plugin(plugin_path) do\n    plugin_id = Path.basename(plugin_path)\n    \n    # Create sandbox for the plugin\n    {:ok, _} = Sandbox.create_sandbox(plugin_id, :plugin,\n      supervisor_module: Plugin.Supervisor,\n      sandbox_path: plugin_path\n    )\n    \n    # Plugin is now running in its own supervision tree\n  end\n  \n  def update_plugin(plugin_id, new_code_path) do\n    # Compile new version\n    {:ok, compile_info} = Sandbox.compile_sandbox(new_code_path)\n    \n    # Hot reload each module\n    Enum.each(compile_info.beam_files, fn beam_file -\u003e\n      beam_data = File.read!(beam_file)\n      Sandbox.hot_reload(plugin_id, beam_data)\n    end)\n  end\nend\n```\n\n### Learning Environment\n\nCreate separate environments for experimenting with OTP patterns:\n\n```elixir\ndefmodule LearningPlatform do\n  def create_exercise_sandbox(user_id, exercise_code) do\n    sandbox_id = \"exercise_#{user_id}\"\n\n    # Write exercise code to temporary directory\n    temp_dir = Path.join(System.tmp_dir!(), sandbox_id)\n    File.mkdir_p!(temp_dir)\n    File.write!(Path.join(temp_dir, \"exercise.ex\"), exercise_code)\n\n    # Compile and run in sandbox\n    {:ok, compile_info} = Sandbox.compile_sandbox(temp_dir)\n    {:ok, _} = Sandbox.create_sandbox(sandbox_id, ExerciseSupervisor,\n      sandbox_path: temp_dir\n    )\n\n    # Student's code now runs in its own supervision tree\n  end\nend\n```\n\n## Architecture\n\nSandbox is built on a modular architecture with clearly separated concerns:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                     Sandbox.Application                      │\n├─────────────────────────────────────────────────────────────┤\n│  ┌─────────────┐  ┌─────────────────┐  ┌─────────────────┐ │\n│  │   Manager   │  │ ModuleVersion   │  │   Resource      │ │\n│  │ (lifecycle) │  │    Manager      │  │   Monitor       │ │\n│  └─────────────┘  └─────────────────┘  └─────────────────┘ │\n├─────────────────────────────────────────────────────────────┤\n│  ┌─────────────┐  ┌─────────────────┐  ┌─────────────────┐ │\n│  │  Security   │  │    Process      │  │   Isolated      │ │\n│  │ Controller  │  │    Isolator     │  │   Compiler      │ │\n│  └─────────────┘  └─────────────────┘  └─────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\nEach sandbox has its own supervision tree and can be hot-reloaded independently without affecting others. For detailed architecture documentation, see the **[Architecture Guide](guides/architecture.md)**.\n\n## Best Practices\n\n1. **Set appropriate timeouts** for compilation and execution\n2. **Monitor sandbox resource usage** in production\n3. **Use version management** for safe rollbacks\n4. **Test state migration handlers** thoroughly\n5. **Clean up sandboxes** when no longer needed\n\n## Limitations\n\n**This is not a security sandbox.** Sandboxes share the same Erlang VM and are not suitable for running untrusted or potentially malicious code. All sandboxes share:\n\n- The global code server and atom table\n- Memory address space\n- Scheduler infrastructure\n- Network and file system access\n\nOther limitations:\n\n- Memory and resource limits are advisory, not enforced\n- Security profiles audit operations but do not prevent them\n- Hot-reload requires proper GenServer `code_change/3` implementation\n- Some BEAM instructions can affect the entire VM\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -am 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Create a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnshkrdotcom%2Fsandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnshkrdotcom%2Fsandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnshkrdotcom%2Fsandbox/lists"}