Add configurable CPU and memory for VMs

Author: inxilpro

README.md

@@ -1,7 +1,103 @@
 # clave
 
-Install with:
+Spin up ephemeral VMs via [Tart](https://tart.run/) for isolated [Claude Code](https://claude.ai/code) sessions. Run `clave` from within a project's
+git repo, and it handles repo cloning, VM lifecycle, networking, and teardown automatically.
+
+## Installation
 
 ```shell
 curl -fsSL https://clave.run | sh
 ```
+
+## Requirements
+
+- macOS with [Tart](https://tart.run/) installed
+- A [Claude Code](https://claude.ai/code) account
+
+## Usage
+
+### Working Directory Mode
+
+Run `clave` from within a project's git repository:
+
+```shell
+cd /path/to/your/project
+clave
+```
+
+Clave will spin up a fresh VM, mount your current working directory into the VM, and launch an interactive Claude Code session
+inside it. When you exit, the VM and clone are torn down automatically. This lets you work on the local project similar to running
+`claude`, but without having to worry about the agent accidentally deleting your home directory or getting tricked into shipping
+your SSH private key somewhere.
+
+### Isolate Mode
+
+Run `clave --isolate` from within a project's git repository:
+
+```shell
+cd /path/to/your/project
+clave --isolate
+```
+
+Before spinning up a fresh VM, clave will create a local git clone of your working directory. (This is similarly efficient as a 
+worktree, but has a copy of your full git history.) Clave will then mount that clone into the VM, keeping any changes made inside
+the VM completely isolated from your project until you quit. Once you quit, you will be prompted to decide what to do with the
+changes before the clone is cleaned up.
+
+## Configuration
+
+Add a `.clave.json` file to your project root to customize VM setup for your project.
+
+### `.clave.json`
+
+```json
+{
+  "base_image": "ghcr.io/cirruslabs/ubuntu:latest",
+  "cpus": 8,
+  "memory": 16384,
+  "provision": [
+    "sudo apt-get install -y redis-server",
+    "sudo systemctl enable redis-server"
+  ],
+  "env": [
+    "STRIPE_SECRET_KEY",
+    "CUSTOM_API_TOKEN"
+  ]
+}
+```
+
+### Options
+
+| Key          | Type     | Description                                                               |
+|--------------|----------|---------------------------------------------------------------------------|
+| `base_image` | string   | Custom Tart VM base image. Defaults to `ghcr.io/cirruslabs/ubuntu:latest` |
+| `cpus`       | integer  | CPUs allocated to the VM. Defaults to `CLAVE_VM_CPUS` (4)                 |
+| `memory`     | integer  | Memory (MB) allocated to the VM. Defaults to `CLAVE_VM_MEMORY` (8192)     |
+| `provision`  | string[] | Bash commands to run during VM provisioning                               |
+| `env`        | string[] | Environment variable names to pass through from your host into the VM     |
+
+See the [`tart` documentation](https://tart.run/quick-start/#vm-images) for a list of available base images.
+
+### Environment Variables Passed Through Automatically
+
+Clave always forwards these environment variables into the VM when present on the host:
+
+- `COLORTERM`, `FORCE_COLOR`, `NO_COLOR`
+- `GIT_AUTHOR_EMAIL`, `GIT_AUTHOR_NAME`, `GIT_COMMITTER_EMAIL`, `GIT_COMMITTER_NAME`
+- `LANG`, `LC_ALL`, `LC_CTYPE`
+- `TZ`, `VISUAL`
+
+Any additional variables listed in `.clave.json`'s `env` array are forwarded as well.
+
+## Global Configuration
+
+Clave reads the following environment variables for global defaults:
+
+| Variable                  | Default                            | Description                                      |
+|---------------------------|------------------------------------|--------------------------------------------------|
+| `ANTHROPIC_API_KEY`       | —                                  | Anthropic API key for Claude Code                |
+| `CLAUDE_CODE_OAUTH_TOKEN` | —                                  | Claude Code OAuth token (alternative to API key) |
+| `CLAVE_BASE_IMAGE`        | `ghcr.io/cirruslabs/ubuntu:latest` | Default VM base image                            |
+| `CLAVE_BASE_VM`           | `clave-base`                       | Name of the base Tart VM                         |
+| `CLAVE_VM_CPUS`           | `4`                                | CPUs allocated to each VM                        |
+| `CLAVE_VM_MEMORY`         | `8192`                             | Memory (MB) allocated to each VM                 |

app/Data/ProjectConfig.php

@@ -25,13 +25,17 @@ public static function fromProjectDir(string $project_dir, Filesystem $fs): stat
 			base_image: $data['base_image'] ?? null,
 			provision: $data['provision'] ?? [],
 			env: $data['env'] ?? [],
+			cpus: isset($data['cpus']) ? (int) $data['cpus'] : null,
+			memory: isset($data['memory']) ? (int) $data['memory'] : null,
 		);
 	}
 
 	public function __construct(
 		public readonly ?string $base_image = null,
 		public readonly array $provision = [],
 		public readonly array $env = [],
+		public readonly ?int $cpus = null,
+		public readonly ?int $memory = null,
 	) {
 	}
 

app/Pipelines/Steps/CloneVm.php

@@ -25,8 +25,8 @@ public function handle(SessionContext $context, Closure $next): mixed
 
 		$context->vm_name = $vm_name;
 
-		$cpus = config('clave.vm.cpus');
-		$memory = config('clave.vm.memory');
+		$cpus = $context->project_config->cpus ?? config('clave.vm.cpus');
+		$memory = $context->project_config->memory ?? config('clave.vm.memory');
 		$display = config('clave.vm.display');
 
 		if ($cpus || $memory || $display) {

tests/Unit/Dto/ProjectConfigTest.php

@@ -72,15 +72,33 @@
 	$fs->shouldReceive('get')->with('/path/to/project/.clave.json')->andReturn(json_encode([
 		'base_image' => 'ghcr.io/custom/image:latest',
 		'provision' => ['sudo apt-get install -y redis-server'],
+		'cpus' => 8,
+		'memory' => 16384,
 	]));
 
 	$config = ProjectConfig::fromProjectDir('/path/to/project', $fs);
 
 	expect($config->base_image)->toBe('ghcr.io/custom/image:latest')
 		->and($config->provision)->toBe(['sudo apt-get install -y redis-server'])
+		->and($config->cpus)->toBe(8)
+		->and($config->memory)->toBe(16384)
 		->and($config->hasCustomizations())->toBeTrue();
 });
 
+test('fromProjectDir parses cpus and memory', function() {
+	$fs = Mockery::mock(Filesystem::class);
+	$fs->shouldReceive('exists')->with('/path/to/project/.clave.json')->andReturn(true);
+	$fs->shouldReceive('get')->with('/path/to/project/.clave.json')->andReturn(json_encode([
+		'cpus' => 2,
+		'memory' => 4096,
+	]));
+
+	$config = ProjectConfig::fromProjectDir('/path/to/project', $fs);
+
+	expect($config->cpus)->toBe(2)
+		->and($config->memory)->toBe(4096);
+});
+
 test('fromProjectDir handles invalid json gracefully', function() {
 	$fs = Mockery::mock(Filesystem::class);
 	$fs->shouldReceive('exists')->with('/path/to/project/.clave.json')->andReturn(true);