Merge pull request #2 from pepicrft/add-reconnect-serialization

feat: Add sandbox serialization and reconnect support

Author: pepicrft

AGENTS.md

@@ -3,3 +3,8 @@
 ## Workflow
 
 - After every change, create a git commit and push it to the current branch.
+
+## Testing
+
+- Never modify global state in tests (e.g. `Application.put_env`, `Application.delete_env`). All tests must be safe to run with `async: true`.
+- For running bash commands from Elixir, use `MuonTrap` instead of `System`. Prefer `MuonTrap` because it propagates process shutdowns to child processes. Reference: https://hexdocs.pm/muontrap/readme.html

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

README.md

@@ -15,6 +15,9 @@ The AI agent ecosystem is producing many sandbox environment providers — Dayto
 - **Provider behaviour** — a single contract for creating, destroying, and querying sandbox environments
 - **Process execution** — run commands in sandboxes with structured results
 - **File operations** — read, write, and list files within sandboxes
+- **Named providers** — configure multiple providers with their credentials, pick a default
+- **Local provider** — built-in provider for dev/test that runs everything on the local machine
+- **Serialization** — persist and restore sandbox references across client restarts
 - **Provider-agnostic** — swap providers without changing application code
 
 ## Installation
@@ -29,6 +32,46 @@ def deps do
 end
 ```
 
+## Configuration
+
+Configure multiple providers and set a default, similar to Finch pools:
+
+```elixir
+# config/runtime.exs
+config :terrarium,
+  default: :daytona,
+  providers: [
+    daytona: {Terrarium.Daytona, api_key: System.fetch_env!("DAYTONA_API_KEY"), region: "us"},
+    e2b: {Terrarium.E2B, api_key: System.fetch_env!("E2B_API_KEY")},
+    local: Terrarium.Providers.Local
+  ]
+```
+
+Connect to an existing machine via SSH:
+
+```elixir
+config :terrarium,
+  default: :server,
+  providers: [
+    server: {Terrarium.Providers.SSH,
+      host: "dev.example.com",
+      user: "deploy",
+      auth: {:key, System.fetch_env!("SSH_PRIVATE_KEY")}
+    }
+  ]
+```
+
+For development, use the built-in local provider:
+
+```elixir
+# config/dev.exs
+config :terrarium,
+  default: :local,
+  providers: [
+    local: Terrarium.Providers.Local
+  ]
+```
+
 ## Quick Start
 
 ### 1. Add a provider package
@@ -45,11 +88,14 @@ end
 ### 2. Create and use a sandbox
 
 ```elixir
-# Create a sandbox
-{:ok, sandbox} = Terrarium.create(Terrarium.Daytona,
-  image: "debian:12",
-  resources: %{cpu: 2, memory: 4}
-)
+# Uses the configured default provider
+{:ok, sandbox} = Terrarium.create(image: "debian:12")
+
+# Or use a specific named provider
+{:ok, sandbox} = Terrarium.create(:e2b, image: "debian:12")
+
+# Or pass a provider module directly
+{:ok, sandbox} = Terrarium.create(Terrarium.Daytona, image: "debian:12", api_key: "...")
 
 # Execute commands
 {:ok, result} = Terrarium.exec(sandbox, "echo hello")
@@ -63,6 +109,21 @@ IO.puts(result.stdout)
 :ok = Terrarium.destroy(sandbox)
 ```
 
+### 3. Surviving client restarts
+
+Sandboxes can be serialized and restored if the client process restarts while the remote sandbox is still running:
+
+```elixir
+# Persist before shutdown
+data = Terrarium.Sandbox.to_map(sandbox)
+MyStore.save("sandbox-123", data)
+
+# Restore after restart
+data = MyStore.load("sandbox-123")
+sandbox = Terrarium.Sandbox.from_map(data)
+{:ok, sandbox} = Terrarium.reconnect(sandbox)
+```
+
 ## Implementing a Provider
 
 Providers implement the `Terrarium.Provider` behaviour:
@@ -88,6 +149,12 @@ defmodule MyProvider do
     :running
   end
 
+  @impl true
+  def reconnect(sandbox) do
+    # Verify the sandbox is still alive, refresh tokens, etc.
+    {:ok, sandbox}
+  end
+
   @impl true
   def exec(sandbox, command, opts) do
     # Execute the command
@@ -111,12 +178,44 @@ end
 
 | Provider | Package | Status |
 |---|---|---|
+| Local | `terrarium` (built-in) | Available |
+| SSH | `terrarium` (built-in) | Available |
 | [Daytona](https://daytona.io) | `terrarium_daytona` | Planned |
 | [E2B](https://e2b.dev) | `terrarium_e2b` | Planned |
 | [Modal](https://modal.com) | `terrarium_modal` | Planned |
 | [Fly Sprites](https://sprites.dev) | `terrarium_sprites` | Planned |
 | [Namespace](https://namespace.so) | `terrarium_namespace` | Planned |
 
+## Telemetry
+
+Terrarium emits telemetry events for all operations via `:telemetry.span/3`. Each operation emits `:start`, `:stop`, and `:exception` events automatically.
+
+| Event | Metadata |
+|---|---|
+| `[:terrarium, :create, *]` | `%{provider: module}` |
+| `[:terrarium, :destroy, *]` | `%{sandbox: sandbox}` |
+| `[:terrarium, :exec, *]` | `%{sandbox: sandbox, command: string}` |
+| `[:terrarium, :read_file, *]` | `%{sandbox: sandbox, path: string}` |
+| `[:terrarium, :write_file, *]` | `%{sandbox: sandbox, path: string}` |
+| `[:terrarium, :ls, *]` | `%{sandbox: sandbox, path: string}` |
+| `[:terrarium, :reconnect, *]` | `%{sandbox: sandbox}` |
+| `[:terrarium, :status, *]` | `%{sandbox: sandbox}` |
+
+```elixir
+:telemetry.attach_many(
+  "terrarium-logger",
+  [
+    [:terrarium, :create, :stop],
+    [:terrarium, :exec, :stop],
+    [:terrarium, :destroy, :stop]
+  ],
+  fn event, measurements, metadata, _config ->
+    Logger.info("#{inspect(event)} took #{measurements.duration} native time units")
+  end,
+  nil
+)
+```
+
 ## License
 
 This project is licensed under the [MIT License](LICENSE).