Fremde Laufzeiten: Claude Code und Befehl in der Sandbox, Egress-Proxy, Vorschlag statt Einsatz (#712)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/ClawdDotNet.App/AppHost.cs

@@ -598,6 +598,23 @@ public sealed class AppHost : IAsyncDisposable
         foreach (var user in tools.GetAll().OfType<Core.Sandbox.ISandboxUser>())
             user.Sandbox = sandbox;
 
+        // #712: Foreign runtimes. The application itself is the launcher inside the sandbox
+        // (network through the proxy, secrets from a file) and the MCP bridge back to us.
+        var mcpGrants = new Core.Mcp.McpGrants(storage);
+        var helper = Core.Sandbox.SandboxHelper.ForThisProcess();
+        if (sandbox is Core.Sandbox.BwrapSandbox bwrap)
+        {
+            bwrap.Helper = helper;
+            bwrap.LoggerFactory = loggerFactory;
+        }
+        engine.ForeignRunner = new Core.Runtimes.ForeignRunner(
+            sandbox,
+            [new Core.Runtimes.ClaudeCodeRuntime(() => instance.ClaudeCode), new Core.Runtimes.CommandRuntime()],
+            mcpGrants,
+            OperatingSystem.IsWindows() ? null : Core.Instances.InstanceEndpoint.McpSocketPath(instancePath),
+            helper,
+            loggerFactory.CreateLogger("ClawdDotNet.Core.Runtimes"));
+
         engine.SetAgentConfigProvider(
             () => instance.Agents,
             instance.InstanceId,
@@ -638,7 +655,7 @@ public sealed class AppHost : IAsyncDisposable
             Transcripts = transcripts,
             Cases = cases,
             SpecialBudgets = specialBudgets,
-            Mcp = new Core.Mcp.McpGrants(storage),
+            Mcp = mcpGrants,
             Insights = new RunInsights(audit, transcripts, board, staging,
                 agentId => instance.Agents.FirstOrDefault(a => a.AgentId == agentId) is { } agent
                     ? engine.TranscriptRetentionFor(agent)

src/ClawdDotNet.App/Services/AgentAdministration.cs

@@ -298,6 +298,81 @@ public sealed class AgentAdministration(AppHost host)
             : $"Prompt history of '{agent.DisplayName}': {Core.Transcripts.PromptHistorySettings.Describe(retentionDays.Value)}.");
     }
 
+    /// <summary>
+    /// #712: The runtime an agent works in. Checked here, not at the next run: a list of
+    /// hosts that does not parse or a command-less command runtime would otherwise show up
+    /// only as a failed run at night.
+    /// </summary>
+    public AdminResult SetRuntime(string agentId, Core.Runtimes.AgentRuntimeConfig runtime)
+    {
+        if (Find(agentId) is not { } agent)
+            return AdminResult.Failure($"No agent with id '{agentId}'.");
+        if (ValidateRuntime(runtime) is { } problem)
+            return AdminResult.Failure(problem);
+
+        runtime.Kind = Core.Runtimes.RuntimeKinds.Normalize(runtime.Kind);
+        runtime.AllowedTools = runtime.AllowedTools.Select(t => t.Trim()).Where(t => t.Length > 0).Distinct().ToList();
+        runtime.Egress = runtime.Egress.Select(e => e.Trim()).Where(e => e.Length > 0).Distinct().ToList();
+        runtime.Arguments = runtime.Arguments.ToList();
+        agent.Runtime = runtime;
+        PersistAgent(agent);
+        host.SaveInstance(new InstanceChange(InstanceChangeKind.Agents, agentId));
+
+        return AdminResult.Success(runtime.IsForeign
+            ? $"'{agent.DisplayName}' now works in {runtime.Kind}, in the sandbox."
+            : $"'{agent.DisplayName}' works natively again.");
+    }
+
+    public static string? ValidateRuntime(Core.Runtimes.AgentRuntimeConfig runtime)
+    {
+        if (!Core.Runtimes.RuntimeKinds.IsKnown(runtime.Kind))
+            return $"Unknown runtime '{runtime.Kind}' — known are {string.Join(", ", Core.Runtimes.RuntimeKinds.All)}.";
+        if (runtime.MaxTurns is < 1 or > 500)
+            return "Turns must be between 1 and 500.";
+        if (runtime.TimeoutMinutes is < 1 or > 240)
+            return "The time limit must be between 1 and 240 minutes.";
+        if (Core.Runtimes.RuntimeKinds.Normalize(runtime.Kind) == Core.Runtimes.RuntimeKinds.Command
+            && string.IsNullOrWhiteSpace(runtime.Command))
+            return "The command runtime needs a command.";
+        // A tool name, possibly with a pattern in parentheses — never an option in disguise.
+        if (runtime.AllowedTools.FirstOrDefault(t => t.TrimStart().StartsWith('-') || t.Contains(',')) is { } odd)
+            return $"'{odd}' is not a tool name.";
+        try
+        {
+            Core.Sandbox.EgressRules.Parse(runtime.Egress);
+        }
+        catch (ArgumentException ex)
+        {
+            return ex.Message;
+        }
+        return null;
+    }
+
+    /// <summary>
+    /// #712: The instance's Claude Code account. Keys are only ever replaced, never read
+    /// back; an empty value keeps the one there is.
+    /// </summary>
+    public AdminResult SetClaudeCode(string? executable, string? auth, string? apiKey, string? oauthToken)
+    {
+        var settings = host.Instance.ClaudeCode;
+        var mode = string.IsNullOrWhiteSpace(auth) ? settings.Auth : auth.Trim().ToLowerInvariant();
+        if (mode is not (Core.Runtimes.ClaudeCodeSettings.ApiKeyAuth or Core.Runtimes.ClaudeCodeSettings.SubscriptionAuth))
+            return AdminResult.Failure($"Unknown sign-in '{auth}'.");
+
+        settings.Auth = mode;
+        if (executable is not null)
+            settings.Executable = executable.Trim();
+        if (!string.IsNullOrWhiteSpace(apiKey))
+            settings.ApiKey = apiKey.Trim();
+        if (!string.IsNullOrWhiteSpace(oauthToken))
+            settings.OAuthToken = oauthToken.Trim();
+        host.SaveInstance(new InstanceChange(InstanceChangeKind.Settings));
+
+        return AdminResult.Success(settings.OnSubscription
+            ? "Claude Code runs on the subscription."
+            : "Claude Code runs on the API key.");
+    }
+
     /// <summary>#660: Instance default retention of the prompt history, in days.</summary>
     public AdminResult SetDefaultPromptHistoryRetention(int retentionDays)
     {

src/ClawdDotNet.Core/Accounting/SqliteUsageRepository.cs

@@ -31,10 +31,12 @@ public sealed class SqliteUsageRepository : IUsageRepository
             cmd.CommandText = """
                 INSERT INTO RunUsage
                     (AgentId, Model, PromptTokens, CompletionTokens, CachedTokens,
-                     CostUsd, CostIsKnown, Status, StepCount, DurationMs, OccurredAt, UsageDate, BudgetPot)
+                     CostUsd, CostIsKnown, Status, StepCount, DurationMs, OccurredAt, UsageDate, BudgetPot,
+                     Runtime, OnSubscription)
                 VALUES
                     (@agentId, @model, @prompt, @completion, @cached,
-                     @cost, @costKnown, @status, @steps, @duration, @occurredAt, @usageDate, @pot)
+                     @cost, @costKnown, @status, @steps, @duration, @occurredAt, @usageDate, @pot,
+                     @runtime, @subscription)
                 """;
 
             cmd.Parameters.AddWithValue("@agentId", usage.AgentId);
@@ -50,6 +52,8 @@ public sealed class SqliteUsageRepository : IUsageRepository
             cmd.Parameters.AddWithValue("@occurredAt", occurredAt.ToString("O"));
             cmd.Parameters.AddWithValue("@usageDate", FormatDate(DateOnly.FromDateTime(occurredAt)));
             cmd.Parameters.AddWithValue("@pot", usage.BudgetPot ?? "");
+            cmd.Parameters.AddWithValue("@runtime", usage.Runtime ?? "");
+            cmd.Parameters.AddWithValue("@subscription", usage.OnSubscription ? 1 : 0);
 
             await cmd.ExecuteNonQueryAsync(ct);
         }, ct);
@@ -118,7 +122,7 @@ public sealed class SqliteUsageRepository : IUsageRepository
         using var cmd = conn.CreateCommand();
         cmd.CommandText = """
             SELECT Id, AgentId, Model, PromptTokens, CompletionTokens, CachedTokens,
-                   CostUsd, CostIsKnown, Status, StepCount, DurationMs, OccurredAt
+                   CostUsd, CostIsKnown, Status, StepCount, DurationMs, OccurredAt, Runtime, OnSubscription
               FROM RunUsage
              ORDER BY OccurredAt DESC
              LIMIT @limit
@@ -139,7 +143,7 @@ public sealed class SqliteUsageRepository : IUsageRepository
         using var cmd = conn.CreateCommand();
         cmd.CommandText = """
             SELECT Id, AgentId, Model, PromptTokens, CompletionTokens, CachedTokens,
-                   CostUsd, CostIsKnown, Status, StepCount, DurationMs, OccurredAt
+                   CostUsd, CostIsKnown, Status, StepCount, DurationMs, OccurredAt, Runtime, OnSubscription
               FROM RunUsage
              WHERE AgentId = @agent COLLATE NOCASE
                -- #717: a special budget's runs are the large kind; they would inflate the
@@ -184,7 +188,9 @@ public sealed class SqliteUsageRepository : IUsageRepository
         StepCount = reader.GetInt32(9),
         DurationMs = reader.GetInt64(10),
         OccurredAt = DateTime.TryParse(reader.GetString(11), null,
-            DateTimeStyles.RoundtripKind, out var dt) ? dt : DateTime.MinValue
+            DateTimeStyles.RoundtripKind, out var dt) ? dt : DateTime.MinValue,
+        Runtime = reader.GetString(12),
+        OnSubscription = reader.GetInt32(13) != 0
     };
 
     private static string FormatDate(DateOnly date) => date.ToString("yyyy-MM-dd");

src/ClawdDotNet.Core/Accounting/UsageModels.cs

@@ -34,6 +34,12 @@ public sealed record RunUsage
     /// runs do not count against the daily limits — that is what the pot is for.
     /// </summary>
     public string BudgetPot { get; init; } = "";
+
+    /// <summary>#712: The runtime of the run; empty for native.</summary>
+    public string Runtime { get; init; } = "";
+
+    /// <summary>#712: Paid from a subscription's quota. The cost is 0 $, the tokens are real (#699).</summary>
+    public bool OnSubscription { get; init; }
 }
 
 /// <summary>Verbrauch eines Tages, aggregiert.</summary>

src/ClawdDotNet.Core/Config/AgentConfig.cs

@@ -177,6 +177,10 @@ public sealed class AgentConfig
     [JsonPropertyName("promptHistory")]
     public Transcripts.AgentPromptHistorySettings PromptHistory { get; set; } = new();
 
+    /// <summary>#712: Where the agent's runs happen — natively (default) or in a foreign runtime.</summary>
+    [JsonPropertyName("runtime")]
+    public Runtimes.AgentRuntimeConfig Runtime { get; set; } = new();
+
     /// <summary>
     /// Übersetzt <see cref="ReasoningEffort"/> in das Anfragefeld. Null heißt:
     /// nichts mitschicken, das Modell denkt wie voreingestellt.

src/ClawdDotNet.Core/Config/InstanceConfig.cs

@@ -151,6 +151,10 @@ public sealed class InstanceConfig
     [JsonPropertyName("fillWork")]
     public Budget.FillWorkSettings FillWork { get; set; } = new();
 
+    /// <summary>#712: The Claude Code account the instance's claude-code agents run on.</summary>
+    [JsonPropertyName("claudeCode")]
+    public Runtimes.ClaudeCodeSettings ClaudeCode { get; set; } = new();
+
     [JsonPropertyName("maxDelegationDepth")]
     public int MaxDelegationDepth { get; set; } = 3;
 

src/ClawdDotNet.Core/Engine/AgentEngine.cs

@@ -63,6 +63,13 @@ public sealed class AgentEngine : IAgentMessageRouter, Staging.IFrozenCallExecut
     /// <summary>#654: The sandbox tools run code in.</summary>
     public Sandbox.ISandboxRunner? Sandbox { get; set; }
 
+    /// <summary>
+    /// #712: Runs agents whose runtime is not native — Claude Code, a command. Without it such
+    /// an agent does not run at all; it never falls back to the native engine, whose model and
+    /// costs are not what was configured.
+    /// </summary>
+    public Runtimes.ForeignRunner? ForeignRunner { get; set; }
+
     private Organisation.OrgChart CurrentOrganisation()
         => OrganisationProvider?.Invoke() ?? new Organisation.OrgChart([], _agentConfigProvider?.Invoke() ?? []);
 
@@ -212,7 +219,9 @@ public sealed class AgentEngine : IAgentMessageRouter, Staging.IFrozenCallExecut
         var chain = delegation ?? DelegationChain.Root(agentConfig.AgentId);
         using var activity = Activity.Begin(runId, agentConfig.AgentId, source ?? AuditSource.Direct, taskId, chain);
         var recorder = CreateRecorder(agentConfig);
-        var result = await RunCoreAsync(agentConfig, userMessage, instanceId, externalCt, runId, source, chain, recorder);
+        var result = agentConfig.Runtime.IsForeign
+            ? await RunForeignAsync(agentConfig, userMessage, externalCt, runId, source, taskId, recorder)
+            : await RunCoreAsync(agentConfig, userMessage, instanceId, externalCt, runId, source, chain, recorder);
         activity.Complete(result.Status.ToString());
         await RecordUsageAsync(agentConfig, result, pot);
         await RecordReceiptAsync(runId, agentConfig, result, source ?? AuditSource.Direct, taskId, chain.CallerRunId, pot);
@@ -475,6 +484,73 @@ public sealed class AgentEngine : IAgentMessageRouter, Staging.IFrozenCallExecut
         }
     }
 
+    /// <summary>
+    /// #712: One run in a foreign runtime. The briefing is the one a native run gets — rules,
+    /// organisation — and the message carries time and source the same way. Budget, receipt,
+    /// usage and transcript are handled by the caller as for any run.
+    /// </summary>
+    private async Task<AgentRunResult> RunForeignAsync(
+        AgentConfig agentConfig, string userMessage, CancellationToken ct, string runId, string? source, string? taskId,
+        Transcripts.RunTranscriptRecorder recorder)
+    {
+        var logger = _loggerFactory.CreateLogger($"ClawdDotNet.Core.Engine.{agentConfig.AgentId}");
+        var sw = Stopwatch.StartNew();
+        var briefing = SystemPromptFor(agentConfig, hasTools: true);
+        var message = MitZeit(userMessage, source);
+        recorder.Begin(briefing, message, userMessage);
+
+        Runtimes.ForeignRunOutcome outcome;
+        Exception? error = null;
+        if (ForeignRunner is null)
+        {
+            outcome = new Runtimes.ForeignRunOutcome
+            {
+                Status = AgentRunStatus.Failed,
+                Text = $"[Not run: the runtime '{agentConfig.Runtime.Kind}' is not set up in this instance]"
+            };
+        }
+        else
+        {
+            try
+            {
+                outcome = await ForeignRunner.RunAsync(
+                    new Runtimes.ForeignRunRequest(agentConfig, runId, taskId, briefing, message), recorder.Event, ct);
+            }
+            catch (OperationCanceledException)
+            {
+                outcome = new Runtimes.ForeignRunOutcome { Status = AgentRunStatus.Cancelled, Text = "[Cancelled]" };
+            }
+            catch (Exception ex)
+            {
+                logger.LogError(ex, "Foreign run failed: {AgentId}", agentConfig.AgentId);
+                error = ex;
+                outcome = new Runtimes.ForeignRunOutcome { Status = AgentRunStatus.Failed, Text = $"[Failed: {ex.Message}]" };
+            }
+        }
+        sw.Stop();
+
+        if (outcome.Text is { } text)
+            recorder.ModelStep(ChatMessage.Assistant(text), null, outcome.Status == AgentRunStatus.Completed ? "stop" : null);
+        logger.LogInformation("Foreign run {Status}: {AgentId} in {Runtime}, turns={Turns}, tokens={Tokens}, duration={Duration}ms",
+            outcome.Status, agentConfig.AgentId, agentConfig.Runtime.Kind, outcome.Turns,
+            outcome.PromptTokens + outcome.CompletionTokens, sw.ElapsedMilliseconds);
+
+        var result = new AgentRunResult(
+            agentConfig.AgentId, outcome.Status, outcome.Text, outcome.Turns,
+            outcome.PromptTokens + outcome.CompletionTokens, sw.Elapsed, error)
+        {
+            PromptTokens = outcome.PromptTokens,
+            CompletionTokens = outcome.CompletionTokens,
+            CachedTokens = outcome.CachedTokens,
+            ReportedCostUsd = outcome.CostUsd,
+            Runtime = Runtimes.RuntimeKinds.Normalize(agentConfig.Runtime.Kind),
+            OnSubscription = outcome.OnSubscription,
+            ActualModel = outcome.Model
+        };
+        OnRunCompleted?.Invoke(agentConfig.Model, result);
+        return result;
+    }
+
     public async Task<AgentRunResult> ChatAsync(
         AgentConfig agentConfig,
         string userMessage,
@@ -535,7 +611,19 @@ public sealed class AgentEngine : IAgentMessageRouter, Staging.IFrozenCallExecut
             // #711: "working" starts past the gate — waiting for it is not working.
             using var activity = Activity.Begin(runId, agentConfig.AgentId, source ?? AuditSource.Direct, taskId, chain);
             var recorder = CreateRecorder(agentConfig);
-            var result = await ChatCoreAsync(agentConfig, userMessage, instanceId, runCts.Token, source, runId, chain, recorder);
+            AgentRunResult result;
+            if (agentConfig.Runtime.IsForeign)
+            {
+                // #712: A foreign runtime has no conversation to continue — each message is a
+                // run of its own. The chat shows both sides all the same.
+                AddChatEntry(agentConfig.AgentId, "user", userMessage, source);
+                result = await RunForeignAsync(agentConfig, userMessage, runCts.Token, runId, source, taskId, recorder);
+                AddChatEntry(agentConfig.AgentId, "assistant", result.FinalMessage ?? $"[{result.Status}]", source);
+            }
+            else
+            {
+                result = await ChatCoreAsync(agentConfig, userMessage, instanceId, runCts.Token, source, runId, chain, recorder);
+            }
             activity.Complete(result.Status.ToString());
             await RecordUsageAsync(agentConfig, result, pot);
             await RecordReceiptAsync(runId, agentConfig, result, source, taskId, chain.CallerRunId, pot);
@@ -1931,7 +2019,7 @@ public sealed class AgentEngine : IAgentMessageRouter, Staging.IFrozenCallExecut
             await _usageRepository.RecordAsync(new RunUsage
             {
                 AgentId = agentConfig.AgentId,
-                Model = agentConfig.Model,
+                Model = result.ActualModel ?? agentConfig.Model,
                 PromptTokens = result.PromptTokens,
                 CompletionTokens = result.CompletionTokens,
                 CachedTokens = result.CachedTokens,
@@ -1941,7 +2029,9 @@ public sealed class AgentEngine : IAgentMessageRouter, Staging.IFrozenCallExecut
                 StepCount = result.StepCount,
                 DurationMs = (long)result.Duration.TotalMilliseconds,
                 OccurredAt = DateTime.Now,
-                BudgetPot = budgetPot ?? ""
+                BudgetPot = budgetPot ?? "",
+                Runtime = result.Runtime,
+                OnSubscription = result.OnSubscription
             }, CancellationToken.None);
         }
         catch (Exception ex)

src/ClawdDotNet.Core/Engine/AgentRunResult.cs

@@ -30,6 +30,15 @@ public sealed record AgentRunResult(
     /// Cache-Schreibaufschläge, abweichende Preise je Anbieter, Rabatte.</para>
     /// </summary>
     public decimal? ReportedCostUsd { get; init; }
+
+    /// <summary>#712: The runtime the run happened in; empty for native.</summary>
+    public string Runtime { get; init; } = "";
+
+    /// <summary>#712: Paid from a subscription's quota — 0 $, but not free (#699).</summary>
+    public bool OnSubscription { get; init; }
+
+    /// <summary>#712: The model a foreign runtime reported, when it differs from the configured name.</summary>
+    public string? ActualModel { get; init; }
 }
 
 public enum AgentRunStatus

src/ClawdDotNet.Core/Instances/InstanceEndpoint.cs

@@ -51,6 +51,16 @@ public static class InstanceEndpoint
             BaseAddress = new Uri("http://instanz")
         };
 
+    /// <summary>
+    /// #712: A client for an MCP socket at a path of its own — inside a sandbox, where the
+    /// instance directory does not exist and only the socket is mounted. Unix sockets only.
+    /// </summary>
+    public static HttpClient CreateMcpClientForSocket(string socketPath)
+        => new(CreateHandler(socketPath, ""))
+        {
+            BaseAddress = new Uri("http://instanz")
+        };
+
     /// <summary>
     /// Ob auf dieser Maschine eine Named Pipe statt eines Unix-Domain-Sockets benutzt
     /// wird.

src/ClawdDotNet.Core/Mcp/McpStdioBridge.cs

@@ -22,6 +22,9 @@ namespace ClawdDotNet.Core.Mcp;
 public static class McpStdioBridge
 {
     public const string Argument = "--mcp-bridge";
+
+    /// <summary>#712: The socket itself instead of the instance directory — inside a sandbox.</summary>
+    public const string SocketArgument = "--socket";
     public const string TokenVariable = "CLAWD_MCP_TOKEN";
     public const string TokenFileVariable = "CLAWD_MCP_TOKEN_FILE";
 

src/ClawdDotNet.Core/Runtimes/ClaudeCodeRuntime.cs

@@ -0,0 +1,318 @@
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using ClawdDotNet.Core.Engine;
+using ClawdDotNet.Core.Sandbox;
+
+namespace ClawdDotNet.Core.Runtimes;
+
+/// <summary>
+/// #712: Claude Code as a runtime — <c>claude -p</c> in the sandbox.
+///
+/// <para><b>Allow lists, never the bypass.</b> Claude Code gets <c>--allowedTools</c> and
+/// <c>--max-turns</c>; <c>--dangerously-skip-permissions</c> is never passed. In print mode
+/// there is no one to ask, so what is not allowed is denied.</para>
+///
+/// <para><b>Only our configuration counts.</b> The work copy may carry a
+/// <c>.claude/settings.json</c> or an <c>.mcp.json</c> — written by whoever wrote the
+/// workspace. <c>--setting-sources user</c> reads only the settings this class writes into
+/// the runtime's home before each run; <c>--strict-mcp-config</c> only the one MCP server,
+/// ours. Hooks are off, and what a run left in the home that would instruct the next one
+/// (agents, commands, skills, a CLAUDE.md) is removed before it starts.</para>
+///
+/// <para><b>Nothing secret on the command line.</b> The key goes through the launcher's
+/// file; the prompt through stdin; the briefing through a file.</para>
+/// </summary>
+public sealed class ClaudeCodeRuntime(Func<ClaudeCodeSettings> settings) : IForeignRuntime
+{
+    public string Kind => RuntimeKinds.ClaudeCode;
+
+    /// <summary>Reading and editing the work copy, and our MCP server. No shell, no web.</summary>
+    public static readonly IReadOnlyList<string> DefaultAllowedTools = ["Read", "Edit", "Write", "Glob", "Grep", "mcp__clawd"];
+
+    /// <summary>Denied even when listed — the web goes through our tools (#193), not around them.</summary>
+    public static readonly IReadOnlyList<string> AlwaysDenied = ["WebFetch", "WebSearch"];
+
+    /// <summary>The hosts Claude Code needs: the API. Updates and telemetry are switched off.</summary>
+    public static readonly IReadOnlyList<string> Egress = ["api.anthropic.com"];
+
+    private static readonly string[] Candidates =
+    [
+        "~/.local/bin/claude", "~/.claude/local/claude", "/usr/local/bin/claude", "/usr/bin/claude"
+    ];
+
+    /// <summary>The program, as configured or where an installer puts it; links resolved.</summary>
+    public static string? Locate(ClaudeCodeSettings settings)
+    {
+        var home = Environment.GetFolderPath(Environment.SpecialFolder.UserProfile);
+        var candidates = string.IsNullOrWhiteSpace(settings.Executable) ? Candidates : [settings.Executable];
+        foreach (var candidate in candidates)
+        {
+            var path = candidate.StartsWith("~/", StringComparison.Ordinal) ? Path.Combine(home, candidate[2..]) : candidate;
+            if (!File.Exists(path))
+                continue;
+            var target = new FileInfo(path).ResolveLinkTarget(returnFinalTarget: true);
+            return target?.FullName ?? Path.GetFullPath(path);
+        }
+        return null;
+    }
+
+    public SandboxRequest Prepare(ForeignRunContext context)
+    {
+        var config = settings();
+        var executable = Locate(config)
+            ?? throw new ForeignRunException("Claude Code is not installed here — set 'claudeCode.executable' in the instance configuration.");
+        var secret = config.OnSubscription ? config.OAuthToken : config.ApiKey;
+        if (string.IsNullOrWhiteSpace(secret))
+            throw new ForeignRunException(config.OnSubscription
+                ? "No subscription token for Claude Code — run 'claude setup-token' and enter it in the instance settings."
+                : "No API key for Claude Code in the instance settings.");
+
+        var runtime = context.Agent.Runtime;
+        var allowed = (runtime.AllowedTools.Count > 0 ? runtime.AllowedTools : DefaultAllowedTools)
+            .Where(t => !AlwaysDenied.Contains(t, StringComparer.OrdinalIgnoreCase))
+            .Where(t => context.HasMcp || !t.StartsWith("mcp__", StringComparison.Ordinal))
+            .ToList();
+
+        PrepareHome(context.HomeDirectory, allowed);
+        File.WriteAllText(Path.Combine(context.PrivateDirectory, ForeignRunContext.BriefingFileName), Briefing(context));
+        File.WriteAllText(Path.Combine(context.PrivateDirectory, "mcp.json"), McpConfig(context));
+
+        var arguments = new List<string>
+        {
+            "-p",
+            "--output-format", "stream-json",
+            "--verbose",
+            "--max-turns", Math.Clamp(runtime.MaxTurns, 1, 500).ToString(System.Globalization.CultureInfo.InvariantCulture),
+            "--setting-sources", "user",
+            "--strict-mcp-config",
+            "--mcp-config", ForeignRunContext.Private + "/mcp.json",
+            "--append-system-prompt-file", ForeignRunContext.Private + "/" + ForeignRunContext.BriefingFileName,
+            "--allowedTools", string.Join(",", allowed),
+            "--disallowedTools", string.Join(",", AlwaysDenied)
+        };
+        if (ModelName(context.Agent.Model) is { } model)
+            arguments.AddRange(["--model", model]);
+
+        var environment = new Dictionary<string, string>(context.McpEnvironment(), StringComparer.Ordinal)
+        {
+            ["DISABLE_AUTOUPDATER"] = "1",
+            ["DISABLE_TELEMETRY"] = "1",
+            ["DISABLE_ERROR_REPORTING"] = "1",
+            ["CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC"] = "1"
+        };
+
+        var readOnly = new List<string>(config.ReadOnlyPaths);
+        var directory = Path.GetDirectoryName(executable)!;
+        if (!directory.StartsWith("/usr/", StringComparison.Ordinal))
+            readOnly.Add(directory);
+
+        return new SandboxRequest
+        {
+            Executable = executable,
+            Arguments = arguments,
+            WorkspacePath = context.WorkCopy,
+            ProtectedPaths = [],
+            ReadOnlyPaths = readOnly,
+            Mounts = context.Mounts(),
+            Environment = environment,
+            SecretEnvironment = new Dictionary<string, string>
+            {
+                [config.OnSubscription ? "CLAUDE_CODE_OAUTH_TOKEN" : "ANTHROPIC_API_KEY"] = secret.Trim()
+            },
+            Egress = [.. Egress, .. runtime.Egress],
+            StandardInput = context.Message,
+            Limits = ForeignRunner.Limits(runtime)
+        };
+    }
+
+    /// <summary>
+    /// The home as this run finds it: our settings, and nothing a previous run left to
+    /// instruct this one. Login state and history stay.
+    /// </summary>
+    internal static void PrepareHome(string home, IReadOnlyList<string> allowed)
+    {
+        // A previous run could have made .claude a link to anywhere on the host — writing
+        // through it would put our file there. Links go; only a real folder is used.
+        var claude = Path.Combine(home, ".claude");
+        if (new DirectoryInfo(claude).LinkTarget is not null || File.Exists(claude))
+            DeleteEntry(claude);
+        Directory.CreateDirectory(claude);
+        foreach (var name in new[] { "agents", "commands", "skills", "hooks", "output-styles", "plugins" })
+        {
+            var path = Path.Combine(claude, name);
+            if (Directory.Exists(path) || File.Exists(path))
+                DeleteEntry(path);
+        }
+        foreach (var name in new[] { "CLAUDE.md", "settings.local.json" })
+        {
+            var path = Path.Combine(claude, name);
+            if (File.Exists(path) || Directory.Exists(path))
+                DeleteEntry(path);
+        }
+
+        var settings = new JsonObject
+        {
+            ["permissions"] = new JsonObject
+            {
+                ["allow"] = new JsonArray(allowed.Select(a => (JsonNode)a).ToArray()),
+                ["deny"] = new JsonArray(AlwaysDenied.Select(a => (JsonNode)a).ToArray())
+            },
+            ["disableAllHooks"] = true
+        };
+        var file = Path.Combine(claude, "settings.json");
+        if (File.Exists(file) || new FileInfo(file).LinkTarget is not null)
+            DeleteEntry(file);
+        File.WriteAllText(file, settings.ToJsonString(new JsonSerializerOptions { WriteIndented = true }));
+    }
+
+    /// <summary>Removes a file, a folder or a link — never what a link points to.</summary>
+    private static void DeleteEntry(string path)
+    {
+        var info = new FileInfo(path);
+        if (info.LinkTarget is not null || !Directory.Exists(path))
+            info.Delete();
+        else
+            Directory.Delete(path, recursive: true);
+    }
+
+    private static string Briefing(ForeignRunContext context)
+        => context.Briefing + "\n\n## How this run works\n\n"
+           + "You work in /work, a copy of your workspace. Nothing you change there is used directly: "
+           + "the changed files become a proposal that is reviewed before anything is applied.\n"
+           + (context.HasMcp
+               ? "The taskboard, your colleagues and your other tools are reachable only through the MCP server 'clawd'.\n"
+               : "")
+           + "End with a short summary of what you did and what is left.";
+
+    private static string McpConfig(ForeignRunContext context)
+    {
+        var servers = new JsonObject();
+        if (context.HasMcp)
+        {
+            var env = new JsonObject
+            {
+                [Mcp.McpStdioBridge.TokenFileVariable] = ForeignRunContext.Private + "/" + ForeignRunContext.TokenFileName
+            };
+            // An MCP server does not inherit the runtime's environment, only a few variables.
+            foreach (var (key, value) in context.Helper!.Environment)
+                env[key] = value;
+            servers["clawd"] = new JsonObject
+            {
+                ["type"] = "stdio",
+                ["command"] = context.Helper.Executable,
+                ["args"] = new JsonArray("--mcp-bridge", Mcp.McpStdioBridge.SocketArgument, ForeignRunContext.McpSocketInSandbox),
+                ["env"] = env
+            };
+        }
+        return new JsonObject { ["mcpServers"] = servers }.ToJsonString();
+    }
+
+    /// <summary><c>anthropic/claude-sonnet-5</c> (OpenRouter's name) → <c>claude-sonnet-5</c>; empty stays the runtime's default.</summary>
+    public static string? ModelName(string? model)
+    {
+        if (string.IsNullOrWhiteSpace(model))
+            return null;
+        var slash = model.IndexOf('/');
+        if (slash >= 0 && !model.StartsWith("anthropic/", StringComparison.OrdinalIgnoreCase))
+            return null;
+        return slash >= 0 ? model[(slash + 1)..] : model;
+    }
+
+    public ForeignRunOutcome Interpret(SandboxResult result, ForeignRunContext context, Action<string> note)
+    {
+        var onSubscription = settings().OnSubscription;
+        JsonObject? final = null;
+        string? model = null;
+        var turns = 0;
+
+        foreach (var line in result.StandardOutput.Split('\n'))
+        {
+            if (!line.StartsWith('{'))
+                continue;
+            JsonObject? message;
+            try
+            {
+                message = JsonNode.Parse(line) as JsonObject;
+            }
+            catch (JsonException)
+            {
+                continue;
+            }
+            switch (Text(message?["type"]))
+            {
+                case "system" when Text(message!["subtype"]) == "init":
+                    model = Text(message["model"]);
+                    break;
+                case "assistant":
+                    turns++;
+                    foreach (var part in message!["message"]?["content"] as JsonArray ?? [])
+                    {
+                        if (Text(part?["type"]) == "tool_use")
+                            note($"Tool: {Text(part!["name"])}");
+                        else if (Text(part?["type"]) == "text" && Text(part!["text"]) is { Length: > 0 } text)
+                            note(text.Length > 500 ? text[..500] + " …" : text);
+                    }
+                    break;
+                case "result":
+                    final = message;
+                    break;
+            }
+        }
+
+        if (final is null)
+        {
+            var reason = result.TimedOut ? "timed out"
+                : result.OutputTruncated ? "produced more output than allowed"
+                : $"ended with exit code {result.ExitCode} and no result";
+            return new ForeignRunOutcome
+            {
+                Status = result.TimedOut ? AgentRunStatus.Cancelled : AgentRunStatus.Failed,
+                Text = $"[Claude Code {reason}]" + Tail(result.StandardError),
+                Turns = turns,
+                Model = model,
+                OnSubscription = onSubscription
+            };
+        }
+
+        var usage = final["usage"] as JsonObject;
+        var input = Number(usage?["input_tokens"]);
+        var cacheWrite = Number(usage?["cache_creation_input_tokens"]);
+        var cacheRead = Number(usage?["cache_read_input_tokens"]);
+        var subtype = Text(final["subtype"]) ?? "";
+        var isError = final["is_error"]?.GetValueKind() == JsonValueKind.True;
+        var status = subtype == "error_max_turns" ? AgentRunStatus.LoopLimitExceeded
+            : isError || subtype != "success" ? AgentRunStatus.Failed
+            : AgentRunStatus.Completed;
+
+        decimal? cost = onSubscription ? 0m : null;
+        if (!onSubscription && final["total_cost_usd"] is JsonValue value && value.TryGetValue<decimal>(out var usd))
+            cost = usd;
+
+        return new ForeignRunOutcome
+        {
+            Status = status,
+            Text = Text(final["result"]) ?? (status == AgentRunStatus.Completed ? "" : $"[Claude Code: {subtype}]"),
+            Turns = (int)Math.Max(turns, Number(final["num_turns"])),
+            PromptTokens = (int)(input + cacheWrite + cacheRead),
+            CompletionTokens = (int)Number(usage?["output_tokens"]),
+            CachedTokens = (int)cacheRead,
+            CostUsd = cost,
+            OnSubscription = onSubscription,
+            Model = model
+        };
+    }
+
+    private static string? Text(JsonNode? node)
+        => node is JsonValue value && value.TryGetValue<string>(out var text) ? text : null;
+
+    private static long Number(JsonNode? node)
+        => node is JsonValue value && value.TryGetValue<long>(out var number) ? number : 0;
+
+    internal static string Tail(string stderr)
+    {
+        var text = stderr.Trim();
+        if (text.Length == 0)
+            return "";
+        return "\n" + (text.Length > 1000 ? "…" + text[^1000..] : text);
+    }
+}

src/ClawdDotNet.Core/Runtimes/CommandRuntime.cs

@@ -0,0 +1,70 @@
+using ClawdDotNet.Core.Engine;
+using ClawdDotNet.Core.Sandbox;
+
+namespace ClawdDotNet.Core.Runtimes;
+
+/// <summary>
+/// #712: A program as the runtime — for special cases, and the way to try the whole path
+/// without a model. The message comes on stdin, the briefing in the file named by
+/// <c>CLAWD_BRIEFING_FILE</c>; what the program prints is the result. A non-zero exit code
+/// is a failure, with the end of stderr as its reason.
+///
+/// <para>The program can reach the MCP server itself: <c>$CLAWD_HELPER --mcp-bridge --socket
+/// $CLAWD_MCP_SOCKET</c> with the token file in <c>CLAWD_MCP_TOKEN_FILE</c>.</para>
+/// </summary>
+public sealed class CommandRuntime : IForeignRuntime
+{
+    public string Kind => RuntimeKinds.Command;
+
+    public SandboxRequest Prepare(ForeignRunContext context)
+    {
+        var runtime = context.Agent.Runtime;
+        if (string.IsNullOrWhiteSpace(runtime.Command))
+            throw new ForeignRunException("No command configured for this agent ('runtime.command').");
+
+        File.WriteAllText(Path.Combine(context.PrivateDirectory, ForeignRunContext.BriefingFileName), context.Briefing);
+
+        var command = runtime.Command.Trim();
+        var readOnly = new List<string>();
+        if (Path.IsPathRooted(command))
+        {
+            var directory = Path.GetDirectoryName(command)!;
+            if (!directory.StartsWith("/usr/", StringComparison.Ordinal) && directory != "/bin")
+                readOnly.Add(directory);
+        }
+        else if (command.Contains('/'))
+        {
+            // Relative to the workspace — the run's copy of it.
+            command = SandboxPaths.Work + "/" + command.TrimStart('.', '/');
+        }
+
+        return new SandboxRequest
+        {
+            Executable = command,
+            Arguments = runtime.Arguments,
+            WorkspacePath = context.WorkCopy,
+            ProtectedPaths = [],
+            ReadOnlyPaths = readOnly,
+            Mounts = context.Mounts(),
+            Environment = context.McpEnvironment(),
+            Egress = runtime.Egress,
+            StandardInput = context.Message,
+            Limits = ForeignRunner.Limits(runtime)
+        };
+    }
+
+    public ForeignRunOutcome Interpret(SandboxResult result, ForeignRunContext context, Action<string> note)
+    {
+        if (result.TimedOut)
+            return new ForeignRunOutcome { Status = AgentRunStatus.Cancelled, Text = "[The command timed out]" + ClaudeCodeRuntime.Tail(result.StandardError) };
+        if (result.OutputTruncated)
+            return new ForeignRunOutcome { Status = AgentRunStatus.Failed, Text = "[The command produced more output than allowed]" };
+        if (result.ExitCode != 0)
+            return new ForeignRunOutcome
+            {
+                Status = AgentRunStatus.Failed,
+                Text = $"[The command ended with exit code {result.ExitCode}]" + ClaudeCodeRuntime.Tail(result.StandardError)
+            };
+        return new ForeignRunOutcome { Status = AgentRunStatus.Completed, Text = result.StandardOutput.Trim(), Turns = 1 };
+    }
+}

src/ClawdDotNet.Core/Runtimes/ForeignRunner.cs

@@ -0,0 +1,202 @@
+using ClawdDotNet.Core.Config;
+using ClawdDotNet.Core.Engine;
+using ClawdDotNet.Core.Sandbox;
+using Microsoft.Extensions.Logging;
+
+namespace ClawdDotNet.Core.Runtimes;
+
+/// <summary>#712: One foreign run as the engine asks for it.</summary>
+public sealed record ForeignRunRequest(
+    AgentConfig Agent, string RunId, string? TaskId, string Briefing, string Message);
+
+/// <summary>
+/// #712: Runs an agent in a foreign runtime — the part that is the same for all of them.
+///
+/// <para>A foreign runtime counts as less trustworthy: nothing of what happens inside it
+/// passes our checks. So it gets <b>its own place</b> (a copy of the workspace, in the
+/// sandbox; without a sandbox it does not run at all), <b>the way out only through us</b>
+/// (the MCP server, with a token for this run that dies with it), and <b>its result is a
+/// proposal</b> — changed files kept next to the agent, never applied.</para>
+///
+/// <para>Where things live, per agent: <c>runtime/home</c> (the runtime's home, kept),
+/// <c>runtime/runs/&lt;run&gt;</c> (this run only, removed afterwards),
+/// <c>proposals/&lt;run&gt;</c> (what the run proposes).</para>
+/// </summary>
+public sealed class ForeignRunner
+{
+    private readonly ISandboxRunner _sandbox;
+    private readonly IReadOnlyDictionary<string, IForeignRuntime> _runtimes;
+    private readonly Mcp.McpGrants? _grants;
+    private readonly string? _mcpSocket;
+    private readonly SandboxHelper? _helper;
+    private readonly ILogger _logger;
+    private readonly TimeProvider _clock;
+
+    public ForeignRunner(
+        ISandboxRunner sandbox,
+        IEnumerable<IForeignRuntime> runtimes,
+        Mcp.McpGrants? grants,
+        string? mcpSocket,
+        SandboxHelper? helper,
+        ILogger logger,
+        TimeProvider? clock = null)
+    {
+        _sandbox = sandbox;
+        _runtimes = runtimes.ToDictionary(r => r.Kind, StringComparer.OrdinalIgnoreCase);
+        _grants = grants;
+        _mcpSocket = mcpSocket;
+        _helper = helper;
+        _logger = logger;
+        _clock = clock ?? TimeProvider.System;
+    }
+
+    /// <summary>The limits of a foreign run: long, many processes, no address-space limit (see <see cref="SandboxLimits.MaxMemoryBytes"/>).</summary>
+    public static SandboxLimits Limits(AgentRuntimeConfig runtime) => new()
+    {
+        Timeout = runtime.Timeout,
+        MaxMemoryBytes = 0,
+        MaxProcesses = 512,
+        MaxOpenFiles = 4096,
+        MaxOutputBytes = 64 * 1024 * 1024,
+        MaxFileBytes = 1024L * 1024 * 1024
+    };
+
+    /// <summary>Why this agent cannot run in its runtime here, or <c>null</c>.</summary>
+    public string? Refusal(AgentConfig agent)
+    {
+        var kind = RuntimeKinds.Normalize(agent.Runtime.Kind);
+        if (!_runtimes.ContainsKey(kind))
+            return $"the runtime '{kind}' is not available";
+        if (!_sandbox.IsAvailable)
+            return $"a foreign runtime runs only in the sandbox, and there is none: {_sandbox.UnavailableReason}";
+        if (string.IsNullOrWhiteSpace(agent.AgentDir))
+            return "the agent has no directory";
+        // The run's directories must not lie in what is copied — or the copy would copy itself.
+        var runtimeRoot = Path.GetFullPath(Path.Combine(agent.AgentDir, "runtime")) + Path.DirectorySeparatorChar;
+        var workspace = string.IsNullOrWhiteSpace(agent.WorkspacePath) ? null : Path.GetFullPath(agent.WorkspacePath).TrimEnd(Path.DirectorySeparatorChar) + Path.DirectorySeparatorChar;
+        if (workspace is null)
+            return "the agent has no workspace";
+        if (runtimeRoot.StartsWith(workspace, StringComparison.Ordinal))
+            return "the agent's workspace contains its runtime directory";
+        return null;
+    }
+
+    public async Task<ForeignRunOutcome> RunAsync(ForeignRunRequest request, Action<string> note, CancellationToken ct)
+    {
+        var agent = request.Agent;
+        if (Refusal(agent) is { } refusal)
+            return new ForeignRunOutcome { Status = AgentRunStatus.Failed, Text = $"[Not run: {refusal}]" };
+
+        var runtime = _runtimes[RuntimeKinds.Normalize(agent.Runtime.Kind)];
+        var root = Path.Combine(agent.AgentDir, "runtime");
+        var runDir = Path.Combine(root, "runs", request.RunId);
+        var privateDir = Path.Combine(runDir, "private");
+        var work = Path.Combine(runDir, "work");
+        var home = Path.Combine(root, "home");
+
+        Mcp.McpRunToken? token = null;
+        try
+        {
+            Directory.CreateDirectory(home);
+            CreatePrivate(privateDir);
+            ForeignWorkspace.Copy(agent.WorkspacePath, work);
+
+            var hasMcp = _grants is not null && _helper is not null && _mcpSocket is not null && File.Exists(_mcpSocket);
+            if (hasMcp)
+            {
+                token = _grants!.OpenRun(agent.AgentId, request.RunId, request.TaskId, agent.Runtime.Timeout + TimeSpan.FromMinutes(5));
+                WritePrivate(Path.Combine(privateDir, ForeignRunContext.TokenFileName), token.Token);
+            }
+
+            var context = new ForeignRunContext
+            {
+                Agent = agent,
+                RunId = request.RunId,
+                TaskId = request.TaskId,
+                Briefing = request.Briefing,
+                Message = request.Message,
+                WorkCopy = work,
+                HomeDirectory = home,
+                PrivateDirectory = privateDir,
+                McpSocket = hasMcp ? _mcpSocket : null,
+                Helper = _helper
+            };
+
+            var sandboxRequest = runtime.Prepare(context);
+            note($"Runtime {runtime.Kind} started in the sandbox");
+            _logger.LogInformation("Foreign run {RunId} of {AgentId} in {Runtime}", request.RunId, agent.AgentId, runtime.Kind);
+            var result = await _sandbox.RunAsync(sandboxRequest, ct);
+            var outcome = runtime.Interpret(result, context, note);
+
+            return outcome with { Text = WithProposal(outcome.Text, agent, request, runtime.Kind, work) };
+        }
+        catch (ForeignRunException ex)
+        {
+            return new ForeignRunOutcome { Status = AgentRunStatus.Failed, Text = $"[Not run: {ex.Message}]" };
+        }
+        catch (SandboxUnavailableException ex)
+        {
+            return new ForeignRunOutcome { Status = AgentRunStatus.Failed, Text = $"[Not run: {ex.Message}]" };
+        }
+        finally
+        {
+            token?.Dispose();
+            try
+            {
+                if (Directory.Exists(runDir))
+                    Directory.Delete(runDir, recursive: true);
+            }
+            catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
+            {
+                _logger.LogWarning(ex, "The run directory {RunDir} could not be removed", runDir);
+            }
+        }
+    }
+
+    /// <summary>The run's text, and what it proposes — kept, not applied.</summary>
+    private string? WithProposal(string? text, AgentConfig agent, ForeignRunRequest request, string kind, string work)
+    {
+        var (changes, ignored) = ForeignWorkspace.Compare(agent.WorkspacePath, work);
+        if (changes.Count == 0 && ignored.Count == 0)
+            return text;
+
+        var proposal = new Proposal
+        {
+            RunId = request.RunId,
+            AgentId = agent.AgentId,
+            TaskId = request.TaskId,
+            Runtime = kind,
+            CreatedAtUtc = _clock.GetUtcNow().UtcDateTime,
+            Changes = changes,
+            Ignored = ignored
+        };
+        var directory = Path.Combine(agent.AgentDir, "proposals", request.RunId);
+        ForeignWorkspace.Keep(proposal, work, directory);
+
+        var lines = changes.Take(20).Select(c => $"- {c.Change}: {c.Path}").ToList();
+        if (changes.Count > 20)
+            lines.Add($"- … and {changes.Count - 20} more");
+        if (ignored.Count > 0)
+            lines.Add($"- ignored (links or special files, not read): {ignored.Count}");
+        return (text ?? "").TrimEnd()
+               + $"\n\n[Proposal {request.RunId}: {changes.Count} change(s), nothing applied — kept in proposals/{request.RunId}]\n"
+               + string.Join("\n", lines);
+    }
+
+    private static void CreatePrivate(string path)
+    {
+        Directory.CreateDirectory(path);
+        if (!OperatingSystem.IsWindows())
+            File.SetUnixFileMode(path, UnixFileMode.UserRead | UnixFileMode.UserWrite | UnixFileMode.UserExecute);
+    }
+
+    private static void WritePrivate(string path, string content)
+    {
+        var options = new FileStreamOptions { Mode = FileMode.CreateNew, Access = FileAccess.Write };
+        if (!OperatingSystem.IsWindows())
+            options.UnixCreateMode = UnixFileMode.UserRead | UnixFileMode.UserWrite;
+        using var stream = new FileStream(path, options);
+        using var writer = new StreamWriter(stream);
+        writer.Write(content);
+    }
+}

src/ClawdDotNet.Core/Runtimes/ForeignRuntime.cs

@@ -0,0 +1,114 @@
+using ClawdDotNet.Core.Config;
+using ClawdDotNet.Core.Sandbox;
+
+namespace ClawdDotNet.Core.Runtimes;
+
+/// <summary>#712: Everything a runtime needs to lay out one run.</summary>
+public sealed record ForeignRunContext
+{
+    public required AgentConfig Agent { get; init; }
+    public required string RunId { get; init; }
+    public string? TaskId { get; init; }
+
+    /// <summary>The system prompt as the native engine would send it — rules, organisation.</summary>
+    public required string Briefing { get; init; }
+
+    /// <summary>The message of this run.</summary>
+    public required string Message { get; init; }
+
+    /// <summary>The run's copy of the workspace, on the host; <c>/work</c> in the sandbox.</summary>
+    public required string WorkCopy { get; init; }
+
+    /// <summary>The runtime's home, kept between runs — on the host; <see cref="Home"/> in the sandbox.</summary>
+    public required string HomeDirectory { get; init; }
+
+    /// <summary>Files of this run only (token, briefing, configuration) — on the host; <see cref="Private"/> in the sandbox.</summary>
+    public required string PrivateDirectory { get; init; }
+
+    /// <summary>The instance's MCP socket on the host, when it has one.</summary>
+    public string? McpSocket { get; init; }
+
+    /// <summary>The application, for the MCP bridge inside the sandbox.</summary>
+    public SandboxHelper? Helper { get; init; }
+
+    public const string Home = "/home/agent";
+    public const string Private = "/run/agent";
+    public const string McpSocketInSandbox = "/run/mcp.sock";
+    public const string TokenFileName = "mcp-token";
+    public const string BriefingFileName = "briefing.md";
+
+    /// <summary>
+    /// The sandbox's side of the MCP server: the socket, the token file, the bridge. Without
+    /// a socket or a helper there is none — the run works without taskboard access.
+    /// </summary>
+    public bool HasMcp => McpSocket is not null && Helper is not null;
+
+    /// <summary>The mounts every foreign run gets: home (writable), the run's own files, the MCP socket.</summary>
+    public IReadOnlyList<SandboxMount> Mounts()
+    {
+        var mounts = new List<SandboxMount>
+        {
+            new(HomeDirectory, Home, Writable: true),
+            new(PrivateDirectory, Private)
+        };
+        if (HasMcp)
+            mounts.Add(new SandboxMount(McpSocket!, McpSocketInSandbox, Writable: true));
+        return mounts;
+    }
+
+    /// <summary>What a program in the sandbox needs to reach the MCP server itself.</summary>
+    public IReadOnlyDictionary<string, string> McpEnvironment()
+    {
+        var environment = new Dictionary<string, string>(StringComparer.Ordinal)
+        {
+            ["HOME"] = Home,
+            ["CLAWD_RUN_ID"] = RunId,
+            ["CLAWD_BRIEFING_FILE"] = Private + "/" + BriefingFileName
+        };
+        if (TaskId is not null)
+            environment["CLAWD_TASK_ID"] = TaskId;
+        if (HasMcp)
+        {
+            environment["CLAWD_MCP_SOCKET"] = McpSocketInSandbox;
+            environment[Mcp.McpStdioBridge.TokenFileVariable] = Private + "/" + TokenFileName;
+            environment["CLAWD_HELPER"] = Helper!.Executable;
+        }
+        return environment;
+    }
+}
+
+/// <summary>#712: What came out of a run, in the engine's terms.</summary>
+public sealed record ForeignRunOutcome
+{
+    public Engine.AgentRunStatus Status { get; init; } = Engine.AgentRunStatus.Completed;
+    public string? Text { get; init; }
+    public int Turns { get; init; }
+    public int PromptTokens { get; init; }
+    public int CompletionTokens { get; init; }
+    public int CachedTokens { get; init; }
+
+    /// <summary>What the provider billed, if it said so; on a subscription 0.</summary>
+    public decimal? CostUsd { get; init; }
+
+    /// <summary>Paid by a subscription's quota — costs nothing, uses something (#699).</summary>
+    public bool OnSubscription { get; init; }
+
+    /// <summary>The model the runtime reported, if any.</summary>
+    public string? Model { get; init; }
+}
+
+/// <summary>
+/// #712: One runtime — how a run is laid out for the sandbox, and how its output is read.
+/// The runner around it does everything that is the same for all: the copy, the token,
+/// the proposal, the clean-up.
+/// </summary>
+public interface IForeignRuntime
+{
+    string Kind { get; }
+
+    /// <summary>Writes what the run needs into the private directory and returns the sandbox request.</summary>
+    SandboxRequest Prepare(ForeignRunContext context);
+
+    /// <summary>Reads the result. <paramref name="note"/> takes lines for the run's transcript.</summary>
+    ForeignRunOutcome Interpret(SandboxResult result, ForeignRunContext context, Action<string> note);
+}

src/ClawdDotNet.Core/Runtimes/ForeignWorkspace.cs

@@ -0,0 +1,183 @@
+using System.Runtime.InteropServices;
+using System.Security.Cryptography;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace ClawdDotNet.Core.Runtimes;
+
+/// <summary>#712: One change a foreign run proposes.</summary>
+public sealed record ProposedChange(
+    [property: JsonPropertyName("path")] string Path,
+    [property: JsonPropertyName("change")] string Change,
+    [property: JsonPropertyName("bytes")] long Bytes,
+    [property: JsonPropertyName("sha256")] string? Sha256)
+{
+    public const string Added = "added";
+    public const string Modified = "modified";
+    public const string Deleted = "deleted";
+}
+
+/// <summary>#712: What a foreign run left behind — never applied, kept for review.</summary>
+public sealed record Proposal
+{
+    [JsonPropertyName("runId")] public string RunId { get; init; } = "";
+    [JsonPropertyName("agentId")] public string AgentId { get; init; } = "";
+    [JsonPropertyName("taskId")] public string? TaskId { get; init; }
+    [JsonPropertyName("runtime")] public string Runtime { get; init; } = "";
+    [JsonPropertyName("createdAtUtc")] public DateTime CreatedAtUtc { get; init; }
+    [JsonPropertyName("changes")] public IReadOnlyList<ProposedChange> Changes { get; init; } = [];
+
+    /// <summary>What the run left out: links, special files — named, never read.</summary>
+    [JsonPropertyName("ignored")] public IReadOnlyList<string> Ignored { get; init; } = [];
+}
+
+/// <summary>
+/// #712: The foreign run's place to work — a copy of the agent's workspace, never the
+/// workspace itself (rule 1 of the concept). What changed there becomes a proposal
+/// (rule 3): the changed files and a list, next to the agent, for review. Whether any of it
+/// is used is decided by the delivery chain (#695), not by the run.
+///
+/// <para><b>Reading what a sandbox left is reading hostile ground.</b> Only regular files
+/// are read. A symbolic link could point to a key outside the sandbox — inside it the
+/// target did not exist, outside it does; a named pipe would block the reader for good.
+/// Both are listed as ignored and never opened. After the run every process of the sandbox
+/// is gone, so nothing changes while it is read.</para>
+/// </summary>
+public static class ForeignWorkspace
+{
+    public const long MaxBytes = 512L * 1024 * 1024;
+    public const int MaxFiles = 20_000;
+
+    private static readonly JsonSerializerOptions Json = new() { WriteIndented = true };
+
+    /// <summary>Copies the workspace to <paramref name="target"/> — regular files and folders only.</summary>
+    public static void Copy(string workspace, string target)
+    {
+        Directory.CreateDirectory(target);
+        if (!Directory.Exists(workspace))
+            return;
+
+        long bytes = 0;
+        var files = 0;
+        foreach (var (relative, full) in Walk(workspace, _ => { }))
+        {
+            var info = new FileInfo(full);
+            bytes += info.Length;
+            if (++files > MaxFiles || bytes > MaxBytes)
+                throw new ForeignRunException(
+                    $"The workspace is too large for a foreign run (more than {MaxFiles} files or {MaxBytes / (1024 * 1024)} MB).");
+            var destination = Path.Combine(target, relative);
+            Directory.CreateDirectory(Path.GetDirectoryName(destination)!);
+            File.Copy(full, destination);
+        }
+    }
+
+    /// <summary>What differs between the workspace and the run's copy.</summary>
+    public static (IReadOnlyList<ProposedChange> Changes, IReadOnlyList<string> Ignored) Compare(string workspace, string copy)
+    {
+        var before = Directory.Exists(workspace)
+            ? Walk(workspace, _ => { }).ToDictionary(e => e.Relative, e => e.Full, StringComparer.Ordinal)
+            : new Dictionary<string, string>(StringComparer.Ordinal);
+
+        var ignored = new List<string>();
+        var changes = new List<ProposedChange>();
+        long bytes = 0;
+        foreach (var (relative, full) in Walk(copy, ignored.Add))
+        {
+            var length = new FileInfo(full).Length;
+            if ((bytes += length) > MaxBytes || changes.Count >= MaxFiles)
+                throw new ForeignRunException("The run left more than a proposal can hold.");
+
+            var hash = Hash(full);
+            if (!before.Remove(relative, out var original))
+                changes.Add(new ProposedChange(relative, ProposedChange.Added, length, hash));
+            else if (new FileInfo(original).Length != length || Hash(original) != hash)
+                changes.Add(new ProposedChange(relative, ProposedChange.Modified, length, hash));
+        }
+        foreach (var relative in before.Keys)
+            changes.Add(new ProposedChange(relative, ProposedChange.Deleted, 0, null));
+
+        changes.Sort((a, b) => string.CompareOrdinal(a.Path, b.Path));
+        return (changes, ignored);
+    }
+
+    /// <summary>Writes the proposal to <paramref name="directory"/>: <c>proposal.json</c> and the files under <c>files/</c>.</summary>
+    public static void Keep(Proposal proposal, string copy, string directory)
+    {
+        var files = Path.Combine(directory, "files");
+        Directory.CreateDirectory(files);
+        foreach (var change in proposal.Changes.Where(c => c.Change != ProposedChange.Deleted))
+        {
+            var destination = Path.Combine(files, change.Path);
+            Directory.CreateDirectory(Path.GetDirectoryName(destination)!);
+            File.Copy(Path.Combine(copy, change.Path), destination, overwrite: true);
+        }
+        File.WriteAllText(Path.Combine(directory, "proposal.json"), JsonSerializer.Serialize(proposal, Json));
+    }
+
+    /// <summary>Regular files below <paramref name="root"/>, relative with '/'; everything else goes to <paramref name="skipped"/>.</summary>
+    private static IEnumerable<(string Relative, string Full)> Walk(string root, Action<string> skipped)
+    {
+        var pending = new Stack<string>([Path.GetFullPath(root)]);
+        var rootLength = Path.GetFullPath(root).TrimEnd(Path.DirectorySeparatorChar).Length + 1;
+        while (pending.Count > 0)
+        {
+            var dir = pending.Pop();
+            foreach (var entry in new DirectoryInfo(dir).EnumerateFileSystemInfos())
+            {
+                var relative = entry.FullName[rootLength..].Replace('\\', '/');
+                switch (FileKind.Of(entry))
+                {
+                    case FileKind.Kind.Directory: pending.Push(entry.FullName); break;
+                    case FileKind.Kind.Regular: yield return (relative, entry.FullName); break;
+                    default: skipped(relative); break;
+                }
+            }
+        }
+    }
+
+    private static string Hash(string path)
+    {
+        using var stream = File.OpenRead(path);
+        return Convert.ToHexStringLower(SHA256.HashData(stream));
+    }
+}
+
+/// <summary>
+/// #712: What an entry really is, without following it. .NET tells links apart but not a
+/// named pipe or a device from a file — under Linux that takes <c>statx</c>, whose layout,
+/// unlike <c>stat</c>'s, is the same on every architecture.
+/// </summary>
+internal static class FileKind
+{
+    public enum Kind { Regular, Directory, Other }
+
+    public static Kind Of(FileSystemInfo entry)
+    {
+        if (entry.LinkTarget is not null || entry.Attributes.HasFlag(FileAttributes.ReparsePoint))
+            return Kind.Other;
+        if (!OperatingSystem.IsLinux())
+            return entry is DirectoryInfo ? Kind.Directory : Kind.Regular;
+
+        var buffer = new byte[256];
+        if (Statx(AtFdCwd, entry.FullName, AtSymlinkNoFollow, StatxType, buffer) != 0)
+            return Kind.Other;
+        var mode = BitConverter.ToUInt16(buffer, 0x1C) & 0xF000;
+        return mode switch
+        {
+            0x8000 => Kind.Regular,
+            0x4000 => Kind.Directory,
+            _ => Kind.Other
+        };
+    }
+
+    private const int AtFdCwd = -100;
+    private const int AtSymlinkNoFollow = 0x100;
+    private const uint StatxType = 0x1;
+
+    [DllImport("libc", EntryPoint = "statx", SetLastError = true)]
+    private static extern int Statx(int dirfd, [MarshalAs(UnmanagedType.LPUTF8Str)] string path, int flags, uint mask, byte[] buffer);
+}
+
+/// <summary>#712: A foreign run that could not take place or not be read.</summary>
+public sealed class ForeignRunException(string message) : Exception(message);

src/ClawdDotNet.Core/Runtimes/RuntimeConfig.cs

@@ -0,0 +1,100 @@
+using System.Text.Json.Serialization;
+
+namespace ClawdDotNet.Core.Runtimes;
+
+/// <summary>#712: The runtimes an agent can work in.</summary>
+public static class RuntimeKinds
+{
+    /// <summary>Our engine with OpenRouter — the default, everything but programming.</summary>
+    public const string Native = "native";
+
+    /// <summary>Claude Code in headless mode, in the sandbox.</summary>
+    public const string ClaudeCode = "claude-code";
+
+    /// <summary>A program whose output is the result, in the sandbox.</summary>
+    public const string Command = "command";
+
+    public static readonly IReadOnlyList<string> All = [Native, ClaudeCode, Command];
+
+    public static bool IsKnown(string? kind) => All.Contains(Normalize(kind));
+
+    public static string Normalize(string? kind)
+        => string.IsNullOrWhiteSpace(kind) ? Native : kind.Trim().ToLowerInvariant();
+}
+
+/// <summary>
+/// #712: In which runtime an agent works (<c>runtime</c> in its configuration). Without it,
+/// the agent is native, as before.
+/// </summary>
+public sealed class AgentRuntimeConfig
+{
+    [JsonPropertyName("kind")]
+    public string Kind { get; set; } = RuntimeKinds.Native;
+
+    /// <summary>
+    /// Claude Code: the tools it may use without asking. Empty: <see cref="ClaudeCodeRuntime.DefaultAllowedTools"/>.
+    /// Anything not listed is denied — there is no one to ask.
+    /// </summary>
+    [JsonPropertyName("allowedTools")]
+    public List<string> AllowedTools { get; set; } = [];
+
+    /// <summary>Claude Code: the most turns of one run.</summary>
+    [JsonPropertyName("maxTurns")]
+    public int MaxTurns { get; set; } = 30;
+
+    [JsonPropertyName("timeoutMinutes")]
+    public int TimeoutMinutes { get; set; } = 30;
+
+    /// <summary>Command: the program — absolute, on the sandbox's PATH, or relative to the workspace.</summary>
+    [JsonPropertyName("command")]
+    public string Command { get; set; } = "";
+
+    [JsonPropertyName("arguments")]
+    public List<string> Arguments { get; set; } = [];
+
+    /// <summary>Hosts the run may reach beyond what the runtime itself needs.</summary>
+    [JsonPropertyName("egress")]
+    public List<string> Egress { get; set; } = [];
+
+    [JsonIgnore]
+    public bool IsForeign => RuntimeKinds.Normalize(Kind) != RuntimeKinds.Native;
+
+    [JsonIgnore]
+    public TimeSpan Timeout => TimeSpan.FromMinutes(Math.Clamp(TimeoutMinutes, 1, 240));
+}
+
+/// <summary>
+/// #712: The Claude Code account of the instance (<c>claudeCode</c> in <c>instance.json</c>).
+///
+/// <para><b>Two ways to sign in, deliberately.</b> Whether an automated agent system may run
+/// on a consumer subscription is not settled, and a subscription shares its quota with the
+/// human who owns it. The API key is the default; the subscription (a token from
+/// <c>claude setup-token</c>) is a matter of configuration, not of rebuilding.</para>
+/// </summary>
+public sealed class ClaudeCodeSettings
+{
+    public const string ApiKeyAuth = "api-key";
+    public const string SubscriptionAuth = "subscription";
+
+    /// <summary>The <c>claude</c> program; empty: looked for in the usual places.</summary>
+    [JsonPropertyName("executable")]
+    public string Executable { get; set; } = "";
+
+    [JsonPropertyName("auth")]
+    public string Auth { get; set; } = ApiKeyAuth;
+
+    /// <summary>An Anthropic API key — best one of its own, with a spending limit.</summary>
+    [JsonPropertyName("apiKey")]
+    public string ApiKey { get; set; } = "";
+
+    /// <summary>A subscription's token from <c>claude setup-token</c>.</summary>
+    [JsonPropertyName("oauthToken")]
+    public string OAuthToken { get; set; } = "";
+
+    /// <summary>Further read-only host paths the program needs — Node and a package directory for an npm install.</summary>
+    [JsonPropertyName("readOnlyPaths")]
+    public List<string> ReadOnlyPaths { get; set; } = [];
+
+    [JsonIgnore]
+    public bool OnSubscription => string.Equals(Auth, SubscriptionAuth, StringComparison.OrdinalIgnoreCase);
+}

src/ClawdDotNet.Core/Sandbox/BwrapSandbox.cs

@@ -45,6 +45,15 @@ public sealed class BwrapSandbox : ISandboxRunner
     public bool IsAvailable => true;
     public string? UnavailableReason => null;
 
+    /// <summary>
+    /// #712: The launcher for runs that need network or secrets (<see cref="SandboxRequest.NeedsLauncher"/>).
+    /// Without it such a run is refused, not run without them.
+    /// </summary>
+    public SandboxHelper? Helper { get; set; }
+
+    /// <summary>#712: The logger the egress proxy reports to.</summary>
+    public ILoggerFactory? LoggerFactory { get; set; }
+
     /// <summary>
     /// The runner of this machine: bwrap under Linux if it can actually build a sandbox here
     /// (tried once — a kernel or AppArmor policy that forbids user namespaces shows only when
@@ -83,11 +92,36 @@ public sealed class BwrapSandbox : ISandboxRunner
     public async Task<SandboxResult> RunAsync(SandboxRequest request, CancellationToken ct)
     {
         Validate(request);
+        if (request.NeedsLauncher && Helper is null)
+            throw new SandboxUnavailableException("this run needs network or secrets, and the sandbox launcher is not available");
 
-        var filterFile = Path.Combine(Path.GetTempPath(), $"clawddotnet_seccomp_{Guid.NewGuid():N}.bpf");
-        await File.WriteAllBytesAsync(filterFile, SeccompFilter.Build(RuntimeInformation.ProcessArchitecture), ct);
+        // A directory only this user can enter: the filter, the proxy's socket, the secrets.
+        var privateDir = Path.Combine(Path.GetTempPath(), $"clawddotnet_sbx_{Guid.NewGuid():N}");
+        Directory.CreateDirectory(privateDir);
+        if (!OperatingSystem.IsWindows())
+            File.SetUnixFileMode(privateDir, UnixFileMode.UserRead | UnixFileMode.UserWrite | UnixFileMode.UserExecute);
+
+        EgressProxy? proxy = null;
         try
         {
+            var filterFile = Path.Combine(privateDir, "seccomp.bpf");
+            await File.WriteAllBytesAsync(filterFile, SeccompFilter.Build(RuntimeInformation.ProcessArchitecture), ct);
+
+            var launch = LaunchFiles.None;
+            if (request.Egress.Count > 0)
+            {
+                var socket = Path.Combine(privateDir, "egress.sock");
+                proxy = EgressProxy.Start(socket, request.Egress,
+                    LoggerFactory?.CreateLogger<EgressProxy>() ?? (ILogger)Microsoft.Extensions.Logging.Abstractions.NullLogger.Instance);
+                launch = launch with { EgressSocket = socket };
+            }
+            if (request.SecretEnvironment.Count > 0)
+            {
+                var secrets = Path.Combine(privateDir, "env.json");
+                await SandboxLauncher.WriteSecretFileAsync(secrets, request.SecretEnvironment, ct);
+                launch = launch with { SecretFile = secrets };
+            }
+
             var start = new ProcessStartInfo(Shell)
             {
                 UseShellExecute = false,
@@ -99,14 +133,15 @@ public sealed class BwrapSandbox : ISandboxRunner
             };
             // Nothing of the main process's environment — not even to bwrap.
             start.Environment.Clear();
-            foreach (var argument in CommandLine(_bwrap, filterFile, request, HostLayout.Read(), _features))
+            foreach (var argument in CommandLine(_bwrap, filterFile, request, HostLayout.Read(), _features, Helper, launch))
                 start.ArgumentList.Add(argument);
 
             return await RunProcessAsync(start, request, ct);
         }
         finally
         {
-            try { File.Delete(filterFile); }
+            proxy?.Dispose();
+            try { Directory.Delete(privateDir, recursive: true); }
             catch (IOException) { /* in /tmp, harmless */ }
         }
     }
@@ -116,8 +151,12 @@ public sealed class BwrapSandbox : ISandboxRunner
     /// Pure — the tests read it on any platform.
     /// </summary>
     public static IReadOnlyList<string> CommandLine(
-        string bwrap, string filterFile, SandboxRequest request, HostLayout host, BwrapFeatures features)
+        string bwrap, string filterFile, SandboxRequest request, HostLayout host, BwrapFeatures features,
+        SandboxHelper? helper = null, LaunchFiles? launch = null)
     {
+        launch ??= LaunchFiles.None;
+        if (request.NeedsLauncher && helper is null)
+            throw new ArgumentException("This run needs the sandbox launcher.");
         var limits = request.Limits;
         var args = new List<string>
         {
@@ -126,7 +165,7 @@ public sealed class BwrapSandbox : ISandboxRunner
             """f=$1; ulimit -v "$2" && ulimit -t "$3" && ulimit -f "$4" && ulimit -n "$5" || exit 126; shift 5; exec "$@" 3<"$f" """,
             "sh",
             filterFile,
-            Kilobytes(limits.MaxMemoryBytes),
+            limits.MaxMemoryBytes > 0 ? Kilobytes(limits.MaxMemoryBytes) : "unlimited",
             ((long)Math.Ceiling(limits.Timeout.TotalSeconds) + 5).ToString(CultureInfo.InvariantCulture),
             Blocks(limits.MaxFileBytes),
             limits.MaxOpenFiles.ToString(CultureInfo.InvariantCulture),
@@ -170,6 +209,28 @@ public sealed class BwrapSandbox : ISandboxRunner
         foreach (var path in request.ReadOnlyPaths)
             args.AddRange(["--ro-bind", Path.GetFullPath(path), Path.GetFullPath(path)]);
 
+        // #712: a runtime's home, the MCP socket — each at its own place, never inside /work,
+        // where it would stand among the files that come back as the run's result.
+        foreach (var mount in request.Mounts)
+        {
+            if (!mount.Target.StartsWith('/') || mount.Target == SandboxPaths.Work
+                || mount.Target.StartsWith(SandboxPaths.Work + "/", StringComparison.Ordinal)
+                || mount.Target.Split('/').Contains(".."))
+                throw new ArgumentException($"'{mount.Target}' is not a place for a mount.");
+            args.AddRange([mount.Writable ? "--bind" : "--ro-bind", Path.GetFullPath(mount.HostPath), mount.Target]);
+        }
+
+        // #712: what the launcher needs — the helper itself, the proxy's socket, the secrets.
+        if (request.NeedsLauncher && helper is not null)
+        {
+            foreach (var path in helper.ReadOnlyPaths)
+                args.AddRange(["--ro-bind", path, path]);
+            if (launch.EgressSocket is { } socket)
+                args.AddRange(["--bind", socket, SandboxPaths.EgressSocket]);
+            if (launch.SecretFile is { } secrets)
+                args.AddRange(["--ro-bind", secrets, SandboxPaths.SecretFile]);
+        }
+
         // The root bwrap builds is a tmpfs of its own — writable unless it is remounted. Only
         // /work and /tmp, each a mount of its own, stay writable.
         args.AddRange(["--remount-ro", "/", "--chdir", SandboxPaths.Work]);
@@ -181,6 +242,18 @@ public sealed class BwrapSandbox : ISandboxRunner
             ["LANG"] = "C.UTF-8",
             ["TMPDIR"] = "/tmp"
         };
+        if (request.NeedsLauncher && helper is not null)
+        {
+            foreach (var (key, value) in helper.Environment)
+                environment[key] = value;
+            if (request.Egress.Count > 0)
+            {
+                // Everything goes to the proxy; the sandbox's loopback has nothing else.
+                var proxy = $"http://127.0.0.1:{SandboxPaths.ProxyPort}";
+                environment["HTTPS_PROXY"] = environment["https_proxy"] = proxy;
+                environment["HTTP_PROXY"] = environment["http_proxy"] = proxy;
+            }
+        }
         foreach (var (key, value) in request.Environment)
             environment[key] = value;
         foreach (var (key, value) in environment.OrderBy(e => e.Key, StringComparer.Ordinal))
@@ -192,7 +265,17 @@ public sealed class BwrapSandbox : ISandboxRunner
         // the process limit, set inside the sandbox's own user namespace. bash calls it -u,
         // dash (Debian's and Ubuntu's sh) -p; if neither takes, nothing runs.
         args.AddRange([Shell, "-c", """exec 3<&-; ulimit -u "$1" 2>/dev/null || ulimit -p "$1" || exit 126; shift; exec "$@" """, "sh",
-            limits.MaxProcesses.ToString(CultureInfo.InvariantCulture), request.Executable]);
+            limits.MaxProcesses.ToString(CultureInfo.InvariantCulture)]);
+        if (request.NeedsLauncher && helper is not null)
+        {
+            args.AddRange([helper.Executable, SandboxLauncher.Argument]);
+            if (request.Egress.Count > 0)
+                args.AddRange([SandboxLauncher.EgressOption, SandboxPaths.EgressSocket]);
+            if (request.SecretEnvironment.Count > 0)
+                args.AddRange([SandboxLauncher.SecretsOption, SandboxPaths.SecretFile]);
+            args.Add("--");
+        }
+        args.Add(request.Executable);
         args.AddRange(request.Arguments);
         return args;
     }
@@ -457,6 +540,12 @@ internal static class Spawner
     }
 }
 
+/// <summary>#712: Files the runner prepared for the launcher, on the host.</summary>
+public sealed record LaunchFiles(string? EgressSocket, string? SecretFile)
+{
+    public static LaunchFiles None { get; } = new(null, null);
+}
+
 /// <summary>#654: What the installed bwrap can do beyond the basics.</summary>
 public sealed record BwrapFeatures(bool DisableUserns, bool ClearEnv)
 {

src/ClawdDotNet.Core/Sandbox/EgressProxy.cs

@@ -0,0 +1,323 @@
+using System.Net;
+using System.Net.Sockets;
+using System.Text;
+using Microsoft.Extensions.Logging;
+
+namespace ClawdDotNet.Core.Sandbox;
+
+/// <summary>
+/// #712/#655: The only way out of a sandbox — an HTTPS proxy in the main process, reached
+/// through a Unix socket that is mounted into the sandbox.
+///
+/// <para><b>Why not share the network.</b> A sandbox on the host's network sees everything
+/// the host sees on loopback: the instance's web port, a database, and — per network
+/// namespace, not per file system — abstract Unix sockets such as an X11 display. The
+/// sandbox keeps a network of its own with nothing but loopback; the launcher inside
+/// relays the proxy port there to this socket (<see cref="SandboxLauncher"/>).</para>
+///
+/// <para><b>What passes.</b> Only <c>CONNECT host:port</c> — a TLS tunnel, nothing in clear
+/// — to a host on the list, and only when every address it resolves to is public. A name
+/// that resolves to loopback or the local network (DNS rebinding) is refused as a whole,
+/// not filtered address by address. Names are resolved here, never in the sandbox.</para>
+/// </summary>
+public sealed class EgressProxy : IDisposable
+{
+    private const int MaxHeaderBytes = 8192;
+    private const int MaxConnections = 32;
+    private static readonly TimeSpan HeaderTimeout = TimeSpan.FromSeconds(10);
+    private static readonly TimeSpan ConnectTimeout = TimeSpan.FromSeconds(15);
+
+    private readonly Socket _listener;
+    private readonly EgressRules _rules;
+    private readonly ILogger _logger;
+    private readonly CancellationTokenSource _stop = new();
+    private readonly SemaphoreSlim _slots = new(MaxConnections);
+    private readonly Func<string, CancellationToken, Task<IPAddress[]>> _resolve;
+    private readonly Func<IPAddress, bool> _mayConnect;
+
+    private EgressProxy(Socket listener, EgressRules rules, ILogger logger,
+        Func<string, CancellationToken, Task<IPAddress[]>>? resolve, Func<IPAddress, bool>? mayConnect)
+    {
+        _listener = listener;
+        _rules = rules;
+        _logger = logger;
+        _resolve = resolve ?? ((host, ct) => Dns.GetHostAddressesAsync(host, ct));
+        _mayConnect = mayConnect ?? IsPublic;
+    }
+
+    /// <summary>What was refused, for the tests and the log: <c>host:port → reason</c>.</summary>
+    public IReadOnlyCollection<string> Refusals => _refusals;
+    private readonly System.Collections.Concurrent.ConcurrentQueue<string> _refusals = new();
+
+    /// <summary>Starts listening on <paramref name="socketPath"/> (0600).</summary>
+    /// <param name="resolve">Name resolution — the tests' way to a local server.</param>
+    /// <param name="mayConnect">Which addresses may be reached; <see cref="IsPublic"/> unless a test says otherwise.</param>
+    public static EgressProxy Start(string socketPath, IReadOnlyList<string> allowed, ILogger logger,
+        Func<string, CancellationToken, Task<IPAddress[]>>? resolve = null, Func<IPAddress, bool>? mayConnect = null)
+    {
+        var listener = new Socket(AddressFamily.Unix, SocketType.Stream, ProtocolType.Unspecified);
+        listener.Bind(new UnixDomainSocketEndPoint(socketPath));
+        if (!OperatingSystem.IsWindows())
+            File.SetUnixFileMode(socketPath, UnixFileMode.UserRead | UnixFileMode.UserWrite);
+        listener.Listen(MaxConnections);
+
+        var proxy = new EgressProxy(listener, EgressRules.Parse(allowed), logger, resolve, mayConnect);
+        _ = proxy.AcceptLoopAsync();
+        return proxy;
+    }
+
+    private async Task AcceptLoopAsync()
+    {
+        while (!_stop.IsCancellationRequested)
+        {
+            Socket client;
+            try
+            {
+                client = await _listener.AcceptAsync(_stop.Token);
+            }
+            catch (Exception) when (_stop.IsCancellationRequested)
+            {
+                return;
+            }
+            catch (SocketException)
+            {
+                continue;
+            }
+
+            if (!await _slots.WaitAsync(0))
+            {
+                client.Dispose();
+                continue;
+            }
+            _ = Task.Run(async () =>
+            {
+                try { await HandleAsync(client); }
+                catch (Exception ex) when (ex is IOException or SocketException or OperationCanceledException or ObjectDisposedException) { }
+                finally
+                {
+                    client.Dispose();
+                    _slots.Release();
+                }
+            });
+        }
+    }
+
+    private async Task HandleAsync(Socket client)
+    {
+        await using var inner = new NetworkStream(client, ownsSocket: false);
+
+        string? head;
+        using (var headTimeout = CancellationTokenSource.CreateLinkedTokenSource(_stop.Token))
+        {
+            headTimeout.CancelAfter(HeaderTimeout);
+            head = await ReadHeadAsync(inner, headTimeout.Token);
+        }
+        if (head is null)
+            return;
+
+        var requestLine = head.Split("\r\n", 2)[0];
+        var parts = requestLine.Split(' ');
+        if (parts.Length != 3 || parts[0] != "CONNECT" || !EgressRules.TrySplit(parts[1], out var host, out var port))
+        {
+            await RefuseAsync(inner, "405 Method Not Allowed", requestLine, "only CONNECT to host:port");
+            return;
+        }
+
+        var target = $"{host}:{port}";
+        if (!_rules.Allows(host, port))
+        {
+            await RefuseAsync(inner, "403 Forbidden", target, "not on the list");
+            return;
+        }
+
+        IPAddress[] addresses;
+        try
+        {
+            addresses = await _resolve(host, _stop.Token);
+        }
+        catch (SocketException)
+        {
+            await RefuseAsync(inner, "502 Bad Gateway", target, "does not resolve");
+            return;
+        }
+        if (addresses.Length == 0 || addresses.Any(a => !_mayConnect(a)))
+        {
+            await RefuseAsync(inner, "403 Forbidden", target, "resolves to a non-public address");
+            return;
+        }
+
+        using var outer = new Socket(SocketType.Stream, ProtocolType.Tcp);
+        using (var connectTimeout = CancellationTokenSource.CreateLinkedTokenSource(_stop.Token))
+        {
+            connectTimeout.CancelAfter(ConnectTimeout);
+            try
+            {
+                await outer.ConnectAsync(addresses, port, connectTimeout.Token);
+            }
+            catch (Exception ex) when (ex is SocketException or OperationCanceledException)
+            {
+                await RefuseAsync(inner, "502 Bad Gateway", target, "cannot connect");
+                return;
+            }
+        }
+
+        _logger.LogInformation("Sandbox egress to {Target}", target);
+        await inner.WriteAsync("HTTP/1.1 200 Connection established\r\n\r\n"u8.ToArray(), _stop.Token);
+        await using var remote = new NetworkStream(outer, ownsSocket: false);
+        await PipeAsync(inner, remote, _stop.Token);
+    }
+
+    private async Task RefuseAsync(Stream inner, string status, string target, string reason)
+    {
+        _refusals.Enqueue($"{target} → {reason}");
+        _logger.LogWarning("Sandbox egress refused: {Target} ({Reason})", target, reason);
+        var body = $"Refused by the sandbox: {reason}.\n";
+        await inner.WriteAsync(Encoding.ASCII.GetBytes(
+            $"HTTP/1.1 {status}\r\nContent-Type: text/plain\r\nContent-Length: {body.Length}\r\nConnection: close\r\n\r\n{body}"), _stop.Token);
+    }
+
+    /// <summary>Reads up to the blank line; <c>null</c> if the head is too long or never ends.</summary>
+    private static async Task<string?> ReadHeadAsync(Stream stream, CancellationToken ct)
+    {
+        var buffer = new byte[MaxHeaderBytes];
+        var length = 0;
+        // Byte by byte: whatever follows the head belongs to the tunnel and must not be swallowed.
+        while (length < buffer.Length)
+        {
+            var read = await stream.ReadAsync(buffer.AsMemory(length, 1), ct);
+            if (read == 0)
+                return null;
+            length++;
+            if (length >= 4 && buffer[length - 4] == '\r' && buffer[length - 3] == '\n'
+                && buffer[length - 2] == '\r' && buffer[length - 1] == '\n')
+                return Encoding.ASCII.GetString(buffer, 0, length);
+        }
+        return null;
+    }
+
+    /// <summary>Both directions until either side ends.</summary>
+    public static async Task PipeAsync(Stream a, Stream b, CancellationToken ct)
+    {
+        using var done = CancellationTokenSource.CreateLinkedTokenSource(ct);
+        var ab = CopyAsync(a, b, done.Token);
+        var ba = CopyAsync(b, a, done.Token);
+        await Task.WhenAny(ab, ba);
+        done.Cancel();
+        try { await Task.WhenAll(ab, ba); }
+        catch (Exception ex) when (ex is IOException or OperationCanceledException or ObjectDisposedException or SocketException) { }
+    }
+
+    private static async Task CopyAsync(Stream from, Stream to, CancellationToken ct)
+    {
+        try
+        {
+            await from.CopyToAsync(to, 81920, ct);
+        }
+        catch (Exception ex) when (ex is IOException or OperationCanceledException or ObjectDisposedException or SocketException) { }
+    }
+
+    /// <summary>
+    /// Whether an address is on the internet — not loopback, not a private or shared range,
+    /// not link-local (where cloud metadata services live), not multicast or reserved.
+    /// </summary>
+    public static bool IsPublic(IPAddress address)
+    {
+        if (address.IsIPv4MappedToIPv6)
+            address = address.MapToIPv4();
+
+        if (address.AddressFamily == AddressFamily.InterNetwork)
+        {
+            var b = address.GetAddressBytes();
+            return !(b[0] == 0 || b[0] == 10 || b[0] == 127
+                || (b[0] == 100 && b[1] >= 64 && b[1] <= 127)      // shared address space (CGNAT)
+                || (b[0] == 169 && b[1] == 254)                     // link-local, metadata
+                || (b[0] == 172 && b[1] >= 16 && b[1] <= 31)
+                || (b[0] == 192 && b[1] == 168)
+                || (b[0] == 192 && b[1] == 0 && b[2] == 0)          // IETF protocol assignments
+                || (b[0] == 198 && (b[1] == 18 || b[1] == 19))      // benchmarking
+                || b[0] >= 224);                                     // multicast, reserved, broadcast
+        }
+
+        if (address.AddressFamily == AddressFamily.InterNetworkV6)
+        {
+            if (IPAddress.IsLoopback(address) || address.Equals(IPAddress.IPv6None)
+                || address.IsIPv6LinkLocal || address.IsIPv6SiteLocal || address.IsIPv6Multicast)
+                return false;
+            var b = address.GetAddressBytes();
+            if ((b[0] & 0xFE) == 0xFC)                               // unique local fc00::/7
+                return false;
+            if (b[0] == 0x00 && b.Take(10).All(x => x == 0))        // unspecified, v4-compatible
+                return false;
+            if (b[0] == 0x20 && b[1] == 0x02)                        // 6to4 wraps any v4 address
+                return false;
+            if (b[0] == 0x00 && b[1] == 0x64 && b[2] == 0xFF && b[3] == 0x9B) // NAT64
+                return false;
+            return true;
+        }
+
+        return false;
+    }
+
+    public void Dispose()
+    {
+        _stop.Cancel();
+        _listener.Dispose();
+    }
+}
+
+/// <summary>#712: The hosts a sandbox may reach.</summary>
+public sealed class EgressRules
+{
+    private readonly List<(string Host, bool Subdomains, int Port)> _entries;
+
+    private EgressRules(List<(string, bool, int)> entries) => _entries = entries;
+
+    /// <summary><c>host</c>, <c>host:port</c> or <c>*.domain</c>; 443 when no port is given.</summary>
+    public static EgressRules Parse(IEnumerable<string> allowed)
+    {
+        var entries = new List<(string, bool, int)>();
+        foreach (var raw in allowed)
+        {
+            var text = raw.Trim().ToLowerInvariant();
+            if (text.Length == 0)
+                continue;
+            var port = 443;
+            if (TrySplit(text, out var h, out var p))
+                (text, port) = (h, p);
+            var subdomains = text.StartsWith("*.", StringComparison.Ordinal);
+            var host = subdomains ? text[2..] : text;
+            if (host.Length == 0 || host.Contains('*') || host.Contains('/'))
+                throw new ArgumentException($"'{raw}' is not a host.");
+            entries.Add((host, subdomains, port));
+        }
+        return new EgressRules(entries);
+    }
+
+    public bool Allows(string host, int port)
+    {
+        host = host.Trim().TrimEnd('.').ToLowerInvariant();
+        // An address literal is never on the list — the list names hosts, and resolving
+        // happens here, where it is checked.
+        if (IPAddress.TryParse(host.Trim('[', ']'), out _))
+            return false;
+        return _entries.Any(e => e.Port == port
+            && (e.Subdomains
+                // *.example.org is its subdomains, not example.org itself — say both if both are meant.
+                ? host.EndsWith("." + e.Host, StringComparison.Ordinal)
+                : host == e.Host));
+    }
+
+    public static bool TrySplit(string authority, out string host, out int port)
+    {
+        host = "";
+        port = 0;
+        var colon = authority.LastIndexOf(':');
+        if (colon <= 0 || authority.EndsWith(']'))
+            return false;
+        if (!int.TryParse(authority[(colon + 1)..], System.Globalization.NumberStyles.None,
+                System.Globalization.CultureInfo.InvariantCulture, out port) || port is < 1 or > 65535)
+            return false;
+        host = authority[..colon];
+        return host.Length > 0;
+    }
+}

src/ClawdDotNet.Core/Sandbox/SandboxLauncher.cs

@@ -0,0 +1,144 @@
+using System.Diagnostics;
+using System.Net;
+using System.Net.Sockets;
+using System.Text.Json;
+
+namespace ClawdDotNet.Core.Sandbox;
+
+/// <summary>
+/// #712: Runs <i>inside</i> the sandbox, in front of the program:
+/// <c>ClawdDotNet --sandbox-launch [--egress SOCKET] [--secrets FILE] -- PROGRAM ARGS…</c>.
+///
+/// <para><b>Network.</b> The sandbox has only loopback. The launcher listens on
+/// <c>127.0.0.1:</c><see cref="SandboxPaths.ProxyPort"/> and carries every connection to the
+/// <see cref="EgressProxy"/> socket; the program finds it through <c>HTTPS_PROXY</c>. It
+/// starts the program only once it listens, so the first request never finds nobody there.</para>
+///
+/// <para><b>Secrets.</b> A key read from a file the runner mounted, set in the program's
+/// environment — a command line would show it to every process of the machine. The
+/// program can read the file, too: it is its own key, and it has to use it.</para>
+///
+/// <para>The program inherits stdin, stdout and stderr; its exit code is the launcher's.</para>
+/// </summary>
+public static class SandboxLauncher
+{
+    public const string Argument = "--sandbox-launch";
+    public const string EgressOption = "--egress";
+    public const string SecretsOption = "--secrets";
+
+    private const int ExitUsage = 125;
+    private const int ExitNotStarted = 127;
+
+    /// <summary>The secrets as the launcher reads them: a JSON object, readable only by its owner.</summary>
+    public static async Task WriteSecretFileAsync(string path, IReadOnlyDictionary<string, string> secrets, CancellationToken ct)
+    {
+        var options = new FileStreamOptions { Mode = FileMode.CreateNew, Access = FileAccess.Write };
+        if (!OperatingSystem.IsWindows())
+            options.UnixCreateMode = UnixFileMode.UserRead | UnixFileMode.UserWrite;
+        await using var stream = new FileStream(path, options);
+        await JsonSerializer.SerializeAsync(stream, secrets, cancellationToken: ct);
+    }
+
+    public sealed record Options(string? EgressSocket, string? SecretFile, string Program, IReadOnlyList<string> Arguments);
+
+    /// <summary>Reads the command line after <see cref="Argument"/>; <c>null</c> if it makes no sense.</summary>
+    public static Options? Parse(IReadOnlyList<string> args)
+    {
+        string? egress = null, secrets = null;
+        var i = 0;
+        while (i < args.Count && args[i] != "--")
+        {
+            switch (args[i])
+            {
+                case Argument: i++; break;
+                case EgressOption when i + 1 < args.Count: egress = args[i + 1]; i += 2; break;
+                case SecretsOption when i + 1 < args.Count: secrets = args[i + 1]; i += 2; break;
+                default: return null;
+            }
+        }
+        if (i + 1 >= args.Count)
+            return null;
+        return new Options(egress, secrets, args[i + 1], args.Skip(i + 2).ToList());
+    }
+
+    public static async Task<int> RunAsync(IReadOnlyList<string> args)
+    {
+        if (Parse(args) is not { } options)
+        {
+            await Console.Error.WriteLineAsync($"Usage: {Argument} [{EgressOption} SOCKET] [{SecretsOption} FILE] -- PROGRAM [ARGS…]");
+            return ExitUsage;
+        }
+
+        using var stop = new CancellationTokenSource();
+        Task? relay = null;
+        if (options.EgressSocket is { } socket)
+        {
+            var listener = new TcpListener(IPAddress.Loopback, SandboxPaths.ProxyPort);
+            listener.Start();
+            relay = RelayAsync(listener, socket, stop.Token);
+        }
+
+        var start = new ProcessStartInfo(options.Program) { UseShellExecute = false };
+        foreach (var argument in options.Arguments)
+            start.ArgumentList.Add(argument);
+        // The launcher's own tuning is not the program's business.
+        start.Environment.Remove("DOTNET_GCHeapHardLimit");
+        if (options.SecretFile is { } file)
+        {
+            var secrets = JsonSerializer.Deserialize<Dictionary<string, string>>(await File.ReadAllTextAsync(file)) ?? [];
+            foreach (var (key, value) in secrets)
+                start.Environment[key] = value;
+        }
+
+        Process process;
+        try
+        {
+            process = Process.Start(start) ?? throw new InvalidOperationException();
+        }
+        catch (Exception ex) when (ex is System.ComponentModel.Win32Exception or InvalidOperationException)
+        {
+            await Console.Error.WriteLineAsync($"Cannot start {options.Program}: {ex.Message}");
+            return ExitNotStarted;
+        }
+
+        using (process)
+        {
+            await process.WaitForExitAsync();
+            stop.Cancel();
+            if (relay is not null)
+                await Task.WhenAny(relay, Task.Delay(1000));
+            return process.ExitCode;
+        }
+    }
+
+    /// <summary>Carries each connection on the sandbox's loopback to the proxy socket.</summary>
+    public static async Task RelayAsync(TcpListener listener, string socketPath, CancellationToken ct)
+    {
+        try
+        {
+            while (!ct.IsCancellationRequested)
+            {
+                var client = await listener.AcceptTcpClientAsync(ct);
+                _ = Task.Run(async () =>
+                {
+                    using (client)
+                    using (var upstream = new Socket(AddressFamily.Unix, SocketType.Stream, ProtocolType.Unspecified))
+                    {
+                        try
+                        {
+                            await upstream.ConnectAsync(new UnixDomainSocketEndPoint(socketPath), ct);
+                            await using var upstreamStream = new NetworkStream(upstream, ownsSocket: false);
+                            await EgressProxy.PipeAsync(client.GetStream(), upstreamStream, ct);
+                        }
+                        catch (Exception ex) when (ex is SocketException or IOException or OperationCanceledException) { }
+                    }
+                }, CancellationToken.None);
+            }
+        }
+        catch (OperationCanceledException) { }
+        finally
+        {
+            listener.Stop();
+        }
+    }
+}

src/ClawdDotNet.Core/Sandbox/SandboxModels.cs

@@ -34,6 +34,75 @@ public sealed record SandboxRequest
     public SandboxLimits Limits { get; init; } = new();
 
     public string? StandardInput { get; init; }
+
+    /// <summary>
+    /// #712: Further host paths at a place of their own — a runtime's home, the MCP socket.
+    /// Applied after the workspace; a target inside <c>/work</c> is refused.
+    /// </summary>
+    public IReadOnlyList<SandboxMount> Mounts { get; init; } = [];
+
+    /// <summary>
+    /// #712/#655: The hosts the run may reach, as <c>host</c> or <c>host:port</c> (443 if
+    /// none), <c>*.example.com</c> for subdomains. Empty: no network at all. Otherwise the
+    /// sandbox still has no network of its own; an HTTPS proxy in the main process opens
+    /// only these, and only to public addresses (<see cref="EgressProxy"/>).
+    /// </summary>
+    public IReadOnlyList<string> Egress { get; init; } = [];
+
+    /// <summary>
+    /// #712: Environment the program needs but that must not stand on a command line — an
+    /// API key. Handed over in a file only the sandbox's launcher reads, never through argv.
+    /// </summary>
+    public IReadOnlyDictionary<string, string> SecretEnvironment { get; init; } = new Dictionary<string, string>();
+
+    /// <summary>Whether the run needs the launcher inside the sandbox (<see cref="SandboxLauncher"/>).</summary>
+    public bool NeedsLauncher => Egress.Count > 0 || SecretEnvironment.Count > 0;
+}
+
+/// <summary>#712: A host path mounted at <paramref name="Target"/> in the sandbox.</summary>
+public sealed record SandboxMount(string HostPath, string Target, bool Writable = false);
+
+/// <summary>
+/// #712: The program that starts the work inside the sandbox when it needs more than an
+/// <c>exec</c> — the application itself, called with <see cref="SandboxLauncher.Argument"/>.
+/// It is mounted read-only with what it needs to start.
+/// </summary>
+public sealed record SandboxHelper(
+    string Executable,
+    IReadOnlyList<string> ReadOnlyPaths,
+    IReadOnlyDictionary<string, string> Environment)
+{
+    /// <summary>
+    /// This application as the helper: its directory, and the .NET it runs on when that is
+    /// not under <c>/usr</c>. <c>null</c> when there is no executable to call (a test host).
+    /// </summary>
+    public static SandboxHelper? ForThisProcess()
+    {
+        var executable = System.Environment.ProcessPath;
+        if (string.IsNullOrEmpty(executable) || !File.Exists(executable))
+            return null;
+        var name = Path.GetFileNameWithoutExtension(executable);
+        return name is "dotnet" or "testhost" ? null : For(executable);
+    }
+
+    /// <summary>The helper at <paramref name="executable"/>, running on the same .NET as this process.</summary>
+    public static SandboxHelper For(string executable)
+    {
+        var paths = new List<string> { Path.GetDirectoryName(Path.GetFullPath(executable))! };
+        var environment = new Dictionary<string, string>(StringComparer.Ordinal)
+        {
+            // .NET reserves address space by the gigabyte; under a memory limit it would not start.
+            ["DOTNET_GCHeapHardLimit"] = "0x20000000",
+            ["DOTNET_CLI_TELEMETRY_OPTOUT"] = "1"
+        };
+        // <root>/shared/Microsoft.NETCore.App/<version>/ — the root is three levels up.
+        var runtime = System.Runtime.InteropServices.RuntimeEnvironment.GetRuntimeDirectory();
+        var root = Path.GetFullPath(Path.Combine(runtime, "..", "..", ".."));
+        if (!root.StartsWith("/usr/", StringComparison.Ordinal) && Directory.Exists(root))
+            paths.Add(root);
+        environment["DOTNET_ROOT"] = root;
+        return new SandboxHelper(Path.GetFullPath(executable), paths, environment);
+    }
 }
 
 /// <summary>#654: The limits of one run.</summary>
@@ -41,7 +110,10 @@ public sealed record SandboxLimits
 {
     public TimeSpan Timeout { get; init; } = TimeSpan.FromMinutes(5);
 
-    /// <summary>Address space per process.</summary>
+    /// <summary>
+    /// Address space per process; 0 for none. A JavaScript runtime (Claude Code) reserves
+    /// tens of gigabytes it never uses and does not start under any sensible limit.
+    /// </summary>
     public long MaxMemoryBytes { get; init; } = 2L * 1024 * 1024 * 1024;
 
     /// <summary>Processes and threads the run may have at once — a fork bomb stops here.</summary>
@@ -109,6 +181,14 @@ public static class SandboxPaths
 {
     public const string Work = "/work";
 
+    /// <summary>#712: Where the launcher finds what the runner hands it.</summary>
+    public const string Run = "/run/clawd";
+    public const string EgressSocket = Run + "/egress.sock";
+    public const string SecretFile = Run + "/env.json";
+
+    /// <summary>#712: The proxy's port on the sandbox's own loopback.</summary>
+    public const int ProxyPort = 3128;
+
     /// <summary>
     /// In the workspace, read-only by default: <c>scripts/</c> holds approved scripts and their
     /// manifests (#695) — what is checked must stay what runs.

src/ClawdDotNet.Core/Security/ConfigSecrets.cs

@@ -54,6 +54,13 @@ public static class ConfigSecrets
         if (config.Watchdog is { } watchdog)
             watchdog.AgentToken = transform(watchdog.AgentToken) ?? "";
 
+        // #712: the Claude Code account — a key with a bill behind it.
+        if (config.ClaudeCode is { } claudeCode)
+        {
+            claudeCode.ApiKey = transform(claudeCode.ApiKey) ?? "";
+            claudeCode.OAuthToken = transform(claudeCode.OAuthToken) ?? "";
+        }
+
         foreach (var agent in config.Agents)
             Apply(agent, transform);
     }

src/ClawdDotNet.Core/Storage/SqliteStorage.cs

@@ -443,6 +443,9 @@ public sealed class SqliteStorage
 
         // #717: Runs that drew on a special budget — outside the daily limits, visible apart.
         SpalteErgaenzen(connection, "RunUsage", "BudgetPot", "TEXT NOT NULL DEFAULT ''");
+        // #712: the runtime, and whether a subscription paid — 0 $ is not "free".
+        SpalteErgaenzen(connection, "RunUsage", "Runtime", "TEXT NOT NULL DEFAULT ''");
+        SpalteErgaenzen(connection, "RunUsage", "OnSubscription", "INTEGER NOT NULL DEFAULT 0");
         SpalteErgaenzen(connection, "RunReceipts", "BudgetPot", "TEXT NULL");
 
         // Findet offene Aufrufe beim Start, ohne die ganze Tabelle zu lesen.

src/ClawdDotNet.Desktop/CommandLine.cs

@@ -35,18 +35,29 @@ internal static class CommandLine
     /// Auswahldialog, ohne Fenster ist es ein Abbruch mit Meldung.</para>
     /// </summary>
     public static string? ReadInstancePath(IReadOnlyList<string>? args)
+        => ReadValue(args, InstanceArgument);
+
+    /// <summary>The value after <paramref name="option"/>, or <c>null</c>.</summary>
+    public static string? ReadValue(IReadOnlyList<string>? args, string option)
     {
         if (args is null) return null;
 
         for (var i = 0; i < args.Count - 1; i++)
         {
-            if (string.Equals(args[i], InstanceArgument, StringComparison.OrdinalIgnoreCase))
+            if (string.Equals(args[i], option, StringComparison.OrdinalIgnoreCase))
                 return args[i + 1];
         }
 
         return null;
     }
 
+    /// <summary>
+    /// #712: The launcher in front of a program inside a sandbox — no application. Only as
+    /// the first argument: everything after <c>--</c> belongs to the program.
+    /// </summary>
+    public static bool IsSandboxLaunch(IReadOnlyList<string>? args)
+        => args is { Count: > 0 } && args[0] == Core.Sandbox.SandboxLauncher.Argument;
+
     /// <summary>#713: Only the stdio bridge to a running instance's MCP server — no application.</summary>
     public static bool IsMcpBridge(IReadOnlyList<string>? args)
         => Has(args, Core.Mcp.McpStdioBridge.Argument);

src/ClawdDotNet.Desktop/McpBridgeRun.cs

@@ -5,7 +5,9 @@ namespace ClawdDotNet.Desktop;
 
 /// <summary>
 /// #713: <c>ClawdDotNet --mcp-bridge --instance &lt;dir&gt;</c> — the instance's MCP server
-/// over stdio, for a runtime that starts its MCP servers as child processes.
+/// over stdio, for a runtime that starts its MCP servers as child processes. In a sandbox
+/// (#712), where there is no instance directory, <c>--socket &lt;path&gt;</c> names the
+/// mounted MCP socket instead.
 ///
 /// <para>No application is built here: no settings, no database, no engine. The bridge
 /// only carries messages to the running instance over its MCP socket; everything is
@@ -19,10 +21,11 @@ internal static class McpBridgeRun
 
     public static async Task<int> RunAsync(string[] args)
     {
+        var socketPath = CommandLine.ReadValue(args, McpStdioBridge.SocketArgument);
         var instancePath = CommandLine.ReadInstancePath(args);
-        if (string.IsNullOrWhiteSpace(instancePath) || !Directory.Exists(instancePath))
+        if (socketPath is null && (string.IsNullOrWhiteSpace(instancePath) || !Directory.Exists(instancePath)))
         {
-            await Console.Error.WriteLineAsync($"Expected {CommandLine.InstanceArgument} <instance directory>.");
+            await Console.Error.WriteLineAsync($"Expected {CommandLine.InstanceArgument} <instance directory> or {McpStdioBridge.SocketArgument} <path>.");
             return ExitNoInstance;
         }
 
@@ -33,7 +36,9 @@ internal static class McpBridgeRun
             return ExitNoToken;
         }
 
-        using var client = InstanceEndpoint.CreateMcpClient(instancePath);
+        using var client = socketPath is not null
+            ? InstanceEndpoint.CreateMcpClientForSocket(socketPath)
+            : InstanceEndpoint.CreateMcpClient(instancePath!);
         using var stdin = new StreamReader(Console.OpenStandardInput());
         await using var stdout = new StreamWriter(Console.OpenStandardOutput()) { AutoFlush = false };
 

src/ClawdDotNet.Desktop/Program.cs

@@ -21,7 +21,9 @@ internal static class Program
     /// ohne Bildschirmsitzung gäbe es keines (#528, Stufe 2).
     /// </remarks>
     public static int Main(string[] args)
-        => CommandLine.IsMcpBridge(args)
+        => CommandLine.IsSandboxLaunch(args)
+            ? Core.Sandbox.SandboxLauncher.RunAsync(args).GetAwaiter().GetResult()
+            : CommandLine.IsMcpBridge(args)
             ? McpBridgeRun.RunAsync(args).GetAwaiter().GetResult()
             : CommandLine.IsHeadless(args)
                 ? HeadlessRun.RunAsync(args).GetAwaiter().GetResult()

src/ClawdDotNet.Manager.Web/wwwroot/app.css

@@ -869,6 +869,21 @@ button.klein {
   min-width: 0;
 }
 
+/* #712: the runtime card */
+.laufzeit-feld {
+  display: grid;
+  gap: 6px;
+}
+
+.laufzeit-feld[hidden],
+.laufzeit-konto[hidden] {
+  display: none;
+}
+
+.laufzeit-konto {
+  margin-top: 12px;
+}
+
 .mcp-token-inaktiv {
   opacity: 0.55;
 }

src/ClawdDotNet.Manager.Web/wwwroot/i18n/de.json

@@ -945,5 +945,42 @@
   "mcp.configHint": "In die .mcp.json des Projekts, in dem du arbeitest. Sie enthält das Token: die Datei nicht in die Versionsverwaltung aufnehmen.",
   "mcp.copy": "Kopieren",
   "mcp.copied": "Kopiert.",
-  "mcp.copyFailed": "Kopieren ist hier nicht erlaubt — Text markieren und von Hand kopieren."
+  "mcp.copyFailed": "Kopieren ist hier nicht erlaubt — Text markieren und von Hand kopieren.",
+
+  "runtime.title": "Laufzeit",
+  "runtime.hint": "Native Läufe nutzen unsere Engine mit OpenRouter. Eine fremde Laufzeit arbeitet in der Sandbox auf einer Kopie des Arbeitsbereichs: Was sie ändert, kommt als Vorschlag zurück und wird nie von selbst übernommen. Taskboard und Kollegen erreicht sie nur über den MCP-Server dieser Instanz.",
+  "runtime.kind": "Laufzeit",
+  "runtime.kind.native": "Nativ (OpenRouter)",
+  "runtime.kind.claude-code": "Claude Code",
+  "runtime.kind.command": "Befehl",
+  "runtime.allowedTools": "Erlaubte Werkzeuge",
+  "runtime.allowedToolsHint": "Durch Komma getrennt. Leer: Read, Edit, Write, Glob, Grep und der MCP-Server. Was nicht aufgeführt ist, wird abgelehnt; Webzugriff immer.",
+  "runtime.maxTurns": "Züge je Lauf",
+  "runtime.timeoutMinutes": "Zeitgrenze (Minuten)",
+  "runtime.command": "Befehl",
+  "runtime.commandHint": "Absolut, im PATH der Sandbox oder relativ zum Arbeitsbereich. Die Nachricht kommt über stdin; was der Befehl ausgibt, ist das Ergebnis.",
+  "runtime.arguments": "Argumente",
+  "runtime.argumentsHint": "Eines je Zeile.",
+  "runtime.egress": "Erreichbare Hosts",
+  "runtime.egressHint": "Einer je Zeile, z. B. api.example.com oder *.example.com:8443. Nur HTTPS, nur öffentliche Adressen. Die API von Claude Code ist immer dabei.",
+  "runtime.saved": "Laufzeit von {name} gespeichert.",
+  "runtime.failed": "Fehlgeschlagen: {error}",
+  "runtime.sandboxReady": "Die Sandbox ist bereit.",
+  "runtime.sandboxMissing": "Keine Sandbox auf dieser Maschine – fremde Laufzeiten laufen nicht: {reason}",
+  "runtime.account": "Claude-Code-Konto",
+  "runtime.accountHint": "Ein Konto für die ganze Instanz. Voreinstellung ist der API-Schlüssel; ein Abo teilt sein Kontingent mit dir, und ob es ein Agentensystem betreiben darf, regeln seine Bedingungen. Schlüssel werden verschlüsselt gespeichert und nie wieder angezeigt.",
+  "runtime.installedAt": "installiert unter {path}",
+  "runtime.notInstalled": "nicht installiert",
+  "runtime.authApiKey": "API-Schlüssel",
+  "runtime.authSubscription": "Abo",
+  "runtime.keyStored": "Schlüssel hinterlegt",
+  "runtime.keyMissing": "noch kein Schlüssel",
+  "runtime.editAccount": "Bearbeiten",
+  "runtime.executable": "Programm",
+  "runtime.auth": "Anmeldung",
+  "runtime.apiKey": "API-Schlüssel",
+  "runtime.oauthToken": "Abo-Token",
+  "runtime.oauthTokenHint": "Erzeugt mit 'claude setup-token' auf einem Rechner, an dem du angemeldet bist.",
+  "runtime.keepStored": "hinterlegt – leer lassen zum Behalten",
+  "runtime.accountSaved": "Claude-Code-Konto gespeichert."
 }

src/ClawdDotNet.Manager.Web/wwwroot/i18n/en.json

@@ -945,5 +945,42 @@
   "mcp.configHint": "Put this into the .mcp.json of the project you work in. It contains the token: keep the file out of version control.",
   "mcp.copy": "Copy",
   "mcp.copied": "Copied.",
-  "mcp.copyFailed": "Copying is not allowed here — select the text and copy it by hand."
+  "mcp.copyFailed": "Copying is not allowed here — select the text and copy it by hand.",
+
+  "runtime.title": "Runtime",
+  "runtime.hint": "Native runs use our engine with OpenRouter. A foreign runtime works in the sandbox on a copy of the workspace: what it changes comes back as a proposal and is never applied by itself. It reaches the taskboard and colleagues only through this instance's MCP server.",
+  "runtime.kind": "Runtime",
+  "runtime.kind.native": "Native (OpenRouter)",
+  "runtime.kind.claude-code": "Claude Code",
+  "runtime.kind.command": "Command",
+  "runtime.allowedTools": "Allowed tools",
+  "runtime.allowedToolsHint": "Comma-separated. Empty: Read, Edit, Write, Glob, Grep and the MCP server. Anything not listed is denied; web access is always denied.",
+  "runtime.maxTurns": "Turns per run",
+  "runtime.timeoutMinutes": "Time limit (minutes)",
+  "runtime.command": "Command",
+  "runtime.commandHint": "Absolute, on the sandbox's PATH, or relative to the workspace. The message arrives on stdin; what the command prints is the result.",
+  "runtime.arguments": "Arguments",
+  "runtime.argumentsHint": "One per line.",
+  "runtime.egress": "Reachable hosts",
+  "runtime.egressHint": "One per line, e.g. api.example.com or *.example.com:8443. Only HTTPS, only public addresses. Claude Code's API is always included.",
+  "runtime.saved": "Runtime of {name} saved.",
+  "runtime.failed": "Failed: {error}",
+  "runtime.sandboxReady": "The sandbox is ready.",
+  "runtime.sandboxMissing": "No sandbox on this machine — foreign runtimes do not run: {reason}",
+  "runtime.account": "Claude Code account",
+  "runtime.accountHint": "One account for the whole instance. The API key is the default; a subscription shares its quota with you, and whether it may run an agent system is up to its terms. Keys are stored encrypted and never shown again.",
+  "runtime.installedAt": "installed at {path}",
+  "runtime.notInstalled": "not installed",
+  "runtime.authApiKey": "API key",
+  "runtime.authSubscription": "Subscription",
+  "runtime.keyStored": "key stored",
+  "runtime.keyMissing": "no key yet",
+  "runtime.editAccount": "Edit",
+  "runtime.executable": "Program",
+  "runtime.auth": "Sign-in",
+  "runtime.apiKey": "API key",
+  "runtime.oauthToken": "Subscription token",
+  "runtime.oauthTokenHint": "Created with 'claude setup-token' on a machine where you are signed in.",
+  "runtime.keepStored": "stored — leave empty to keep",
+  "runtime.accountSaved": "Claude Code account saved."
 }

src/ClawdDotNet.Manager.Web/wwwroot/views/agents.js

@@ -6,6 +6,7 @@ import { api } from "../modules/api.js";
 import { abonnieren } from "../modules/events.js";
 import { t } from "../modules/i18n.js";
 import { erstelleMcpKarte } from "./mcp-access.js";
+import { erstelleLaufzeitKarte } from "./runtime.js";
 import {
   erstelleElement,
   erstelleIcon,
@@ -331,7 +332,8 @@ async function rendereDetails(agentId) {
   const berichtswegKarte = erstelleKarte(t("agents.reportingLine"), [berichtswegText, verschaerfenZeile]);
 
   // #713: A human's own client working as this agent, through the MCP server.
-  detailContainer.append(basisKarte, werkzeugeKarte, berichtswegKarte, erstelleMcpKarte(agent));
+  // #712: native, or a foreign runtime in the sandbox.
+  detailContainer.append(basisKarte, werkzeugeKarte, berichtswegKarte, erstelleLaufzeitKarte(agent), erstelleMcpKarte(agent));
 }
 
 function oeffneNeuerAgentDialog() {

src/ClawdDotNet.Manager.Web/wwwroot/views/runtime.js

@@ -0,0 +1,180 @@
+// ClawdDotNet — where an agent's runs happen (#712)
+//
+// Native is our engine with OpenRouter. A foreign runtime (Claude Code, a command) runs in
+// the sandbox, on a copy of the workspace; what it changes comes back as a proposal and is
+// never applied by itself. Its only way to the taskboard and to colleagues is our MCP server.
+
+import { api } from "../modules/api.js";
+import { t } from "../modules/i18n.js";
+import { erstelleElement, erstelleKarte, erstelleModal, zeigeMeldung } from "../modules/dom.js";
+
+const liste = (text) => text.split(/[\n,]/).map((x) => x.trim()).filter((x) => x.length > 0);
+
+/** The card for one agent: its runtime and, for Claude Code, the instance's account. */
+export function erstelleLaufzeitKarte(agent) {
+  const laufzeit = agent.runtime || { kind: "native", allowedTools: [], maxTurns: 30, timeoutMinutes: 30, command: "", arguments: [], egress: [] };
+  const lage = erstelleElement("p", { klasse: "gedaempft text-klein" });
+  const konto = erstelleElement("div", { klasse: "laufzeit-konto" });
+
+  const art = erstelleElement("select", { "aria-label": t("runtime.kind") });
+  for (const kind of ["native", "claude-code", "command"]) {
+    art.append(erstelleElement("option", { value: kind, text: t(`runtime.kind.${kind}`) }));
+  }
+  art.value = laufzeit.kind;
+
+  const werkzeuge = erstelleElement("textarea", { rows: "2", placeholder: "Read, Edit, Write, Glob, Grep, mcp__clawd" });
+  werkzeuge.value = (laufzeit.allowedTools || []).join(", ");
+  const zuege = erstelleElement("input", { type: "number", min: "1", max: "500", value: String(laufzeit.maxTurns || 30) });
+  const minuten = erstelleElement("input", { type: "number", min: "1", max: "240", value: String(laufzeit.timeoutMinutes || 30) });
+  const befehl = erstelleElement("input", { type: "text", value: laufzeit.command || "", placeholder: "scripts/run.sh" });
+  const argumente = erstelleElement("textarea", { rows: "2" });
+  argumente.value = (laufzeit.arguments || []).join("\n");
+  const ziele = erstelleElement("textarea", { rows: "2", placeholder: "api.example.com" });
+  ziele.value = (laufzeit.egress || []).join("\n");
+
+  const feld = (schluessel, element, hinweis) => erstelleElement("div", { klasse: "laufzeit-feld", "data-feld": schluessel },
+    erstelleElement("label", { text: t(`runtime.${schluessel}`) }),
+    element,
+    hinweis ? erstelleElement("div", { klasse: "gedaempft text-klein", text: hinweis }) : null);
+
+  const felder = {
+    werkzeuge: feld("allowedTools", werkzeuge, t("runtime.allowedToolsHint")),
+    zuege: feld("maxTurns", zuege),
+    minuten: feld("timeoutMinutes", minuten),
+    befehl: feld("command", befehl, t("runtime.commandHint")),
+    argumente: feld("arguments", argumente, t("runtime.argumentsHint")),
+    ziele: feld("egress", ziele, t("runtime.egressHint"))
+  };
+
+  const sichtbar = () => {
+    const kind = art.value;
+    const fremd = kind !== "native";
+    felder.werkzeuge.hidden = kind !== "claude-code";
+    felder.zuege.hidden = kind !== "claude-code";
+    felder.minuten.hidden = !fremd;
+    felder.befehl.hidden = kind !== "command";
+    felder.argumente.hidden = kind !== "command";
+    felder.ziele.hidden = !fremd;
+    konto.hidden = kind !== "claude-code";
+  };
+  art.addEventListener("change", sichtbar);
+
+  const speichern = erstelleElement("button", {
+    type: "button",
+    klasse: "schaltflaeche primaer",
+    text: t("common.save"),
+    onclick: async () => {
+      speichern.disabled = true;
+      const eingabe = {
+        kind: art.value,
+        allowedTools: liste(werkzeuge.value),
+        maxTurns: Number(zuege.value) || 30,
+        timeoutMinutes: Number(minuten.value) || 30,
+        command: befehl.value.trim(),
+        arguments: argumente.value.split("\n").map((x) => x.trim()).filter((x) => x.length > 0),
+        egress: liste(ziele.value)
+      };
+      try {
+        await api(`/agents/${encodeURIComponent(agent.agentId)}/runtime`, { method: "PUT", body: eingabe });
+        agent.runtime = eingabe;
+        zeigeMeldung(t("runtime.saved", { name: agent.displayName }), "info");
+      } catch (err) {
+        zeigeMeldung(t("runtime.failed", { error: err.message }), "gefahr");
+      } finally {
+        speichern.disabled = false;
+      }
+    }
+  });
+
+  async function lade() {
+    try {
+      const stand = await api("/runtimes");
+      lage.textContent = stand.sandboxAvailable
+        ? t("runtime.sandboxReady")
+        : t("runtime.sandboxMissing", { reason: stand.sandboxReason || "" });
+      zeigeKonto(stand.claudeCode);
+    } catch (err) {
+      lage.textContent = err.message;
+    }
+  }
+
+  function zeigeKonto(claude) {
+    const anmeldung = claude.auth === "subscription" ? t("runtime.authSubscription") : t("runtime.authApiKey");
+    const schluessel = claude.auth === "subscription" ? claude.hasOAuthToken : claude.hasApiKey;
+    konto.replaceChildren(
+      erstelleElement("div", { klasse: "werkzeug-zeile" },
+        erstelleElement("div", { klasse: "werkzeug-info" },
+          erstelleElement("strong", { text: t("runtime.account") }),
+          erstelleElement("div", {
+            klasse: "werkzeug-beschreibung gedaempft",
+            text: [
+              claude.located ? t("runtime.installedAt", { path: claude.located }) : t("runtime.notInstalled"),
+              anmeldung,
+              schluessel ? t("runtime.keyStored") : t("runtime.keyMissing")
+            ].join(" · ")
+          })),
+        erstelleElement("div", { klasse: "werkzeug-aktionen" },
+          erstelleElement("button", {
+            type: "button",
+            klasse: "schaltflaeche flach klein",
+            text: t("runtime.editAccount"),
+            onclick: () => bearbeiteKonto(claude, lade)
+          }))));
+  }
+
+  sichtbar();
+  lade();
+
+  return erstelleKarte(t("runtime.title"), [
+    erstelleElement("p", { klasse: "gedaempft", text: t("runtime.hint") }),
+    lage,
+    erstelleElement("div", { klasse: "formular-raster" },
+      erstelleElement("label", { text: t("runtime.kind") }), art,
+      felder.werkzeuge, felder.zuege, felder.minuten, felder.befehl, felder.argumente, felder.ziele),
+    konto,
+    erstelleElement("div", { klasse: "modal-fuss" }, speichern)
+  ]);
+}
+
+/** The instance's Claude Code account: program, sign-in, key. A key is only ever replaced. */
+function bearbeiteKonto(claude, danach) {
+  const programm = erstelleElement("input", { type: "text", value: claude.executable || "", placeholder: claude.located || "~/.local/bin/claude" });
+  const anmeldung = erstelleElement("select");
+  anmeldung.append(
+    erstelleElement("option", { value: "api-key", text: t("runtime.authApiKey") }),
+    erstelleElement("option", { value: "subscription", text: t("runtime.authSubscription") }));
+  anmeldung.value = claude.auth || "api-key";
+  const schluessel = erstelleElement("input", { type: "password", autocomplete: "off", placeholder: claude.hasApiKey ? t("runtime.keepStored") : "" });
+  const token = erstelleElement("input", { type: "password", autocomplete: "off", placeholder: claude.hasOAuthToken ? t("runtime.keepStored") : "" });
+
+  const modal = erstelleModal(t("runtime.account"), erstelleElement("div", {},
+    erstelleElement("p", { klasse: "gedaempft text-klein", text: t("runtime.accountHint") }),
+    erstelleElement("div", { klasse: "formular-raster" },
+      erstelleElement("label", { text: t("runtime.executable") }), programm,
+      erstelleElement("label", { text: t("runtime.auth") }), anmeldung,
+      erstelleElement("label", { text: t("runtime.apiKey") }), schluessel,
+      erstelleElement("label", { text: t("runtime.oauthToken") }), token,
+      erstelleElement("div", { klasse: "gedaempft text-klein", text: t("runtime.oauthTokenHint") }))
+  ), [
+    erstelleElement("button", { type: "button", klasse: "schaltflaeche flach", text: t("common.cancel"), onclick: () => modal.schliessen() }),
+    erstelleElement("button", {
+      type: "button",
+      klasse: "schaltflaeche primaer",
+      text: t("common.save"),
+      onclick: async () => {
+        try {
+          await api("/runtimes/claude-code", {
+            method: "PUT",
+            body: { executable: programm.value.trim(), auth: anmeldung.value, apiKey: schluessel.value, oauthToken: token.value }
+          });
+          zeigeMeldung(t("runtime.accountSaved"), "info");
+          modal.schliessen();
+          await danach();
+        } catch (err) {
+          zeigeMeldung(t("runtime.failed", { error: err.message }), "gefahr");
+        }
+      }
+    })
+  ]);
+  modal.oeffnen();
+}

src/ClawdDotNet.Web/Contracts/Dtos.cs

@@ -55,7 +55,37 @@ public sealed record AgentDto(
     IReadOnlyList<AgentToolDto> Tools,
     // #715: What makes the agent read foreign content — its tools, or "setting". Empty: standard tier.
     IReadOnlyList<string> ForeignContentSources,
-    bool TreatAsForeignReader);
+    bool TreatAsForeignReader,
+    // #712
+    AgentRuntimeDto Runtime);
+
+/// <summary>#712: Where an agent's runs happen.</summary>
+public sealed record AgentRuntimeDto(
+    string Kind,
+    IReadOnlyList<string> AllowedTools,
+    int MaxTurns,
+    int TimeoutMinutes,
+    string Command,
+    IReadOnlyList<string> Arguments,
+    IReadOnlyList<string> Egress);
+
+/// <summary>#712: What foreign runtimes find on this machine — never a key, only whether there is one.</summary>
+public sealed record RuntimesDto(
+    bool SandboxAvailable,
+    string? SandboxReason,
+    IReadOnlyList<string> Kinds,
+    IReadOnlyList<string> DefaultAllowedTools,
+    ClaudeCodeDto ClaudeCode);
+
+public sealed record ClaudeCodeDto(
+    string Executable,
+    string? Located,
+    string Auth,
+    bool HasApiKey,
+    bool HasOAuthToken);
+
+/// <summary>#712: Changes to the Claude Code account. Empty keys keep the stored ones.</summary>
+public sealed record ClaudeCodeInputDto(string? Executable, string? Auth, string? ApiKey, string? OAuthToken);
 
 /// <summary>
 /// Ein Werkzeug am Agenten. <b>Ohne die Einstellungen</b> — die stehen in einem freien

src/ClawdDotNet.Web/Contracts/Mapping.cs

@@ -43,7 +43,23 @@ internal static class Mapping
                     tools?.Invoke(name)?.ReadsForeignContent == true))
                 .ToList(),
             tools is null ? [] : Core.Organisation.ReportingLine.TrustOf(agent, tools).Sources,
-            agent.TreatAsForeignReader);
+            agent.TreatAsForeignReader,
+            agent.Runtime.ToDto());
+
+    public static AgentRuntimeDto ToDto(this Core.Runtimes.AgentRuntimeConfig runtime)
+        => new(Core.Runtimes.RuntimeKinds.Normalize(runtime.Kind), runtime.AllowedTools, runtime.MaxTurns,
+            runtime.TimeoutMinutes, runtime.Command, runtime.Arguments, runtime.Egress);
+
+    public static Core.Runtimes.AgentRuntimeConfig ToConfig(this AgentRuntimeDto dto) => new()
+    {
+        Kind = dto.Kind ?? Core.Runtimes.RuntimeKinds.Native,
+        AllowedTools = [.. dto.AllowedTools ?? []],
+        MaxTurns = dto.MaxTurns,
+        TimeoutMinutes = dto.TimeoutMinutes,
+        Command = dto.Command ?? "",
+        Arguments = [.. dto.Arguments ?? []],
+        Egress = [.. dto.Egress ?? []]
+    };
 
     /// <summary>
     /// Die Einstellungen eines Werkzeugs — <b>ohne die Geheimnisse</b>.

src/ClawdDotNet.Web/Endpoints/ApiEndpoints.cs

@@ -134,6 +134,30 @@ internal static class ApiEndpoints
         agents.MapDelete("/{agentId}", (AppHost host, string agentId) =>
             host.AgentAdmin.Remove(agentId).ToResponse());
 
+        // #712: the runtime — native, or foreign in the sandbox.
+        agents.MapPut("/{agentId}/runtime", (AppHost host, string agentId, AgentRuntimeDto input) =>
+            host.AgentAdmin.SetRuntime(agentId, input.ToConfig()).ToResponse());
+
+        var runtimes = api.MapGroup("/runtimes");
+        runtimes.MapGet("/", (AppHost host) =>
+        {
+            var sandbox = host.Engine?.Sandbox;
+            var claude = host.Instance.ClaudeCode;
+            return new RuntimesDto(
+                sandbox?.IsAvailable ?? false,
+                sandbox?.UnavailableReason ?? (sandbox is null ? "no engine" : null),
+                Core.Runtimes.RuntimeKinds.All,
+                Core.Runtimes.ClaudeCodeRuntime.DefaultAllowedTools,
+                new ClaudeCodeDto(
+                    claude.Executable,
+                    Core.Runtimes.ClaudeCodeRuntime.Locate(claude),
+                    claude.Auth,
+                    !string.IsNullOrWhiteSpace(claude.ApiKey),
+                    !string.IsNullOrWhiteSpace(claude.OAuthToken)));
+        });
+        runtimes.MapPut("/claude-code", (AppHost host, ClaudeCodeInputDto input) =>
+            host.AgentAdmin.SetClaudeCode(input.Executable, input.Auth, input.ApiKey, input.OAuthToken).ToResponse());
+
         // #715: Can only tighten — the tools decide the tier, this adds to it.
         agents.MapPut("/{agentId}/foreign-reader", (AppHost host, string agentId, bool value) =>
             host.AgentAdmin.SetTreatAsForeignReader(agentId, value).ToResponse());