Skip to content

Team publishing and deployment preparation

Workrun has two separate workspace modes. Personal mode is for building and running on your own computer; team mode uses Workrun Server to share, review, and use published versions. Choosing team mode does not deploy workflows to the server: workflows still run in each member’s desktop app. The team service manages identity, shared assets, and published versions.

Your saved local workflows can also be reused from the Team-mode homepage without publishing. Publishing shares a version with other members. See Architecture and the Server, LiteLLM, and Langfuse deployment guide.

Personal mode Team mode
Best for Exploration, local development, and independent runs Collaborative workflows that need sharing, review, and reproducibility
Data and assets Stored in the current device’s personal workspace Current account drafts are local; releases and shared metadata are stored on Server
Sign-in and server No sign-in or team service required Requires a team-service connection and sign-in
Execution The desktop app runs local Workflows and Apps The desktop app runs its local definitions or shared releases, preparing pinned Apps for releases
Publishing Save a draft and continue editing Publish semantic versions for members to browse, run, and schedule

Choose Personal mode or Team mode when you first launch Workrun.

After choosing Personal mode, fill out your profile and start using Workrun locally. You do not need to deploy or connect a Workrun Server.

Personal mode: complete your profile to start working locally.

After choosing Team mode, enter the Workrun Server address supplied by your team and sign in. Use the team’s public HTTPS address—not a container-internal address or localhost on another member’s computer.

Team mode: enter the Workrun Server address to continue.

After connecting to the service, sign in with your team account to access shared Workflows, Apps, and published releases.

Team mode: sign in to the team workspace after connecting to Workrun Server.

The modes are not two views of the same assets. A local Workflow or App in personal mode is not automatically shared when you switch to team mode. Create or migrate collaborative assets in team mode, then publish them as versions. You can review or switch modes later in Settings → Workspace; save any current draft before switching.

Settings → Workspace: switch between Personal mode and Team mode.

Team mode requires an accessible Workrun Server. It is the collaboration control plane, not a remote executor that replaces a member’s computer for Python Apps, model calls, or workflow runs.

Run history, chat sessions, and generated artifacts remain on the device that executes the run, isolated by Personal/Team workspace. Team publishing shares Workflow and App versions without synchronizing these run records or files. Switching devices does not automatically restore earlier local results; see File results and local storage.

After connecting to the team service and signing in, team members can browse and run published workflows. Workrun uses semantic versions for Workflows and Apps at publish time.

A published Workflow pins the versions of its Team Apps. Before a run, the desktop app prepares an isolated App copy instead of reading a development version that was changed later. Historical runs, evaluations, and production behavior can therefore be tied to—and reproduced from—the version actually used.

  1. In Settings → Workspace, connect to the team service and sign in.
  2. Confirm that local Apps referenced by the workflow are installed, and publish a version of every App that needs sharing first.
  3. Run required evaluation suites and inspect the quality gate, cost, duration, and failed cases.
  4. Select Publish in the workflow editor, then confirm the semantic version and release note.
  5. Have another member browse or run the published version to verify the team service exposes the intended asset.

Before publishing, complete three checks:

  • Run critical evaluation suites and confirm the quality-gate result.
  • Verify that referenced Apps, models, and tool permissions are what you intend.
  • Write down what changed in this version and how to migrate any incompatible change.
  • Team members run a published release from the team workspace; later draft edits do not silently change that run.
  • Team-mode schedules use published definitions, following the recipe’s latest-published or pinned-release policy.
  • Publish a new version to fix a problem or update a dependency. Do not alter an old version to repair history.
  • If a run reports a missing or mismatched Team App release, restore that release before retrying instead of substituting the current development copy.

Self-hosted team service: deployment preparation

Section titled “Self-hosted team service: deployment preparation”

Team mode relies on Workrun Server for its service capabilities. Its backend source lives in apps/server and manages authentication, shared Workflow/App releases, related resources, and optional LiteLLM model access; desktop editing drafts are local to the current account; it depends on MongoDB and Better Auth. Before enabling team mode, deploy Workrun Server to an address members can reach and connect to that address in the desktop app’s Settings → Workspace.

Plan the deployment boundary as follows:

Workrun desktop apps ── HTTPS ──> reverse proxy / Workrun Server ──> MongoDB (persistent storage)
└──> OAuth providers (optional)
  1. Provide a stable HTTPS address, such as https://workrun.example.com; members connect to it in Settings → Workspace.
  2. Prepare a MongoDB connection string and persistent storage. Recreating containers must not lose team users, drafts, releases, or file resources.
  3. Generate and securely retain BETTER_AUTH_SECRET; never use an example value in production. Keep it unchanged during migration or scaling to preserve existing sessions.
  4. Set both SERVER_BASE_URL and BETTER_AUTH_URL to the public HTTPS address, not a container address or localhost. If GitHub sign-in is enabled, register the same callback base with the provider.
  5. Keep MONGODB_URI, OAuth client secrets, and authentication secrets in secret management or an uncommitted environment file—not in images, deployment configuration, or the repository.
  6. Terminate TLS at the reverse proxy and expose only required service ports. Keep MongoDB on a private network rather than exposing it to the internet.

The current source of truth for configuration is apps/server/.env.example and apps/server/src/env.validation.ts. Configure the runtime environment from those definitions when deploying.

  • Sign in through the public team URL and verify the session from a second member’s device.
  • Create and publish a test App and Workflow; confirm a second member can browse and run the intended release.
  • Verify that App resources download and that pinned dependencies of a published Workflow can be prepared.
  • Restart the Server container and verify that users, published releases, and resources persist.
  • Rehearse restoration of MongoDB data and file resources before storing real team assets.

Personal App and Workflow sharing uses ZIP/TAR packages. A Workflow package includes its local App and child-Workflow dependencies, while external services must be configured on the receiving device. See Use Python Apps and Build your first workflow.

Archive sharing does not migrate objects into the Team workspace or create Team releases. Team Workflows continue to use Publish and pinned Team App versions. The author can delete a Team Workflow from its detail-page More (⋯) menu; other members do not see the deletion action.