Run on Plue

run-on-plue executes a Smithers workflow script on Plue infrastructure instead of locally, via the <Sandbox> provider seam and createPlueSandboxProvider, which shells through the plue CLI so Plue owns workspace lifecycle, authentication, quotas, placement, and execution through its self-hosted Microsandbox plane. Use it when a child workflow needs a real Plue workspace: a repo-bound VM with SSH, git, jj, Node, network egress, and bootstrapped Claude Code and Codex CLIs.

What it does

The workflow lives at .smithers/workflows/run-on-plue.tsx: it accepts a path to any Smithers .tsx workflow, reads it, and sends it to a Plue-backed sandbox provider. The provider:

Creates a Plue workspace with plue workspace create --repo <owner>/<repo>.
Polls plue workspace view --format json until running with an SSH command.
Connects over SSH in batch mode.
Installs Bun, then the Claude Code and Codex CLIs, when missing.
Seeds Claude and Codex auth for the remote CLIs.
Ships a small remote project containing the child workflow source, agents.ts, package.json, and input.json.
Runs smthrs up in the workspace and reads the remote run result back over SSH.
Deletes the workspace unless keepWorkspace is true.

The parent workflow receives:

{
  status: "finished" | "failed" | "cancelled";
  output?: unknown;
  remoteRunId?: string;
  workspaceId?: string;
}

Requirements

plue CLI installed and authenticated on the host running Smithers. Verify with plue auth status.
The target Plue server must have workspaces enabled (SMITHERS_FEATURE_FLAGS_WORKSPACES=true locally) and be configured for real workspaces with SMITHERS_SANDBOX_PROVIDER=microsandbox plus an authenticated Microsandbox controller.
The repo passed as repo must exist in Plue and be accessible to the authenticated user.
Claude and Codex auth must be available locally: prefer Claude Code subscription OAuth in the OS credential store (ANTHROPIC_API_KEY only works with usable API billing) and ~/.codex/auth.json (OPENAI_API_KEY is only a fallback for setups where the Codex CLI honors API-key auth).
If plue is not on PATH, set PLUE_BIN or pass plueBin in the workflow input.

Secrets are seeded at run time through Plue’s operation-scoped secret or credential-proxy path: never write Claude, Codex, OpenAI, Anthropic, Microsandbox, or proxy credentials into guest disks, snapshots, images, command arguments, logs, errors, durable request state, or committed files.

Run a workflow remotely

Run the included demo child workflow:

bunx smthrs up .smithers/workflows/run-on-plue.tsx --input '{
  "script": ".smithers/workflows/plue-demo-child.tsx",
  "repo": "alice/smoke-test"
}'

Pass input through to the remote child:

bunx smthrs up .smithers/workflows/run-on-plue.tsx --input '{
  "script": "workflows/review-child.tsx",
  "repo": "acme/app",
  "input": {
    "ticketId": "APP-123"
  }
}'

Use a local or custom CLI binary and keep the workspace for inspection:

bunx smthrs up .smithers/workflows/run-on-plue.tsx --input '{
  "script": ".smithers/workflows/plue-demo-child.tsx",
  "repo": "alice/smoke-test",
  "plueBin": "/path/to/plue",
  "keepWorkspace": true
}'

Use the provider directly

run-on-plue is the default wrapper, but workflows can pass the provider object to <Sandbox> directly:

/** @jsxImportSource smthrs */
import { createSmithers } from "smthrs";
import { Sandbox } from "@smthrs/components";
import { createPlueSandboxProvider } from "../lib/plue-provider";
import { childWorkflow } from "./child";
import { z } from "zod/v4";

const { Workflow, smithers, outputs } = createSmithers({
  result: z.object({ summary: z.string() }),
});

const provider = createPlueSandboxProvider({
  repo: "acme/app",
  keepWorkspace: false,
});

export default smithers((ctx) => (
  <Workflow name="remote-child">
    <Sandbox
      id="plue-run"
      provider={provider}
      workflow={childWorkflow}
      input={{ prompt: ctx.input.prompt }}
      output={outputs.result}
      reviewDiffs={false}
      timeoutMs={30 * 60_000}
    />
  </Workflow>
));

Non-interactive caveat

Keep reviewDiffs={false} for Plue runs: <Sandbox> defaults to fail-closed diff review, which expects a local approval interaction before applying file changes, but the v1 Plue provider is non-interactive. It runs the remote child, maps the result into the parent run, and opens no human approval loop inside the VM. Design child workflows to return structured output or artifacts. To inspect the remote VM after a failure, run with keepWorkspace: true and connect with plue workspace view or plue workspace ssh.

Claude and Codex bootstrap

Remote workspaces may not have all agent CLIs preinstalled, so the provider bootstraps them idempotently:

When missing, bun installs from the official installer, and claude (bun i -g @anthropic-ai/claude-code) and codex (bun i -g @openai/codex) install via Bun.
~/.bun/bin is prepended to PATH for remote commands.
plue workspace exec --seed-agent-auth claude,codex stages Claude Code and Codex credentials before the child workflow runs.

The remote mini-project’s agents.ts exports both ClaudeCodeAgent and CodexAgent, so child workflows can use either CLI once bootstrap completes.

Start

Articles

Learn

Capabilities

Build Workflows

Run and Operate

Workflow Pack

Components

Integrations

Agent Support

Examples

Contributing

Run on Plue

Run on Plue

What it does

Requirements

Run a workflow remotely

Use the provider directly

Non-interactive caveat

Claude and Codex bootstrap

​Run on Plue

​What it does

​Requirements

​Run a workflow remotely

​Use the provider directly

​Non-interactive caveat

​Claude and Codex bootstrap

Run on Plue

What it does

Requirements

Run a workflow remotely

Use the provider directly

Non-interactive caveat

Claude and Codex bootstrap