@superhq/shuru 0.1.2 → 0.2.0

package/README.md

@@ -42,6 +42,10 @@ const sb = await Sandbox.start({
   allowNet: true,
   ports: ["8080:80"],
   mounts: { "./src": "/workspace" },
+  secrets: {
+    API_KEY: { from: "OPENAI_API_KEY", hosts: ["api.openai.com"] },
+  },
+  network: { allow: ["api.openai.com", "registry.npmjs.org"] },
 });
 ```
 
@@ -54,6 +58,8 @@ const sb = await Sandbox.start({
 | `allowNet` | `boolean` | Enable network access |
 | `ports` | `string[]` | Port forwards (`"host:guest"`) |
 | `mounts` | `Record<string, string>` | Directory mounts (`{ hostPath: guestPath }`) |
+| `secrets` | `Record<string, SecretConfig>` | Secrets to inject via proxy (see below) |
+| `network` | `NetworkConfig` | Network access policy (see below) |
 | `shuruBin` | `string` | Path to shuru binary (default: `"shuru"`) |
 
 ## API
@@ -82,6 +88,34 @@ Save the VM's disk state and stop the VM. To continue working, call `Sandbox.sta
 
 Stop the VM without saving. All changes are discarded.
 
+### Secrets
+
+Secrets keep API keys on the host. The guest receives a random placeholder token; the proxy substitutes the real value only on HTTPS requests to the specified hosts.
+
+```ts
+const sb = await Sandbox.start({
+  allowNet: true,
+  secrets: {
+    API_KEY: { from: "OPENAI_API_KEY", hosts: ["api.openai.com"] },
+  },
+});
+// Inside the VM, $API_KEY is a placeholder token.
+// Requests to api.openai.com get the real key injected by the proxy.
+```
+
+### Network policy
+
+Restrict which domains the guest can reach:
+
+```ts
+const sb = await Sandbox.start({
+  allowNet: true,
+  network: { allow: ["api.openai.com", "*.npmjs.org"] },
+});
+```
+
+Omit `network.allow` to allow all domains.
+
 ## Requirements
 
 - macOS 14+ on Apple Silicon

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superhq/shuru",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/index.ts

@@ -1,2 +1,7 @@
 export { Sandbox } from "./sandbox";
-export type { ExecResult, StartOptions } from "./types";
+export type {
+	ExecResult,
+	NetworkConfig,
+	SecretConfig,
+	StartOptions,
+} from "./types";

package/src/sandbox.ts

@@ -76,6 +76,18 @@ export function buildArgs(bin: string, opts: StartOptions): string[] {
 	if (opts.diskSize) args.push("--disk-size", String(opts.diskSize));
 	if (opts.allowNet) args.push("--allow-net");
 
+	if (opts.secrets) {
+		for (const [name, secret] of Object.entries(opts.secrets)) {
+			args.push("--secret", `${name}=${secret.from}@${secret.hosts.join(",")}`);
+		}
+	}
+
+	if (opts.network?.allow) {
+		for (const host of opts.network.allow) {
+			args.push("--allow-host", host);
+		}
+	}
+
 	if (opts.ports) {
 		for (const p of opts.ports) {
 			args.push("-p", p);

package/src/types.ts

@@ -1,3 +1,15 @@
+export interface SecretConfig {
+	/** Host environment variable containing the real value. */
+	from: string;
+	/** Domains where this secret may be sent (e.g. "api.openai.com"). */
+	hosts: string[];
+}
+
+export interface NetworkConfig {
+	/** Allowed domain patterns. Omit to allow all. */
+	allow?: string[];
+}
+
 export interface StartOptions {
 	from?: string;
 	cpus?: number;
@@ -6,6 +18,8 @@ export interface StartOptions {
 	allowNet?: boolean;
 	ports?: string[];
 	mounts?: Record<string, string>;
+	secrets?: Record<string, SecretConfig>;
+	network?: NetworkConfig;
 	shuruBin?: string;
 }